timothy/mapper
Public Access
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
6380b8325d6c026503f5052f142c25d3e3f8e055
mapper/openspec/changes/mpvj-headless-setup-script/design.md
Timothy Hofland 7928a2be9b 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.
2026-03-10 22:23:58 +01:00

2.5 KiB
Raw Blame History

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.