Initial release v0.01 — SeniorNet kiosk browser

- PyQt5 floating toolbar (Back, Forward, HOME, Bookmarks) over Google Chrome - Scrollable bookmarks bar with nested folder dropdown menus - Chrome DevTools Protocol (CDP) for navigation control - Home screen with large senior-friendly buttons (Gmail, Google, Weather, News, Facebook, Messenger, YouTube) - Automatic GPU/ML cache cleanup on every Chrome launch - Kiosk hardening: TTY switching blocked, keyboard shortcuts intercepted, auto-restart on crash - System config files and install script included
2026-05-21 11:39:10 +00:00
commit 6c756e3adc
9 changed files with 1086 additions and 0 deletions
@@ -0,0 +1,121 @@
+# SeniorNet Kiosk — v0.01
+
+A fully locked-down, zero-maintenance browser kiosk for senior users running on Ubuntu 24.04 LTS Server.
+
+## Overview
+
+The kiosk presents a single Chrome browser window with a custom floating toolbar. Seniors see only large, friendly navigation buttons and bookmarks — no browser UI, no address bar, no settings. Everything is managed remotely over SSH or Cockpit.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────┐
+│  SeniorNet Toolbar (PyQt5 overlay — always on top)  │
+│  [ < Back ]  [ Forward > ]  [ HOME ]  [ Bookmarks ] │
+├─────────────────────────────────────────────────────┤
+│  Bookmarks Bar (scrollable, nested folder menus)    │
+├─────────────────────────────────────────────────────┤
+│                                                     │
+│           Google Chrome (--app mode)                │
+│         No browser UI — content only                │
+│                                                     │
+└─────────────────────────────────────────────────────┘
+```
+
+- **OS**: Ubuntu 24.04 LTS Server (minimal, headless)
+- **Display**: X11 + LightDM (auto-login) + Openbox WM
+- **Browser**: Google Chrome in `--app` mode (no tabs/address bar)
+- **Toolbar**: PyQt5 frameless overlay, always-on-top, 142px tall
+- **Browser control**: Chrome DevTools Protocol (CDP) over WebSocket on port 9222
+- **Remote management**: SSH + Cockpit (port 9091)
+- **Remote access**: Headscale (self-hosted Tailscale)
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `browser.py` | Main application — PyQt5 overlay + CDP Chrome controller |
+| `bookmarks.json` | Nested bookmarks (folders + links) shown in the bookmarks bar |
+| `/home/jgitta/kiosk-home/index.html` | Home screen with large buttons and live clock |
+
+## System Configuration Files
+
+| Path | Purpose |
+|------|---------|
+| `/etc/lightdm/lightdm.conf.d/50-kiosk.conf` | Auto-login as jgitta into Openbox session |
+| `~/.config/openbox/autostart` | Launches browser.py at session start, auto-restarts on crash |
+| `/etc/X11/xorg.conf.d/50-kiosk-hardening.conf` | Blocks TTY switching and Ctrl+Alt+Backspace |
+| `/etc/apt/apt.conf.d/20auto-upgrades` | Automatic unattended security updates |
+
+## Chrome Launch Flags
+
+Chrome is launched with these key flags:
+
+```
+--app=<HOME_URL>          # No browser UI, content only
+--window-position=0,142   # Below the 142px overlay
+--window-size=1920,938    # Full width, remaining height
+--remote-debugging-port=9222  # CDP for toolbar control
+--disable-gpu             # Required on server hardware (no GPU drivers)
+--disable-dev-shm-usage   # Prevents shared memory crash
+--test-type               # Suppresses unsupported-flag warning banner
+--disable-features=OptimizationHints,...  # Prevents ML model cache corruption
+--disable-component-update  # No background component downloads
+--user-data-dir=~/.config/google-chrome-kiosk  # Dedicated kiosk profile
+```
+
+## Hardening
+
+- **TTY switching blocked**: `/etc/X11/xorg.conf.d/50-kiosk-hardening.conf` sets `DontVTSwitch`
+- **X kill blocked**: `DontZap` prevents Ctrl+Alt+Backspace
+- **tty2–tty6 disabled**: `systemctl disable getty@tty2..6`
+- **Keyboard shortcuts blocked**: Overlay intercepts Alt+F4, Ctrl+W, Ctrl+T, Ctrl+N, F11, Escape
+- **Auto-restart**: Openbox autostart restarts browser.py within 5 seconds if it crashes
+- **Profile cleanup**: GPU/ML caches wiped on every Chrome launch to prevent corruption
+
+## Bookmarks
+
+Bookmarks are stored in `bookmarks.json` as nested JSON. Top-level items appear as buttons in the bookmarks bar. Items with a `children` array become folder dropdown menus.
+
+```json
+[
+  {"name": "Gmail", "url": "https://mail.google.com"},
+  {"name": "News", "children": [
+    {"name": "BBC News", "url": "https://www.bbc.com/news"}
+  ]}
+]
+```
+
+Edit bookmarks live through the **Bookmarks** button in the toolbar, or edit `bookmarks.json` directly via SSH.
+
+## Home Screen Buttons
+
+Defined in `/home/jgitta/kiosk-home/index.html`:
+
+- Email (Gmail)
+- Internet (Google)
+- Weather (AccuWeather)
+- News
+- Facebook
+- Facebook Messenger
+- YouTube
+
+## Remote Management
+
+- **SSH**: `ssh jgitta@192.168.88.44` (local) or `ssh jgitta@kiosk-remote` (via Tailscale)
+- **Cockpit**: `https://192.168.88.44:9091`
+
+## Installation Summary
+
+1. Install Ubuntu 24.04 LTS Server (minimal)
+2. Install packages: `python3-pyqt5 google-chrome-stable unclutter xorg openbox lightdm fonts-noto-color-emoji websocket-client`
+3. Configure LightDM for auto-login
+4. Copy `kiosk-browser/` and `kiosk-home/` to `/home/jgitta/`
+5. Place system config files (see table above)
+6. Reboot
+
+## Version History
+
+| Version | Date | Notes |
+|---------|------|-------|
+| 0.01 | 2026-05-21 | Initial release — working kiosk with toolbar, bookmarks, hardening |