From 0eacdaca79e8e5ad1aa1460d7f367006670d61b0 Mon Sep 17 00:00:00 2001 From: outis1one Date: Sun, 23 Nov 2025 18:54:18 -0500 Subject: [PATCH] Update Readme.md --- Readme.md | 756 +++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 576 insertions(+), 180 deletions(-) diff --git a/Readme.md b/Readme.md index 2a4ca88..8f1f654 100644 --- a/Readme.md +++ b/Readme.md @@ -1,247 +1,643 @@ -### UBK (Ubuntu Based Kiosk) — Installer README +# Ubuntu Based Kiosk (UBK) -Built with Claude Sonnet 4/.5 AI assistance -License: GPL v3 - Keep derivatives open source -Repository: https://github.com/outis1one/ubk/ +**Current Version:** 0.9.7 (check script header for latest version) +**Built with Claude Sonnet 4/.5 AI assistance** +**License:** GPL v3 - Keep derivatives open source +**Repository:** https://github.com/outis1one/ubk/ + +--- + +## Target Systems -## TARGET SYSTEMS: - Ubuntu 24.04+ Server (minimal install recommended) -- Raspberry Pi 4+ (with or without touchscreen) -- untested +- Raspberry Pi 4+ (with or without touchscreen) - *untested* - Laptops, desktops, all-in-ones, 2-in-1s - Touch support optional (works with keyboard/mouse) -# SECURITY NOTICE: -This is NOT suitable for secure locations or public kiosks. -Do NOT use as a replacement for hardened kiosk solutions. -Use entirely at your own risk. +--- + +## ⚠️ Security Notice + +**This is NOT suitable for secure locations or public kiosks.** + +- Do NOT use as a replacement for hardened kiosk solutions +- Designed for home/office/trusted environments only +- Use entirely at your own risk +- No warranty or security guarantees provided + +--- + +## Purpose -# PURPOSE: Home/office kiosk for reusing old hardware, displaying: -- Self-hosted services (Immich, MagicMirror2, Home Assistant) -- Web dashboards, digital signage -- Photo slideshows, family calendars + +- Self-hosted services (Immich, MagicMirror2, Home Assistant, Plex, Jellyfin, Emby) +- Web dashboards and digital signage +- Photo slideshows and family calendars +- Video conferencing (Jitsi, Zoom, Google Meet) - Any web-based content -## Overview -UBK is a full kiosk environment built on Ubuntu, designed for locked‑down, single‑purpose deployments. This installer (`install_kiosk_0.9.7.sh`) automates setup of the entire system, including: - -* Electron-based kiosk application -* Autologin kiosk user environment -* System lockdown (no shell access, no switching TTYs) -* Display configuration and Openbox session -* Audio playback via Squeezelite -* Printing support via CUPS -* Optional networking, WiFi, and hostname configuration -* Systemd services for all kiosk components - -The script is intended for fresh installations and can fully provision a kiosk from a clean Ubuntu machine. - -## Functionality -- single or multiple sites, with auto rotation, and manual sites not in rotation -- ability to pause a rotational site, auto return to home popup for manual sites -- password protection -- Squeezelite player -- Cups printing -- touch screen controls (two finger swiping between sites, toggable on screen keyboard and pause site) - +--- ## Quick Install -``` -install ubuntu 24.04 server, config wifi if no ethernet is available and enable ssh -sudo chmod +x install_kiosk_0.9.7.sh -sudo ./install_kiosk_0.9.7.sh +```bash +# Install Ubuntu 24.04 Server +# Configure WiFi if no ethernet available +# Enable SSH during installation + +# Download and run installer +wget https://github.com/outis1one/ubk/raw/main/install_kiosk_0.9.7.sh +chmod +x install_kiosk_0.9.7.sh +./install_kiosk_0.9.7.sh ``` -The installer will prompt for required configuration values during setup. +The installer will guide you through configuration during setup. + +--- + +## Core Features + +### Multi-Site Management +- **Single or multiple sites** with independent configurations +- **Auto-rotation** - Sites rotate automatically based on duration +- **Manual sites** - Duration = 0, accessible via swipe only +- **Hidden sites** - Duration = -1, PIN-protected access +- **Home URL** - Auto-return after inactivity on other sites +- **Pause functionality** - Temporarily pause rotation (configurable per-site) + +### Touch Controls +- **2-finger horizontal swipe** - Switch between sites +- **3-finger up swipe** - Access hidden tabs (PIN required) +- **1-finger swipe** (dual mode) - Navigate within page (arrow keys) +- **On-screen keyboard** - Auto-shows on text fields or click keyboard icon + +### On-Screen Keyboard +- **HTML-based keyboard** with full QWERTY layout +- **Auto-show on text fields** (optional) +- **30-second auto-close** after inactivity +- **Shift/Caps Lock support** +- **Special characters** via shift keys +- Works alongside physical keyboard + +### Password Protection & Lockout +- **Session lockout** after configured inactivity +- **Scheduled lockout** at specific time daily +- **Display wake lockout** - Require password after display schedule +- **Boot password** option - Require password on system startup +- **SHA-256 hashed passwords** +- **Full screen blocking** during lockout (no content visible) + +### Navigation Security +- **Restricted** - Exact URL only, no link clicking +- **Same-origin** - Links within same domain only (recommended) +- **Open** - Unrestricted browsing (trusted environments only) + +### Scheduling System +- **Power schedule** - Auto-shutdown and RTC wake (hardware dependent) +- **Display schedule** - Turn display off/on at specific times +- **Quiet hours** - Mute audio or stop Squeezelite during hours +- **Electron reload** - Periodic restart to prevent memory leaks + +### Media Playback Intelligence +- **Auto-detects playing media** (HTML5 video/audio, YouTube, Plex, Jellyfin, Emby) +- **Pauses rotation** during media playback +- **Grace period** after media stops +- **Respects user activity** while watching + +--- + +## Optional Add-ons + +### Audio +- **Lyrion Music Server (LMS)** - Formerly Logitech Media Server +- **Squeezelite Player** - Network audio player for LMS +- **PipeWire audio** - Modern Linux audio stack +- **Volume controls** - Hardware button support + +### Printing +- **CUPS printing system** +- **Network printer sharing** +- **IPP Everywhere support** +- **PDF printing** via cups-pdf + +### Remote Access +- **VNC** - x11vnc for remote desktop +- **WireGuard VPN** - Config paste support +- **Tailscale VPN** - Auth key support +- **Netbird VPN** - Setup key support + +### Advanced +- **Emergency WiFi Hotspot** - Auto-starts if no internet after boot +- **SSH remote access** - For configuration and troubleshooting --- ## What This Script Installs ### Core Components +- **Electron** v33.4.11 (Chromium-based app framework) +- **Node.js** v20.x with npm +- **Openbox** - Lightweight window manager +- **LightDM** - Display manager with autologin +- **xorg** - X11 server and utilities +- **unclutter** - Hide mouse cursor +- **Hardware acceleration** - VAAPI, Mesa drivers -* **Electron runtime and build toolchain** -* **Node.js / npm** and required modules -* **Chromium** and supporting libraries -* **ChromeDriver** (for Electron builds or testing) -* **ffmpeg** for multimedia support -* **unclutter** to hide the cursor -* **Openbox** for lightweight X session -* **x11-xserver-utils** +### Audio Stack +- **PipeWire** - Modern audio/video server +- **PipeWire-Pulse** - PulseAudio compatibility +- **WirePlumber** - Session manager +- **ALSA** utilities -### Audio +### System Services +- **systemd-timesyncd** - NTP time sync +- **acpid** - Power button handling +- **ufw** - Uncomplicated Firewall +- **Network Manager** or netplan for networking -* **Squeezelite** for audio playback -* ALSA utilities for device enumeration +### Development Tools +- **build-essential** - GCC, make, etc. +- **Python 3** with evdev for PTT +- **jq** - JSON processing -### Printing +--- -* **CUPS** printing system -* Printer permissions and service configuration - -### System Services & Environment - -* Kiosk autostart under Openbox -* Systemd units for: - - * Kiosk application - * Squeezelite - * Keyboard IPC handler - * Autostart helpers +## System Behavior ### Security & Lockdown +- **Autologin** as kiosk user +- **VT switching disabled** (Ctrl+Alt+F1-F12 blocked) +- **X server key combinations disabled** (Ctrl+Alt+Backspace) +- **Right-click disabled** in kiosk app +- **Screen blanking disabled** with schedule awareness +- **DPMS management** - Aggressive keep-alive with schedule respect -* Autologin kiosk user -* Disabled TTY switching -* Suppressed right-click behavior -* Screen blanking disabled -* Config permission hardening +### Audio Management +- **PipeWire watchdog** - Auto-restart if audio fails +- **Volume persistence** - Speakers 100%, Mic 100% and unmuted +- **Quiet hours aware** - Respects audio schedules +- **User services** - Audio runs under kiosk user + +### Network +- **WiFi configuration** - WPA2, netplan-based +- **Multi-method WiFi scan** - nmcli, iw, wpa_cli fallbacks +- **Watchdog support** - Auto-revert bad WiFi configs +- **Emergency hotspot** - Fallback if no internet --- -## Licensing — Third‑Party Software Attribution +## Maintenance & Troubleshooting -This project bundles or installs several upstream open-source components. Their licenses apply to their respective software. UBK itself does **not** modify these licenses. +### Service Management + +```bash +# Restart kiosk display +sudo systemctl restart lightdm + +# View Electron logs +sudo tail -f /home/kiosk/electron.log + +# Check service status +systemctl status lightdm +systemctl status squeezelite +sudo systemctl --user -M kiosk@ status pipewire +``` + +### Common Issues + +**No display after boot:** +```bash +# Check LightDM status +sudo journalctl -u lightdm -n 50 + +# Verify kiosk user +id kiosk + +# Check X11 authorization +sudo -u kiosk DISPLAY=:0 xdpyinfo +``` + +**Audio not working:** +```bash +# Check PipeWire (use menu: Advanced → Audio Diagnostics) +sudo -u kiosk pactl info + +# Restart audio +sudo systemctl restart lightdm +``` + +**Touch not working:** +```bash +# List input devices +xinput list + +# Check Electron logs for touch events +sudo tail -f /home/kiosk/electron.log | grep TOUCH +``` + +**Keyboard not appearing:** +```bash +# Check keyboard button setting +sudo grep enableKeyboardButton /home/kiosk/kiosk-app/config.json + +# View keyboard events +sudo tail -f /home/kiosk/electron.log | grep KEYBOARD +``` + +### Adding Printers to CUPS + +**1. Access CUPS Web Interface:** +``` +http://:631/admin +``` +Login with the username and password you used during Ubuntu installation. + +**2. Click "Add Printer"** + +**3. Find Your Printer URI** + +CUPS needs a device URI to connect to your printer. Here's how to find it: + +**For Network Printers (Most Common):** + +From Windows, find the printer's URI: +1. Right-click printer → **Printer Properties** → **Ports** tab +2. Look for the checked port, note the format: + +**HP Network Printers:** +- Windows shows: `IP_192.168.1.100` or similar +- CUPS URI: `hp:/net/?ip=192.168.1.100` +- Alternative: `socket://192.168.1.100:9100` + +**Generic Network Printers (IPP):** +- Windows shows: `http://192.168.1.100/ipp/print` or similar +- CUPS URI: `ipp://192.168.1.100/ipp/print` +- Alternative: `http://192.168.1.100:631/ipp/print` + +**Generic Network Printers (Socket/JetDirect):** +- Windows shows: `Standard TCP/IP Port` on `192.168.1.100` +- CUPS URI: `socket://192.168.1.100:9100` +- Port 9100 is standard for HP JetDirect protocol + +**USB Printers:** +- CUPS auto-detects these +- URI looks like: `usb://HP/LaserJet%20P1102` +- Select from "Local Printers" list in CUPS + +**4. Select Driver** + +After entering URI, CUPS will ask for a driver: +- Search for your printer model +- If not found, try "Generic PCL" or "Generic PostScript" +- For HP printers, install `hplip`: `sudo apt install hplip` + +**5. Set as Default (Optional)** + +Administration → Set Default Printer + +**6. Print Test Page** + +Printers → Your Printer → Maintenance → Print Test Page + +**Quick Reference - Common URIs:** +```bash +# HP Network Printer +hp:/net/HP_LaserJet_P3015?ip=192.168.1.100 + +# Generic Network (Socket/JetDirect - Port 9100) +socket://192.168.1.100:9100 + +# Generic Network (IPP) +ipp://192.168.1.100/ipp/print + +# Shared Windows Printer +smb://WORKGROUP/COMPUTER/PrinterName +``` + +**Troubleshooting:** +- **Printer not responding:** Check firewall, ensure kiosk can ping printer IP +- **Wrong driver:** Try Generic PostScript or PCL drivers +- **Authentication failed:** Verify Windows printer sharing is enabled +- **Can't find printer:** Use `lpinfo -v` to list all available devices + +### Menu System Access + +```bash +# Run installer script again to access menu +./install_kiosk_0.9.7.sh + +# Menu structure: +# 1. Core Settings - Sites, WiFi, schedules, passwords +# 2. Addons - LMS, CUPS, VNC, VPNs +# 3. Advanced - Diagnostics, logs, Electron updates +# 4. Restart Kiosk Display +``` + +### Updating Electron + +```bash +# Via menu: Advanced → Manual Electron Update +# Or manually: +cd /home/kiosk/kiosk-app +sudo -u kiosk npm install electron@latest +sudo systemctl restart lightdm +``` + +--- + +## Configuration Files + +### Main Config +`/home/kiosk/kiosk-app/config.json` +```json +{ + "autoswitch": true, + "swipeMode": "dual", + "allowNavigation": "same-origin", + "homeTabIndex": 0, + "inactivityTimeout": 120, + "enablePauseButton": true, + "enableKeyboardButton": true, + "enablePasswordProtection": false, + "tabs": [ + { + "url": "https://example.com", + "duration": 180, + "username": "", + "password": "" + } + ] +} +``` + +### Key Config Values +- **duration**: `>0` = auto-rotate (seconds), `0` = manual only, `-1` = hidden +- **swipeMode**: `"dual"` = 2-finger nav + 1-finger arrows, `"standard"` = 2-finger only +- **allowNavigation**: `"restricted"` | `"same-origin"` | `"open"` +- **homeTabIndex**: Tab to return to after inactivity (`-1` = disabled) +- **inactivityTimeout**: Seconds before showing "still here?" prompt +- **lockoutTimeout**: Minutes of inactivity before lockout (0 = disabled) +- **lockoutAtTime**: Daily lockout time in `"HH:MM"` format +- **requirePasswordOnBoot**: `true` = password required on system startup + +**Note:** Config files may contain `lockoutActiveStart` and `lockoutActiveEnd` fields from earlier versions. These are not currently functional and are ignored by the application. + +--- + +## Advanced Features + +### Site Duration Modes + +**Auto-Rotate (duration > 0):** +- Site displays for specified seconds +- Auto-advances to next rotation site +- Pause button available +- Respects media playback + +**Manual Only (duration = 0):** +- Site accessible via swipe +- Never auto-rotates +- No pause button (not needed) +- Can be set as Home URL + +**Hidden (duration = -1):** +- Accessible via 3-finger up swipe + PIN +- PIN stored in `/home/kiosk/kiosk-app/.jitsi-pin` +- Default PIN: 1234 +- Hidden from normal rotation + +### Inactivity Extensions + +When "Are you still here?" prompt appears: +- **"Yes, I'm still here"** - Reset all timers, stay on current page +- **Time extensions** (15m, 30m, 1h, 2h) - Pause rotation and inactivity +- **"No, go home"** - Return to home URL immediately +- Extensions pause BOTH rotation and lockout timers +- Maximum extension: 4 hours (safety timeout) + +### Lockout Behavior + +**Triggers:** +- Inactivity timeout expires (if configured) +- Scheduled lockout time reached (if configured) +- Display schedule wake-up (if password-on-wake enabled) +- System boot (if requirePasswordOnBoot enabled) + +**During Lockout:** +- Full black screen (no content visible) +- All browser views detached for security +- Password prompt displayed +- Limited power menu (no Reload option to prevent bypass) +- Rotation and timers paused + +**After Unlock:** +- Returns to previous site +- Timers reset +- Normal operation resumes + +### Media Detection + +Detects and pauses for: +- HTML5 `