Create Readme.md

2025-11-23 16:43:33 -05:00
parent 515af15c03
commit 3322b281ce
1 changed files with 209 additions and 0 deletions
@@ -0,0 +1,209 @@
+# UBK (Ubuntu Based Kiosk) — Installer README
+
+## 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.
+
+---
+
+## Quick Install
+
+```
+sudo chmod +x install_kiosk_0.9.7.sh
+sudo ./install_kiosk_0.9.7.sh
+```
+
+The installer will prompt for required configuration values during setup.
+
+---
+
+## What This Script Installs
+
+### Core Components
+
+* **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
+
+* **Squeezelite** for audio playback
+* ALSA utilities for device enumeration
+
+### 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
+
+### Security & Lockdown
+
+* Autologin kiosk user
+* Disabled TTY switching
+* Suppressed right-click behavior
+* Screen blanking disabled
+* Config permission hardening
+
+---
+
+## Licensing — Third‑Party Software Attribution
+
+This project bundles or installs several upstream open-source components. Their licenses apply to their respective software. UBK itself does **not** modify these licenses.
+
+Below are SPDX-style license identifiers and project attribution references.
+
+### Electron
+
+* **License:** MIT
+* **Project:** [https://github.com/electron/electron](https://github.com/electron/electron)
+* **SPDX:** `MIT`
+
+### Chromium
+
+* **License:** BSD-3-Clause, plus multiple third-party components
+* **Project:** [https://www.chromium.org/](https://www.chromium.org/)
+* **SPDX:** `BSD-3-Clause`
+
+### Node.js
+
+* **License:** MIT
+* **Project:** [https://github.com/nodejs/node](https://github.com/nodejs/node)
+* **SPDX:** `MIT`
+
+### npm Packages
+
+Most npm modules used by the kiosk app are MIT, Apache-2.0, or similar permissive licenses. Check your app’s `package.json` for exact listings.
+
+### CUPS
+
+* **License:** Apache-2.0 (CUPS 2.2+) with GPL2/LGPL2 exceptions on older versions
+* **Project:** [https://openprinting.github.io/cups/](https://openprinting.github.io/cups/)
+* **SPDX:** `Apache-2.0`
+
+### Squeezelite
+
+* **License:** GPL-3.0-or-later
+* **Project:** [https://github.com/ralph-irving/squeezelite](https://github.com/ralph-irving/squeezelite)
+* **SPDX:** `GPL-3.0-or-later`
+
+### ffmpeg
+
+* **License:** LGPL-2.1-or-later / GPL-2.0-or-later depending on build
+* **Project:** [https://ffmpeg.org/](https://ffmpeg.org/)
+* **SPDX:** `LGPL-2.1-or-later` (typical Ubuntu build)
+
+### unclutter
+
+* **License:** Public Domain / MIT (depending on fork)
+* **Project:** [https://github.com/Airblader/unclutter-xfixes](https://github.com/Airblader/unclutter-xfixes)
+* **SPDX:** `MIT`
+
+---
+
+## Maintenance Guide
+
+### Updating the Electron Kiosk App
+
+1. Switch to the kiosk user or app directory.
+2. Pull new code.
+3. Rebuild the Electron application.
+4. Restart kiosk systemd service:
+
+```
+sudo systemctl restart ubk-kiosk.service
+```
+
+### Checking Service Status
+
+```
+systemctl status ubk-kiosk.service
+systemctl status squeezelite.service
+systemctl status display-manager
+```
+
+### Logs
+
+Logs are stored under:
+
+```
+/var/log/ubk/
+```
+
+---
+
+## Troubleshooting
+
+### Kiosk app doesn’t start
+
+* Check Openbox autostart files.
+* Verify `electron` binary is installed.
+* View systemd logs:
+
+```
+sudo journalctl -u ubk-kiosk.service -f
+```
+
+### No audio output
+
+* Use ALSA utilities to list devices.
+* Confirm squeezelite is running.
+
+### Printer not detected
+
+* Ensure CUPS is active:
+
+```
+sudo systemctl status cups
+```
+
+* Verify permissions on `/etc/cups/printers.conf`.
+
+---
+
+## Security Notes
+
+* Autologin is intentionally enabled.
+* TTY switching via Ctrl+Alt+Fx is disabled.
+* Shell access is restricted for the kiosk user.
+* System updates should be applied manually or through automation you trust.
+
+---
+
+## Disclaimer
+
+UBK aggregates open-source software governed by their respective licenses. The authors of UBK make no warranty regarding modifications made by downstream integrators.
+
+---
+
+## Project Status
+
+This installer is part of an evolving kiosk system. Future versions may include additional lockdown measures, network watchdogs, or health monitoring.
+
+---
+
+# End of README