dropshell-templates/squashdisplay

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
------------
* Supported systems:
  - Raspberry Pi with Raspberry Pi OS
  - Intel Mac Mini with Ubuntu Server
  - Other x86_64 systems with Ubuntu
* Docker installed (for running setup)
* Internet connection for package installation
* Target URL to display
* HDMI or DisplayPort output

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/Chrome in kiosk mode
6. Disables screen blanking and power management
7. Optional watchdog to restart browser if it crashes
8. System-specific optimizations:
   - Raspberry Pi: GPU memory allocation, update disabling
   - Ubuntu/Mac Mini: Intel GPU optimizations

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 (will auto-detect system type)
3. Confirm system modifications when prompted
4. REBOOT the system: sudo reboot
5. System will auto-start in kiosk mode

The installer will automatically detect if you're running on:
- Raspberry Pi (ARM-based)
- Ubuntu on x86_64 (Mac Mini or PC)
If detection fails, you'll be prompted to select manually.

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