Make installer cross-platform (Linux/macOS)

haoruizhou · haoruizhou · commit 6676428a4b51 · 2026-05-26T00:33:02.000-04:00
Add full Linux support and an interactive --hotspot mode to the one-line base-station installer; keep macOS support. The installer now bootstraps git and Docker on Debian/Ubuntu/Raspberry Pi OS, can enable a NetworkManager-based Wi‑Fi AP (wfr-hotspot) and installs a systemd unit for it. CI workflow updated to validate compose from the repo root and run a linux e2e job that syntax-checks the script, validates compose, runs the installer, asserts core containers, checks service ports, verifies idempotency, and ensures non-interactive hotspot behaviour. Documentation (README and MACBOOK_DEPLOY.md) and WHICH_ONE.md updated with Linux/RPi instructions and hotspot notes. Fix .env macbook DBC_HOST_PATH to be repo-root relative and add wfr-hotspot.service file.
diff --git a/.github/workflows/macbook-installer-ci.yml b/.github/workflows/macbook-installer-ci.yml
@@ -9,6 +9,7 @@ on:
       - 'universal-telemetry-software/deploy/.env.macbook'
       - 'universal-telemetry-software/deploy/MACBOOK_DEPLOY.md'
       - 'universal-telemetry-software/deploy/ci-validate-compose.py'
+      - 'universal-telemetry-software/deploy/wfr-hotspot.service'
       - '.github/workflows/macbook-installer-ci.yml'
   pull_request:
     branches: [ main, deploy ]
@@ -18,6 +19,7 @@ on:
       - 'universal-telemetry-software/deploy/.env.macbook'
       - 'universal-telemetry-software/deploy/MACBOOK_DEPLOY.md'
       - 'universal-telemetry-software/deploy/ci-validate-compose.py'
+      - 'universal-telemetry-software/deploy/wfr-hotspot.service'
       - '.github/workflows/macbook-installer-ci.yml'
   workflow_dispatch:
 
@@ -65,9 +67,13 @@ jobs:
 
       - name: Validate compose file
         run: |
-          cd universal-telemetry-software/deploy
           if command -v docker &>/dev/null && docker info &>/dev/null; then
-            docker compose -f docker-compose.macbook-base.yml config --quiet
+            # Run from repo root so DBC_HOST_PATH (./universal-telemetry-software/deploy/example.dbc) resolves correctly.
+            docker compose \
+              --project-directory "${{ github.workspace }}" \
+              -f universal-telemetry-software/deploy/docker-compose.macbook-base.yml \
+              --env-file universal-telemetry-software/deploy/.env.macbook \
+              config --quiet
             echo "Compose config valid"
           else
             echo "Skipping compose validation - Docker not running"
@@ -82,20 +88,89 @@ jobs:
             echo "Script correctly detected Docker state"
           fi
 
-  linux-script-test:
+  linux-e2e:
     runs-on: ubuntu-latest
+    # Docker Engine and git are pre-installed on ubuntu-latest runners.
+    # install_linux_deps() detects them and skips the apt-get paths.
+    # Images are pulled from ghcr.io (public) and stack runs in-band.
+    timeout-minutes: 20
     steps:
       - uses: actions/checkout@v4
 
-      - name: Verify script detects non-macOS
+      - name: Syntax check
+        run: bash -n universal-telemetry-software/deploy/install.sh
+
+      - name: --help exits 0
+        run: bash universal-telemetry-software/deploy/install.sh --help
+
+      - name: Compose config validates against PR branch files
+        # Runs from repo root so DBC_HOST_PATH (./universal-telemetry-software/deploy/example.dbc) resolves correctly.
         run: |
