Squash Display Kiosk Template ============================== This template configures a Raspberry Pi or Linux system as a dedicated kiosk display that automatically boots to a fullscreen web browser showing a specified URL. IMPORTANT: This template makes SYSTEM-LEVEL changes to the host machine, including installing packages, configuring auto-login, and modifying system services. REQUIREMENTS ------------ * Raspberry Pi or Linux system with HDMI output * Fresh Raspberry Pi OS Lite installation (recommended) * Docker installed (for running setup) * Internet connection for package installation * Target URL to display WHAT IT DOES ------------ This template automates the complete kiosk setup process: 1. Installs required packages (Chromium, X server, utilities) 2. Creates/configures kiosk user account 3. Sets up auto-login on boot 4. Configures X server to start automatically 5. Launches Chromium in kiosk mode 6. Disables screen blanking and power management 7. Optional watchdog to restart browser if it crashes 8. Configures GPU memory for better performance (RPi) CONFIGURATION ------------- Key settings in service.env: * KIOSK_URL - The webpage to display (required) * KIOSK_USER - System user for kiosk (default: squash) * DISPLAY_WIDTH/HEIGHT/REFRESH - Display resolution * GPU_MEM - GPU memory allocation in MB (RPi only) * ENABLE_WATCHDOG - Auto-restart crashed browser * ENABLE_AUTO_LOGIN - Boot directly to kiosk * ENABLE_HDMI_KEEP_ALIVE - Prevent display sleep INSTALLATION ------------ 1. Configure your settings in the service configuration 2. Run: ./install.sh 3. Confirm system modifications when prompted 4. REBOOT the system: sudo reboot 5. System will auto-start in kiosk mode The installation uses a privileged Docker container to make the necessary system changes. This is intentional and required. USAGE ----- After installation and reboot: - System boots directly to kiosk display - No keyboard/mouse needed for normal operation - Browser runs in fullscreen kiosk mode - Automatic recovery from crashes (if watchdog enabled) COMMANDS -------- * ./install.sh - Install and configure kiosk * ./status.sh - Check kiosk and configuration status * ./configure.sh - Update kiosk settings (URL, display, etc.) * ./logs.sh - View setup and system logs * ./uninstall.sh - Remove Docker container (not system changes) * ./start.sh - Re-run setup (rarely needed) * ./stop.sh - Stop setup container MANUAL TESTING -------------- To test the kiosk without rebooting: sudo -u squash startx /home/squash/kiosk.sh To exit kiosk mode during testing: Alt+F4 or Ctrl+Alt+Backspace TROUBLESHOOTING --------------- 1. Black screen after reboot: - Check X server: ps aux | grep X - View logs: journalctl -u getty@tty1 - Check script: cat /home/squash/kiosk.sh 2. Browser won't start: - Test manually: chromium-browser - Check logs: ./logs.sh - Verify packages: dpkg -l | grep chromium 3. Wrong resolution: - Check available modes: xrandr - Update settings: ./configure.sh - Verify HDMI connection 4. Page doesn't load: - Check network: ping google.com - Test URL: curl YOUR_URL - Verify in browser: chromium-browser YOUR_URL 5. Screen goes to sleep: - Check power settings: xset q - Verify HDMI service: systemctl status hdmi-keep-alive CUSTOMIZATION ------------- To modify kiosk behavior: 1. Edit /home/squash/kiosk.sh for browser options 2. Edit /home/squash/.bashrc for startup behavior 3. Use ./configure.sh to update URL and display settings SECURITY NOTES -------------- * Kiosk mode disables many browser security features * No authentication required for physical access * Consider network isolation for public displays * Regular updates still recommended for security UNINSTALLING ------------ The uninstall.sh script only removes the Docker container. To fully remove kiosk configuration: 1. Remove auto-login: sudo rm /etc/systemd/system/getty@tty1.service.d/autologin.conf 2. Remove kiosk scripts: rm /home/squash/kiosk.sh /home/squash/watchdog.sh 3. Re-enable updates: sudo systemctl enable apt-daily.service apt-daily.timer 4. Remove packages (optional): sudo apt remove chromium-browser xorg xinit unclutter 5. Remove user (optional): sudo userdel -r squash