docs: Add Raspberry Pi setup documentation - #301
Conversation
Adds comprehensive Raspberry Pi setup guides including: - Custom image creation - Quick deploy script - Autostart setup - Production setup - VMware testing guide
There was a problem hiding this comment.
Pull request overview
This PR adds comprehensive Raspberry Pi setup documentation for the SnackAttack application, including automated deployment scripts and testing guides. The documentation covers multiple deployment scenarios from quick setup to production-ready configurations.
Key Changes:
- Automated deployment scripts for Raspberry Pi OS Lite
- Complete setup documentation for custom image creation
- VMware/VirtualBox testing guide for development without hardware
- Production optimization scripts with health checks and backups
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 15 comments.
Show a summary per file
| File | Description |
|---|---|
| rpi-setup/README.md | Main documentation hub with quick start guide, architecture explanation, and helper script documentation |
| rpi-setup/quick-deploy.sh | One-command deployment script with dependency installation and auto-start configuration |
| rpi-setup/setup-autostart.sh | Detailed auto-start configuration script with step-by-step setup |
| rpi-setup/setup-production.sh | Production hardening script with optimizations, health checks, and automated backups |
| rpi-setup/create-custom-image.md | Complete guide for creating reusable custom Raspberry Pi images |
| rpi-setup/testing-with-vmware.md | VMware/VirtualBox testing guide for development and debugging |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| cd /home/pi/snackAttackTrack | ||
| git pull | ||
| pip3 install -r requirements-raspberry-pi.txt | ||
| sudo systemctl restart display-manager |
There was a problem hiding this comment.
The command sudo systemctl restart display-manager will fail on Raspberry Pi OS Lite because there is no display-manager service installed. This should be sudo systemctl restart getty@tty1 to properly restart the autologin console session.
| sudo apt-get install qemu-utils | ||
|
|
||
| # Convert img to vmdk | ||
| qemu-img convert -f raw -O vmdk 2024-XX-XX-raspios-bullseye-armhf.img raspi-test.vmdk |
There was a problem hiding this comment.
The file name references "bullseye" which is an older Raspberry Pi OS version (Debian 11). The README.md recommends Bookworm (Debian 12), which is the current version. Consider updating this example to use "bookworm" instead of "bullseye" for consistency with the recommended OS version.
| # Configure swappiness for SD card longevity | ||
| echo "" | ||
| echo "→ Optimizing swap for SD card..." | ||
| sudo bash -c 'echo "vm.swappiness=10" >> /etc/sysctl.conf' |
There was a problem hiding this comment.
Appending to /etc/sysctl.conf without checking if the setting already exists could result in duplicate entries if the script is run multiple times. Consider using a conditional check similar to the fstab entries, or use a separate config file in /etc/sysctl.d/ to avoid duplication.
| sudo bash -c 'echo "vm.swappiness=10" >> /etc/sysctl.conf' | |
| if ! grep -q '^vm.swappiness=' /etc/sysctl.conf; then | |
| sudo bash -c 'echo "vm.swappiness=10" >> /etc/sysctl.conf' | |
| fi |
| sudo bash -c 'cat >> /boot/config.txt << EOF | ||
|
|
||
| # Production Optimizations | ||
| boot_delay=0 | ||
| disable_splash=1 | ||
| avoid_warnings=1 | ||
|
|
||
| # Audio (disable if not needed) | ||
| # dtparam=audio=off | ||
|
|
||
| # Reduce GPU memory for kiosk use | ||
| gpu_mem=128 | ||
| EOF' |
There was a problem hiding this comment.
Appending to /boot/config.txt without checking if these settings already exist could result in duplicate entries if the script is run multiple times. Consider adding a check similar to what's done in quick-deploy.sh (line 153) to prevent duplicate configuration blocks.
| 3. Run: | ||
| ```bash | ||
| curl -sSL https://raw.githubusercontent.com/DouglasHalse/snackAttackTrack/main/rpi-setup/quick-deploy.sh | bash | ||
| ``` | ||
|
|
||
| Or download and run manually: | ||
| ```bash | ||
| wget https://raw.githubusercontent.com/DouglasHalse/snackAttackTrack/main/rpi-setup/quick-deploy.sh | ||
| chmod +x quick-deploy.sh | ||
| ./quick-deploy.sh | ||
| ``` |
There was a problem hiding this comment.
Piping a script directly from the internet to bash without verification (curl -sSL ... | bash) is a security risk. While convenient, users should be warned about this or encouraged to use the manual download approach shown below. Consider adding a security note recommending users review the script first, or only promote the manual download method.
| 3. Run: | |
| ```bash | |
| curl -sSL https://raw.githubusercontent.com/DouglasHalse/snackAttackTrack/main/rpi-setup/quick-deploy.sh | bash | |
| ``` | |
| Or download and run manually: | |
| ```bash | |
| wget https://raw.githubusercontent.com/DouglasHalse/snackAttackTrack/main/rpi-setup/quick-deploy.sh | |
| chmod +x quick-deploy.sh | |
| ./quick-deploy.sh | |
| ``` | |
| 3. Download and run the setup script **manually** (recommended): | |
| ```bash | |
| wget https://raw.githubusercontent.com/DouglasHalse/snackAttackTrack/main/rpi-setup/quick-deploy.sh | |
| chmod +x quick-deploy.sh | |
| ./quick-deploy.sh |
Alternatively, run with a one-liner (less secure)
⚠️ Security Warning:
Piping a script directly from the internet tobashis a security risk.
You should always review scripts before running them.
Only use this method if you trust the source.
curl -sSL https://raw.githubusercontent.com/DouglasHalse/snackAttackTrack/main/rpi-setup/quick-deploy.sh | bash| chmod +x /home/pi/backup-database.sh | ||
|
|
||
| # Add daily backup cron job | ||
| (crontab -l 2>/dev/null || true; echo "0 2 * * * /home/pi/backup-database.sh") | crontab - |
There was a problem hiding this comment.
The crontab command could add duplicate entries if the script is run multiple times. Consider checking if the cron job already exists before adding it, or use a check similar to: (crontab -l 2>/dev/null | grep -v backup-database.sh; echo "0 2 * * * /home/pi/backup-database.sh") | crontab - to replace any existing entry.
| (crontab -l 2>/dev/null || true; echo "0 2 * * * /home/pi/backup-database.sh") | crontab - | |
| (crontab -l 2>/dev/null | grep -v '/home/pi/backup-database.sh'; echo "0 2 * * * /home/pi/backup-database.sh") | crontab - |
| killall python3 | ||
| killall X |
There was a problem hiding this comment.
Using killall python3 and killall X is overly aggressive and could terminate other Python scripts or X sessions that might be running on the system. Consider using more specific process identification, such as pkill -f "python3 main.py" or storing the PID when the app starts, to only kill the SnackAttack process.
| killall python3 | |
| killall X | |
| # Only kill the SnackAttack process (adjust "main.py" if your entrypoint is different) | |
| pkill -f "python3 main.py" | |
| # Optionally, stop the X session started for SnackAttack (if safe) | |
| pkill -u $USER X |
| # Or manually | ||
| sudo systemctl restart display-manager |
There was a problem hiding this comment.
The command sudo systemctl restart display-manager will not work on Raspberry Pi OS Lite as there is no display-manager service installed. This should be sudo systemctl restart getty@tty1 or ~/restart-snackattack.sh to properly restart the application.
| # Or manually | |
| sudo systemctl restart display-manager | |
| # Or manually (for console-based systems) | |
| sudo systemctl restart getty@tty1 |
| wget https://raw.githubusercontent.com/Drewsif/PiShrink/master/pishrink.sh | ||
| chmod +x pishrink.sh | ||
| sudo ./pishrink.sh snackattack-rpi.img | ||
| ``` |
There was a problem hiding this comment.
These instructions download and execute the pishrink.sh script directly from a third-party GitHub repository (Drewsif/PiShrink) using a mutable master branch reference, without any checksum or signature verification. If that repository is compromised or the download is tampered with, an attacker could execute arbitrary code as root on the build host and silently backdoor the generated Raspberry Pi images. To reduce supply-chain risk, pin to a specific, audited PiShrink release (e.g., by commit hash), verify its integrity (checksum/signature), or vendor the script into this repository instead of executing it directly from a remote URL.
| wget https://raw.githubusercontent.com/Drewsif/PiShrink/master/pishrink.sh | ||
| chmod +x pishrink.sh | ||
| sudo ./pishrink.sh snackattack-rpi.img |
There was a problem hiding this comment.
These deployment instructions fetch and execute the pishrink.sh script from the third-party Drewsif/PiShrink GitHub repository, pinned only to the mutable master branch and without any integrity verification. This creates a supply-chain risk where compromise of that repository or the download path could lead to arbitrary code execution as root on the machine creating your images, and to backdoored artifacts. Prefer pinning to a specific, vetted commit or release and validating a published checksum/signature, or vendoring the script into this repo, instead of executing arbitrary remote code directly.
Summary
Adds comprehensive Raspberry Pi setup guides including: