7928a2be9b
Implement a 'one-liner' installation script for the MPVJ (Modern PocketVJ) ecosystem on Raspbian x64 Lite. - Interactive whiptail UI for Hostname, SSID, and WiFi Password configuration. - Automated system hardening: hostapd, dnsmasq, avahi-daemon, and Node.js. - Memory safety for Pi 3B: temporary 1GB swap and NPM concurrency limits. - Networking failsafe: static AP on wlan0 and DHCP on eth0 with mDNS support. - OpenSpec artifacts (Proposal, Design, Spec, Tasks) included.
45 lines
2.5 KiB
Markdown
45 lines
2.5 KiB
Markdown
## Context
|
|
|
|
Targeting the Raspberry Pi 3B (1GB RAM) running Raspbian x64 Lite. The goal is a "Finalize on Reboot" strategy where the user is disconnected from SSH and reconnects to the newly created WiFi Access Point.
|
|
|
|
## Goals / Non-Goals
|
|
|
|
**Goals:**
|
|
- Create a `curl | bash` compatible script.
|
|
- Support a custom Git repository URL as a script argument.
|
|
- Use `whiptail` for a professional, interactive UI.
|
|
- Ensure the system remains accessible via Ethernet if WiFi configuration fails.
|
|
|
|
**Non-Goals:**
|
|
- **Automated SSH Key Setup**: We will rely on the user's existing SSH credentials.
|
|
- **Firewall Configuration**: Advanced `iptables` or `ufw` setup is out of scope for this version.
|
|
|
|
## Decisions
|
|
|
|
### 1. Delivery Workflow
|
|
The script will be invoked as:
|
|
`curl -sSL <URL>/setup.sh | sudo bash -s -- <REPO_URL>`
|
|
This allows the script to be hosted on Gitea/GitHub and pull the application code dynamically.
|
|
|
|
### 2. Networking Architecture
|
|
- **wlan0**: Configured as a static Access Point (`192.168.4.1`).
|
|
- **eth0**: Remains a DHCP client for failsafe rescue.
|
|
- **mDNS (Link-Local)**: Avahi will be configured to broadcast `mpvj.local` even on IPv4 Link-Local (169.254.x.x) to support direct Pi-to-Laptop cable connection without a router.
|
|
- **WiFi Region**: The script will interrogate and set the `country_code` in `wpa_supplicant.conf` to prevent `hostapd` from being "soft-blocked" by the kernel.
|
|
|
|
### 3. Build Strategy (The "Safe" Build)
|
|
To handle the 1GB RAM limitation on Pi 3B:
|
|
1. **Disk Check**: Verify at least 2GB of free space before starting.
|
|
2. **Swap Scaling**: Temporarily increase swap to 1GB using `dphys-swapfile`.
|
|
3. **Concurrency Limiting**: Run `npm config set jobs 1` and `node --max-old-space-size=512` during the build phase to prevent OOM (Out of Memory) panics.
|
|
4. **Hybrid Detection**: Skip the build entirely if a pre-compiled `frontend/dist` folder is detected in the repository.
|
|
|
|
### 4. Configuration Templating
|
|
The script will use "Heredocs" to overwrite system configuration files with the user's validated input (SSID, Password, Hostname, Country Code).
|
|
|
|
## Risks / Trade-offs
|
|
|
|
- **[Risk] SSH Disconnection** → **Mitigation**: The script performs all updates and installs *before* staging the network changes and requires a final user confirmation before rebooting.
|
|
- **[Risk] SD Card Wear** → **Mitigation**: The swap increase is temporary and only used during the installation/build phase.
|
|
- **[Risk] Invalid WiFi Password** → **Mitigation**: The script includes a validation loop to ensure WPA2 passwords are at least 8 characters.
|