-          chmod +x universal-telemetry-software/deploy/install.sh
-          output=$(bash universal-telemetry-software/deploy/install.sh 2>&1) || true
-          echo "$output" | grep -q "requires macOS" && echo "Correctly rejects Linux" || echo "Unexpected output"
+          docker compose \
+            --project-directory "${{ github.workspace }}" \
+            -f universal-telemetry-software/deploy/docker-compose.macbook-base.yml \
+            --env-file universal-telemetry-software/deploy/.env.macbook \
+            config --quiet
+          echo "Compose config valid"
+
+      - name: Python compose structural check
+        run: python3 universal-telemetry-software/deploy/ci-validate-compose.py
+
+      - name: Run full installer end-to-end
+        # Clones ~/wfr-base-station from the main branch, pulls images, starts stack.
+        # Uses sudo docker compose (as install.sh does on Linux) — fine on GHA runners.
+        run: bash universal-telemetry-software/deploy/install.sh
+
+      - name: Assert all core containers are running
+        run: |
+          docker ps
+          docker ps --format '{{.Names}}' | grep -q daq-telemetry || { echo "daq-telemetry not running"; exit 1; }
+          docker ps --format '{{.Names}}' | grep -q daq-redis    || { echo "daq-redis not running";    exit 1; }
+          docker ps --format '{{.Names}}' | grep -q daq-pecan    || { echo "daq-pecan not running";    exit 1; }
+          echo "All 3 core containers are up"
 
-      - name: Validate compose file structure
+      - name: Wait for Pecan on port 3000
         run: |
-          python3 universal-telemetry-software/deploy/ci-validate-compose.py
+          echo "Polling http://localhost:3000 ..."
+          for i in $(seq 1 30); do
+            if curl -sf http://localhost:3000 -o /dev/null; then
+              echo "Pecan is serving on port 3000"
+              exit 0
+            fi
+            echo "  attempt $i/30 — retrying in 3 s"
+            sleep 3
+          done
+          echo "Pecan did not become ready within 90 s"
+          docker logs daq-pecan || true
+          exit 1
+
+      - name: Wait for telemetry status page on port 8080
+        run: |
+          echo "Polling http://localhost:8080 ..."
+          for i in $(seq 1 30); do
+            if curl -sf http://localhost:8080 -o /dev/null; then
+              echo "Status page is serving on port 8080"
+              exit 0
+            fi
+            echo "  attempt $i/30 — retrying in 3 s"
+            sleep 3
+          done
+          echo "Telemetry status page did not become ready within 90 s"
+          docker logs daq-telemetry || true
+          exit 1
+
+      - name: Idempotency — re-run installer over existing clone
+        run: bash universal-telemetry-software/deploy/install.sh
+
+      - name: --hotspot skips gracefully in non-interactive CI
+        # stdin from /dev/null makes [[ ! -t 0 ]] true → prints skip message, returns 1.
+        # The outer script still reaches print_success and exits 0.
+        run: |
+          output=$(bash universal-telemetry-software/deploy/install.sh --hotspot </dev/null 2>&1) || true
+          echo "$output"
+          echo "$output" | grep -q "Not an interactive terminal" \
+            || { echo "Expected hotspot-skip message was not found in output"; exit 1; }
+          echo "Non-interactive hotspot skip verified"
 
   url-accessibility:
     runs-on: ubuntu-latest
diff --git a/README.md b/README.md
@@ -6,10 +6,14 @@
 
 Comprehensive telemetry and data acquisition system for real-time monitoring of formula racing vehicle performance. This system captures CAN bus data from the vehicle, transmits it to a base station, and visualizes it through an interactive web dashboard.
 
-> 🚀 **Quick Start — macOS Base Station**
+> 🚀 **Quick Start — Base Station (macOS or Linux)**
 > ```bash
 > curl -fsSL https://raw.githubusercontent.com/Western-Formula-Racing/data-acquisition/main/universal-telemetry-software/deploy/install.sh | bash
 > ```
+> **Linux with Wi-Fi hotspot for pit devices (RPi at track):**
+> ```bash
+> curl -fsSL https://raw.githubusercontent.com/Western-Formula-Racing/data-acquisition/main/universal-telemetry-software/deploy/install.sh | bash -s -- --hotspot
+> ```
 > [Full setup guide →](./universal-telemetry-software/deploy/MACBOOK_DEPLOY.md)
 
 ![pecan dashboard](pecan/docs-assets/PECAN-Dashboard.jpg)
