feat: add headless-setup-script and OpenSpec artifacts
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.
This commit is contained in:
Timothy Hofland
@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-03-10
|
||||
44
openspec/changes/mpvj-headless-setup-script/design.md
Normal file
44
openspec/changes/mpvj-headless-setup-script/design.md
Normal file
@ -0,0 +1,44 @@
|
||||
## 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.
|
||||
26
openspec/changes/mpvj-headless-setup-script/proposal.md
Normal file
26
openspec/changes/mpvj-headless-setup-script/proposal.md
Normal file
@ -0,0 +1,26 @@
|
||||
## Why
|
||||
|
||||
Deploying MPVJ on a Raspberry Pi 3B (x64 Lite) requires complex system-level configuration (WiFi Access Point, DNS masking, service orchestration). Currently, this is a manual and error-prone process. A "one-liner" headless setup script is needed to transform a clean Raspbian installation into a dedicated mapping appliance with zero friction.
|
||||
|
||||
## What Changes
|
||||
|
||||
- **Interactive Setup Script**: A Bash-based installer (`setup.sh`) that asks for hostname, SSID, and WiFi password using a TUI (Text User Interface).
|
||||
- **Automated System Hardening**: Automatic installation and configuration of `hostapd`, `dnsmasq`, `avahi-daemon`, and `nodejs`.
|
||||
- **Hybrid Networking Configuration**: Setup of a static IP (192.168.4.1) for the WiFi AP while maintaining DHCP on Ethernet (eth0) for failsafe access.
|
||||
- **Application Deployment**: Cloning the MPVJ repository from a user-provided URL and installing dependencies.
|
||||
- **Service Orchestration**: Installation of a `systemd` service for the MPVJ backend to ensure it starts on boot.
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
- `headless-installer`: A standalone Bash script capable of configuring a Raspberry Pi for headless MPVJ operation via a single command.
|
||||
|
||||
### Modified Capabilities
|
||||
- `hybrid-network-control`: The existing networking logic will be updated to respect the configurations generated by the setup script.
|
||||
|
||||
## Impact
|
||||
|
||||
- **System Networking**: Modifies `/etc/dhcpcd.conf`, `/etc/hostapd/hostapd.conf`, and `/etc/dnsmasq.conf`.
|
||||
- **Hostname**: Updates `/etc/hostname` and `/etc/hosts`.
|
||||
- **Resource Management**: Automatically manages swap file size during the build process to prevent OOM errors on 1GB RAM devices.
|
||||
- **Security**: Sets an independent WPA2 password for the WiFi AP while leaving the system SSH password untouched.
|
||||
@ -0,0 +1,53 @@
|
||||
# Headless Installer Spec
|
||||
|
||||
## Interrogation Phase
|
||||
|
||||
### Hostname Selection
|
||||
- **GIVEN** the script is running
|
||||
- **WHEN** prompted for a hostname
|
||||
- **THEN** the system SHALL validate that the name contains only alphanumeric characters and hyphens
|
||||
- **AND** it SHALL default to `mpvj` if left blank
|
||||
|
||||
### WiFi Configuration
|
||||
- **GIVEN** the interrogation phase
|
||||
- **WHEN** the user enters a WiFi password
|
||||
- **THEN** the script SHALL verify it is at least 8 characters long (WPA2 requirement)
|
||||
- **AND** it SHALL loop back to the prompt if validation fails
|
||||
- **AND** the script SHALL prompt for a 2-letter ISO Country Code (e.g., US, GB) to unblock the WiFi hardware.
|
||||
|
||||
## Installation Phase
|
||||
|
||||
### Pre-Flight Checks
|
||||
- **GIVEN** the start of the installation
|
||||
- **WHEN** checking system resources
|
||||
- **THEN** the script SHALL verify that at least 2GB of disk space is available
|
||||
- **AND** it SHALL abort with a clear error message if space is insufficient.
|
||||
|
||||
### System Updates
|
||||
- **GIVEN** the start of the script
|
||||
- **WHEN** updating packages
|
||||
- **THEN** it SHALL use a progress bar (`whiptail --gauge`) to show status
|
||||
- **AND** it SHALL run in non-interactive mode (`-y`)
|
||||
|
||||
### Repository Cloning
|
||||
- **GIVEN** a valid <REPO_URL> argument
|
||||
- **WHEN** cloning the repository
|
||||
- **THEN** it SHALL clone into `/home/pi/mpvj`
|
||||
- **AND** it SHALL ensure the `pi` user owns the directory
|
||||
|
||||
## Summary & Finalization
|
||||
|
||||
### Information Display
|
||||
- **GIVEN** the end of the installation
|
||||
- **WHEN** all configurations are staged
|
||||
- **THEN** the script SHALL display a "Don't Miss It" summary box containing:
|
||||
- Hostname (`.local` address)
|
||||
- Static IP (`192.168.4.1`)
|
||||
- WiFi SSID
|
||||
- WiFi Password
|
||||
- **AND** it SHALL require the user to press "OK" to proceed to the reboot prompt
|
||||
|
||||
### Reboot Confirmation
|
||||
- **GIVEN** the summary has been acknowledged
|
||||
- **WHEN** the reboot prompt appears
|
||||
- **THEN** the system SHALL ONLY reboot if the user selects "Yes"
|
||||
33
openspec/changes/mpvj-headless-setup-script/tasks.md
Normal file
33
openspec/changes/mpvj-headless-setup-script/tasks.md
Normal file
@ -0,0 +1,33 @@
|
||||
## 1. Interrogation & Validation
|
||||
|
||||
- [x] 1.1 Implement argument check for `<REPO_URL>`.
|
||||
- [x] 1.2 Create `whiptail` prompts for Hostname, SSID, WiFi Password, and Country Code.
|
||||
- [x] 1.3 Add validation loop for WPA2 password length (min 8 chars) and Country Code format.
|
||||
|
||||
## 2. System Staging
|
||||
|
||||
- [x] 2.1 Implement the Pre-Flight Disk Space check (`df -h`).
|
||||
- [x] 2.2 Implement the progress bar for `apt update && upgrade`.
|
||||
- [x] 2.3 Install dependencies: `nodejs`, `hostapd`, `dnsmasq`, `avahi-daemon`, `git`.
|
||||
- [x] 2.4 Configure Hostname and WiFi Country Code in system files.
|
||||
- [x] 2.5 Set up the temporary 1GB Swap file.
|
||||
|
||||
## 3. Networking Configuration
|
||||
|
||||
- [x] 3.1 Write the `hostapd.conf` template using user-provided SSID and Password.
|
||||
- [x] 3.2 Configure `dnsmasq.conf` for the `192.168.4.1` range.
|
||||
- [x] 3.3 Update `dhcpcd.conf` to set static IP on `wlan0`.
|
||||
- [x] 3.4 Create Avahi service file for mDNS HTTP discovery (including Link-Local support).
|
||||
|
||||
## 4. Application Deployment
|
||||
|
||||
- [x] 4.1 Clone the repository to `/home/pi/mpvj`.
|
||||
- [x] 4.2 Run `npm install` with concurrency limits (`--jobs 1`) and `npm run build` within the swap safety net.
|
||||
- [x] 4.3 Install the `systemd` service for the backend.
|
||||
- [x] 4.4 Generate the `.env` file with installation metadata.
|
||||
|
||||
## 5. Finalization
|
||||
|
||||
- [x] 5.1 Revert the swap file to default size.
|
||||
- [x] 5.2 Implement the "Ultimate Summary" whiptail message box.
|
||||
- [x] 5.3 Add the final reboot confirmation dialog.
|
||||
Reference in New Issue
Block a user