diff --git a/docs/superpowers/plans/2026-06-28-tappaas-vps-publishing.md b/docs/superpowers/plans/2026-06-28-tappaas-vps-publishing.md new file mode 100644 index 0000000..51cb3df --- /dev/null +++ b/docs/superpowers/plans/2026-06-28-tappaas-vps-publishing.md @@ -0,0 +1,368 @@ +# TaPPaaS VPS Publishing (VPS side) — Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Wire the makerfloss VPS to publish `*.tappaas.makerfloss.eu` — add a `wg1` peer for the TaPPaaS FLOSSFirewall, issue the wildcard cert, add the catch-all route to the backend, and publish the public DNS — reusing the proven mf01 pattern. + +**Architecture:** All changes are additive edits to `AnsibleBaobabV4/host_vars/makerfloss.yml` (plus one vault entry), deployed with the repo's existing plays. TLS terminates at the VPS; a catch-all Traefik router forwards plain HTTP over `wg1` to the FLOSSFirewall/Caddy backend at `10.13.0.9:80`. This plan delivers the **VPS edge only** — end-to-end `200` awaits the separate TaPPaaS-side plan, so the success criterion here is a valid-TLS `502` (route works, backend not yet up). + +**Tech Stack:** Ansible (baobab roles `baobab.wireguard_server`, `baobab.traefik`, `baobab.gandi_dns`), Traefik (Gandi DNS-01 ACME), WireGuard, `wireguard-tools`. + +## Global Constraints + +- **Target repo/branch:** changes land in `~/Projects/AnsibleBaobabV4` on **`main`**. That repo currently has unrelated WIP on `feat/loki-review-staleness-alert` — before starting, get these commits onto `main` cleanly (stash/commit the WIP, or branch off `main` and fast-forward `main` when done). Do **not** mix this work into the loki feature branch. +- **All ansible commands run from** `~/Projects/AnsibleBaobabV4` (repo root) using `.venv/bin/ansible-playbook`. +- **Inventory + limit always:** `-i inventories/prod/hosts.yml --limit makerfloss`. +- **Vault is auto-loaded** from `~/.ansible/vault-keys/prod.txt` via `ansible.cfg` (`vault_identity_list = prod@...`). Never pass `--vault-id` manually; never print vault plaintext into a commit or log. +- **Idempotency (repo rule):** every deploy task runs the play **twice**; the second run must report `changed=0`. +- **Peer naming/addressing (decided):** peer name `flossfw`, `wg1` IP **`10.13.0.9/32`** (confirmed free; taken = `.1 .2 .3 .5 .6 .8`). +- **Test hostname:** use `whoami.tappaas.makerfloss.eu` throughout — any label under the wildcard works; nothing needs to exist at the backend for the VPS-side checks. +- **Reach path:** all verification targets the **public VPS** (`makerfloss.eu` / `88.99.32.236`, SSH `:7576`) — no makerspace tunnel needed (access.md path B2). +- **Never commit secrets.** The keypair lives only in the encrypted vault. + +## File Structure + +- `~/Projects/AnsibleBaobabV4/group_vars/all/90-secrets.vault.yml` *(modify, encrypted)* — adds `flossfw` keypair under `vault_wireguard_makerfloss_peers`. +- `~/Projects/AnsibleBaobabV4/host_vars/makerfloss.yml` *(modify)* — adds, in four distinct sections: the `wg1` peer, the wildcard cert set, the catch-all dynamic route, and the public DNS records. + +No new files; no TaPPaaS-side files (separate plan). + +--- + +### Task 1: Generate the FLOSSFirewall WireGuard keypair and store it in the vault + +**Files:** +- Modify: `~/Projects/AnsibleBaobabV4/group_vars/all/90-secrets.vault.yml` (encrypted) + +**Interfaces:** +- Produces: vault var `vault_wireguard_makerfloss_peers.flossfw.public_key` (and `.private_key`), referenced by Task 2. + +- [ ] **Step 1: Ensure `wg` is available** + +Run: +```bash +command -v wg || sudo apt-get install -y wireguard-tools +``` +Expected: a path like `/usr/bin/wg`. + +- [ ] **Step 2: Generate the keypair (private never leaves tmpfs until vaulted)** + +Run: +```bash +umask 077 +wg genkey | tee /dev/shm/flossfw.key | wg pubkey > /dev/shm/flossfw.pub +echo "PRIV=$(cat /dev/shm/flossfw.key)" +echo "PUB=$(cat /dev/shm/flossfw.pub)" +``` +Expected: two base64 strings (44 chars ending `=`). + +- [ ] **Step 3: Add the entry to the vault** + +Run: +```bash +cd ~/Projects/AnsibleBaobabV4 +.venv/bin/ansible-vault edit group_vars/all/90-secrets.vault.yml +``` +Under the existing `vault_wireguard_makerfloss_peers:` mapping, add (paste the real values from Step 2 in place of `PRIV`/`PUB`): +```yaml + flossfw: + private_key: "PRIV" + public_key: "PUB" +``` +Save and close the editor. + +- [ ] **Step 4: Verify the entry decrypts and parses** + +Run: +```bash +cd ~/Projects/AnsibleBaobabV4 +.venv/bin/ansible-vault view group_vars/all/90-secrets.vault.yml | grep -A3 'flossfw:' +``` +Expected: the `flossfw:` block with `private_key`/`public_key` printed. (This is local stdout only — do not redirect to a file.) + +- [ ] **Step 5: Shred the tmp keys** + +Run: +```bash +shred -u /dev/shm/flossfw.key /dev/shm/flossfw.pub 2>/dev/null; rm -f /dev/shm/flossfw.key /dev/shm/flossfw.pub +``` +Expected: files gone (`ls /dev/shm/flossfw.* ` → no such file). The keys now live only in the vault. + +- [ ] **Step 6: Commit** + +```bash +cd ~/Projects/AnsibleBaobabV4 +git add group_vars/all/90-secrets.vault.yml +git commit -m "secrets: add flossfw wireguard keypair for tappaas wg1 peer" +``` + +--- + +### Task 2: Add the FLOSSFirewall as a `wg1` peer and deploy + +**Files:** +- Modify: `~/Projects/AnsibleBaobabV4/host_vars/makerfloss.yml` (`wireguard_server_peers`) + +**Interfaces:** +- Consumes: `vault_wireguard_makerfloss_peers.flossfw.public_key` (Task 1). +- Produces: VPS `wg1` allows `10.13.0.9/32` — the backend address Task 4 routes to. + +- [ ] **Step 1: Add the peer entry** + +In `host_vars/makerfloss.yml`, append to the `wireguard_server_peers:` list (after the `mf01` entry), matching the existing style exactly: +```yaml + - name: "flossfw" + public_key: "{{ vault_wireguard_makerfloss_peers.flossfw.public_key }}" + allowed_ips: "10.13.0.9/32" + managed: true + description: "TaPPaaS FLOSSFirewall (Caddy reverse proxy, split-tunnel)" + generate_config: false # client config deployed on the TaPPaaS side +``` + +- [ ] **Step 2: Deploy the WireGuard server config** + +Run: +```bash +cd ~/Projects/AnsibleBaobabV4 +.venv/bin/ansible-playbook play_setup.yml -i inventories/prod/hosts.yml --limit makerfloss -t wireguard-server,firewall +``` +Expected: PLAY RECAP with `failed=0`, `changed>=1`. + +- [ ] **Step 3: Confirm idempotence (run again)** + +Run the exact command from Step 2 again. +Expected: PLAY RECAP `changed=0`. + +- [ ] **Step 4: Verify the peer is live on the VPS** + +Run: +```bash +ssh -p 7576 sjat@makerfloss.eu "sudo wg show wg1 allowed-ips" | grep -F '10.13.0.9/32' +``` +Expected: one line containing the `flossfw` public key and `10.13.0.9/32`. (No handshake yet — the FLOSSFirewall isn't up; that's expected.) + +- [ ] **Step 5: Commit** + +```bash +cd ~/Projects/AnsibleBaobabV4 +git add host_vars/makerfloss.yml +git commit -m "wg1: add flossfw peer (10.13.0.9) for tappaas publishing" +``` + +--- + +### Task 3: Add the `*.tappaas` wildcard cert set and issue it + +**Files:** +- Modify: `~/Projects/AnsibleBaobabV4/host_vars/makerfloss.yml` (`traefik_wildcard_sets`) + +**Interfaces:** +- Produces: a valid `*.tappaas.makerfloss.eu` cert on the VPS Traefik, used by Task 4's router (`tls: {}`). + +- [ ] **Step 1: Add the wildcard set** + +In `host_vars/makerfloss.yml`, append to `traefik_wildcard_sets:` (after the `mf01` entry): +```yaml + - main: "tappaas.makerfloss.eu" + sans: ["*.tappaas.makerfloss.eu"] +``` + +- [ ] **Step 2: Deploy Traefik (triggers ACME via the anchor router)** + +Run: +```bash +cd ~/Projects/AnsibleBaobabV4 +.venv/bin/ansible-playbook play_containers.yml -i inventories/prod/hosts.yml --limit makerfloss -t traefik +``` +Expected: PLAY RECAP `failed=0`; the traefik container is recreated. + +- [ ] **Step 3: Confirm idempotence (run again)** + +Run the Step 2 command again. +Expected: PLAY RECAP `changed=0`. + +- [ ] **Step 4: Watch ACME issue the cert** + +Run (wait up to ~90s for DNS-01 to complete): +```bash +ssh -p 7576 sjat@makerfloss.eu "docker logs traefik 2>&1 | grep -i tappaas | tail -20" +``` +Expected: ACME log lines referencing `tappaas.makerfloss.eu` / `*.tappaas.makerfloss.eu` with no error; eventually a "certificate obtained" style entry. + +- [ ] **Step 5: Verify the served cert (by IP + SNI — no DNS needed yet)** + +Run: +```bash +echo | openssl s_client -connect 88.99.32.236:443 -servername whoami.tappaas.makerfloss.eu 2>/dev/null | openssl x509 -noout -ext subjectAltName +``` +Expected: SAN list contains `*.tappaas.makerfloss.eu`. + +- [ ] **Step 6: Commit** + +```bash +cd ~/Projects/AnsibleBaobabV4 +git add host_vars/makerfloss.yml +git commit -m "traefik: add *.tappaas.makerfloss.eu wildcard cert set" +``` + +--- + +### Task 4: Add the catch-all delegate route to the backend and deploy + +**Files:** +- Modify: `~/Projects/AnsibleBaobabV4/host_vars/makerfloss.yml` (`traefik_extra_dynamic_files`) + +**Interfaces:** +- Consumes: the wildcard cert (Task 3) via `tls: {}`; the `10.13.0.9` peer (Task 2). +- Produces: VPS routes `*.tappaas` → `http://10.13.0.9:80`. + +- [ ] **Step 1: Add the dynamic route file** + +In `host_vars/makerfloss.yml`, add a new key under `traefik_extra_dynamic_files:` (sibling of `mf01-delegate.yml`). **Keep the regex single-quoted** — a YAML error here breaks the whole file provider: +```yaml + tappaas-delegate.yml: | + http: + routers: + tappaas-wildcard: + rule: 'HostRegexp(`^.+\.tappaas\.makerfloss\.eu$`)' + entryPoints: + - websecure + service: tappaas-backend + tls: {} + services: + tappaas-backend: + loadBalancer: + passHostHeader: true + servers: + - url: "http://10.13.0.9:80" +``` + +- [ ] **Step 2: Deploy Traefik** + +Run: +```bash +cd ~/Projects/AnsibleBaobabV4 +.venv/bin/ansible-playbook play_containers.yml -i inventories/prod/hosts.yml --limit makerfloss -t traefik +``` +Expected: PLAY RECAP `failed=0`. + +- [ ] **Step 3: Confirm idempotence (run again)** + +Run the Step 2 command again. +Expected: PLAY RECAP `changed=0`. + +- [ ] **Step 4: Verify the dynamic file parsed (no file-provider error)** + +Run: +```bash +ssh -p 7576 sjat@makerfloss.eu "docker logs traefik 2>&1 | grep -iE 'error|tappaas-delegate' | tail -20" +``` +Expected: no parse/error lines mentioning `tappaas-delegate.yml`. + +- [ ] **Step 5: Verify the route matches (502 = success here)** + +Run: +```bash +curl -sk -o /dev/null -w '%{http_code}\n' -H 'Host: whoami.tappaas.makerfloss.eu' https://88.99.32.236/ +``` +Expected: `502` (or `504`). The router matched and tried the backend; `10.13.0.9:80` isn't up yet, which is the expected VPS-side end state. A `404` would mean the route didn't match — investigate before committing. + +- [ ] **Step 6: Commit** + +```bash +cd ~/Projects/AnsibleBaobabV4 +git add host_vars/makerfloss.yml +git commit -m "traefik: route *.tappaas to flossfw backend over wg1" +``` + +--- + +### Task 5: Publish the public DNS records and deploy + +**Files:** +- Modify: `~/Projects/AnsibleBaobabV4/host_vars/makerfloss.yml` (`gandi_dns_records`) + +**Interfaces:** +- Produces: public A records `tappaas` and `*.tappaas` → `88.99.32.236`. + +- [ ] **Step 1: Add the records** + +In `host_vars/makerfloss.yml`, append to `gandi_dns_records:` (after the `*.mf01` entry), matching the existing style: +```yaml + - name: "tappaas" + type: A + ttl: 300 + values: ["88.99.32.236"] + - name: "*.tappaas" + type: A + ttl: 300 + values: ["88.99.32.236"] +``` + +- [ ] **Step 2: Deploy DNS** + +Run: +```bash +cd ~/Projects/AnsibleBaobabV4 +.venv/bin/ansible-playbook play_dns.yml -i inventories/prod/hosts.yml --limit makerfloss -t gandi-dns +``` +Expected: PLAY RECAP `failed=0`; task output shows the two records added. + +- [ ] **Step 3: Confirm idempotence (run again)** + +Run the Step 2 command again. +Expected: PLAY RECAP `changed=0` (records already present). + +- [ ] **Step 4: Verify resolution** + +Run (allow up to the 300s TTL to propagate): +```bash +dig +short whoami.tappaas.makerfloss.eu @1.1.1.1 +dig +short tappaas.makerfloss.eu @1.1.1.1 +``` +Expected: both return `88.99.32.236`. + +- [ ] **Step 5: Commit** + +```bash +cd ~/Projects/AnsibleBaobabV4 +git add host_vars/makerfloss.yml +git commit -m "dns: publish tappaas + *.tappaas A records to the VPS" +``` + +--- + +### Task 6: VPS-side integration verification (no code change) + +**Files:** none — verification gate. + +- [ ] **Step 1: End-to-end VPS edge check** + +Run: +```bash +curl -sk -o /dev/null -w 'http=%{http_code} cert_subject=%{ssl_verify_result}\n' https://whoami.tappaas.makerfloss.eu/ +echo | openssl s_client -connect whoami.tappaas.makerfloss.eu:443 -servername whoami.tappaas.makerfloss.eu 2>/dev/null | openssl x509 -noout -ext subjectAltName | grep -F '*.tappaas.makerfloss.eu' +``` +Expected: real public DNS resolves to the VPS, TLS validates against the `*.tappaas` wildcard, and HTTP returns `502`/`504` (backend not yet up). This is the **completed VPS-side deliverable**. + +- [ ] **Step 2: Record the result** + +Note in the session/PR: VPS edge ready; `200 OK` is gated on the **TaPPaaS-side plan** (FLOSSFirewall WireGuard client + Caddy plain-HTTP backend on `10.13.0.9:80` + internal DNS). That plan is blocked on identifying the TaPPaaS config repo (spec Open items). Optionally add a short note to `MakerFLOSS_Troubleshooting/runbooks/` pointing at this pattern (mirror of `publishing-services-mf01.md`). + +--- + +## Self-Review + +**Spec coverage (VPS scope):** +- Component A.1 wg1 peer → Task 2 ✓ (keypair prereq → Task 1 ✓) +- A.2 wildcard cert → Task 3 ✓ +- A.3 catch-all route → Task 4 ✓ +- A.4 public DNS → Task 5 ✓ +- Phasing steps 1–3 (tunnel VPS-end, edge, DNS) → Tasks 2–5 ✓; integration gate → Task 6 ✓ +- Isolation: split-tunnel/`AllowedIPs` and the `tcp/80 from 10.13.0.1` firewall are **TaPPaaS-side** — correctly deferred to the other plan, not in scope here. +- Phasing steps 4–5 (internal DNS, makerspace LAN) → TaPPaaS-side plan, out of scope. **Noted gap by design.** + +**Placeholder scan:** No TBD/TODO/"handle errors" placeholders; `PRIV`/`PUB` in Task 1 are explicitly real-value substitutions generated in-step. ✓ + +**Type/name consistency:** peer name `flossfw`, IP `10.13.0.9`, vault path `vault_wireguard_makerfloss_peers.flossfw.public_key`, service `tappaas-backend`, router `tappaas-wildcard`, dynamic file `tappaas-delegate.yml`, hostname `whoami.tappaas.makerfloss.eu` — all consistent across tasks. ✓ +