diff --git a/universal-telemetry-software/deploy/.env.macbook b/universal-telemetry-software/deploy/.env.macbook
@@ -9,7 +9,7 @@
 REMOTE_IP=10.71.1.10
 ENABLE_TIMESCALE_LOGGING=auto
 TIMESCALE_TABLE=WFR26test
-DBC_HOST_PATH=./example.dbc
+DBC_HOST_PATH=./universal-telemetry-software/deploy/example.dbc
 RELAY_TOKEN=
 CLOUDFLARED_CONFIG=./cloudflared/config.yml
 CLOUDFLARED_CREDENTIALS=./cloudflared/credentials.json
diff --git a/universal-telemetry-software/deploy/MACBOOK_DEPLOY.md b/universal-telemetry-software/deploy/MACBOOK_DEPLOY.md
@@ -1,34 +1,45 @@
-# MacBook Base Station Setup
+# Base Station Setup (macOS / Linux)
 
-Local telemetry stack for a MacBook base station. The default startup is minimal:
+Local telemetry stack for a MacBook or Linux base station (including Raspberry Pi 4B). The default startup is minimal:
 telemetry receiver, Redis, and the Pecan dashboard.
 
 TimescaleDB writes, local media services, and the Cloudflare tunnel are opt-in
 Docker Compose profiles.
 
 ## Prerequisites
 
