7c7c60e969
All checks were successful
Test and Publish Templates / test-and-publish (push) Successful in 45s
147 lines
4.5 KiB
Plaintext
147 lines
4.5 KiB
Plaintext
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 |