# 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**: Debian Trixie
- **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 |