-- [Docker Desktop](https://www.docker.com/products/docker-desktop/) installed and running
-- Car RPi on the same network, or use simulation mode
+**macOS:** [Docker Desktop](https://www.docker.com/products/docker-desktop/) installed and running.
+
+**Linux / Raspberry Pi 4B:** Nothing pre-installed — the installer bootstraps git and Docker Engine automatically. Requires Debian/Ubuntu or Raspberry Pi OS (apt-get).
+
+Car RPi on the same network, or use simulation mode.
 
 ---
 
 ## One-Command Install (Recommended)
 
-**Requires macOS + Docker Desktop (one-time install from docker.com).**
-
 ```bash
 curl -fsSL https://raw.githubusercontent.com/Western-Formula-Racing/data-acquisition/main/universal-telemetry-software/deploy/install.sh | bash
 ```
 
+**Linux with Wi-Fi hotspot for pit devices** (RPi 4B at track — ethernet to car radio, Wi-Fi AP for laptops/tablets):
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/Western-Formula-Racing/data-acquisition/main/universal-telemetry-software/deploy/install.sh | bash -s -- --hotspot
+```
+
 That's it. The script:
-1. Verifies Docker Desktop is running
-2. Clones the repo to `~/wfr-base-station/` (or updates if already present)
-3. Pulls the latest images
-4. Starts the stack
+1. **macOS:** Verifies Docker Desktop is running
+2. **Linux:** Installs git and Docker Engine if missing, enables Docker on boot
+3. Clones the repo to `~/wfr-base-station/` (or updates if already present)
+4. Pulls the latest images
+5. Starts the stack (auto-restarts on reboot via `restart: unless-stopped`)
+6. **`--hotspot` (Linux):** Prompts before enabling — switches `wlan0` to AP mode (`WFR-Base`); pit crew opens Pecan at `http://10.42.0.1:3000`. **Warning:** disconnects Wi-Fi SSH/internet if no other adapter is present.
 
 Subsequent updates: run the same command again.
 
+**Pecan runs in the browser on pit devices** — the base station only serves static files and forwards telemetry. Open Pecan from a laptop or tablet on the LAN, not in Chromium on the Pi itself.
+
 ---
 
 ## Manual Setup
@@ -71,7 +82,7 @@ All configuration is done through `deploy/.env.macbook`. Key variables:
 | `REMOTE_IP` | `10.71.1.10` | Car RPi IP address |
 | `ENABLE_TIMESCALE_LOGGING` | `auto` | Auto-start writer when the TimescaleDB profile is running |
 | `TIMESCALE_TABLE` | `WFR26test` | Season table name (no `_base` suffix — added automatically) |
-| `DBC_HOST_PATH` | `./example.dbc` | Path to DBC file |
+| `DBC_HOST_PATH` | `./universal-telemetry-software/deploy/example.dbc` | Path to DBC file (relative to repo root) |
 | `RELAY_TOKEN` | blank | Optional relay token |
 | `CLOUDFLARED_CONFIG` | `./cloudflared/config.yml` | Private tunnel config path for `--profile tunnel` |
 | `CLOUDFLARED_CREDENTIALS` | `./cloudflared/credentials.json` | Private tunnel credentials path for `--profile tunnel` |
@@ -128,6 +139,43 @@ docker compose -f deploy/docker-compose.macbook-base.yml --env-file deploy/.env.
 
 **TimescaleDB not writing:** Start with `docker compose --profile timescale ... up -d`. In `auto` mode, telemetry probes the configured database at boot and starts the writer only when it is reachable. Verify the `WFR26test_base` table exists: `psql postgresql://wfr:wfr_password@localhost:5432/wfr -c "\dt"`
 
+## Network setup
+
+### macOS
+
+Set IP `10.71.1.20` on the USB-C ethernet adapter connected to the car radio base.
+
+Via GUI: System Settings → Network → USB-C Ethernet → Configure IPv4 → Manually → IP: 10.71.1.20 / Subnet: 255.255.255.0
+
+Via CLI:
+```bash
+networksetup -listallhardwareports
+sudo networksetup -setmanual '<interface>' 10.71.1.20 255.255.255.0
+ping -c 3 10.71.1.10
+```
+
+### Linux / Raspberry Pi
+
+Set IP `10.71.1.20` on the ethernet interface connected to the car radio (USB-ethernet or onboard).
+
+```bash
+ip -br link   # find interface name
+
+# NetworkManager (RPi OS / Ubuntu)
+sudo nmcli con mod '<connection-name>' ipv4.method manual \
+  ipv4.addresses 10.71.1.20/24 ipv4.gateway ''
+sudo nmcli con up '<connection-name>'
+
+# Or temporary (resets on reboot)
+sudo ip addr add 10.71.1.20/24 dev eth0
+
+ping -c 3 10.71.1.10
+```
+
+With `--hotspot`, the installer **asks for confirmation** before switching `wlan0` to AP mode (`WFR-Base` / `wfr-racing`). This disconnects any Wi-Fi client connection (including SSH over Wi-Fi) and removes internet on Wi-Fi unless another adapter (e.g. ethernet) is connected. Pit devices connect and open `http://10.42.0.1:3000`. The ethernet car link at `10.71.1.20` is independent.
+
+---
+
 ## Windows / WSL2 — Limited Support
 
 The base station stack is designed for macOS and native Linux. Windows support is limited:
diff --git a/universal-telemetry-software/deploy/WHICH_ONE.md b/universal-telemetry-software/deploy/WHICH_ONE.md
@@ -19,8 +19,8 @@ Use these first:
 | Target | File / doc | Notes |
 |--------|------------|-------|
 | Car RPi | `CAR_DEPLOY.md` + `car-telemetry.service` | Native systemd, no Docker/Redis on the car |
-| MacBook base | `docker-compose.macbook-base.yml` | Default LAN stack with optional TimescaleDB, media, and tunnel profiles |
-| RPi base | `docker-compose.rpi-base.yml` | Lightweight base station, no local TimescaleDB persistence |
+| MacBook / Linux / RPi 4B base | `docker-compose.macbook-base.yml` + `install.sh` | One-command curl install; optional `--profile timescale`, `--hotspot` on Linux |
+| RPi base (manual, deprecating) | `docker-compose.rpi-base.yml` | Lightweight ephemeral base, host networking; no one-click installer |
 
 ---
 
diff --git a/universal-telemetry-software/deploy/install.sh b/universal-telemetry-software/deploy/install.sh
diff --git a/universal-telemetry-software/deploy/wfr-hotspot.service b/universal-telemetry-software/deploy/wfr-hotspot.service
