kvitt/PLAN-M2c-pi.md

PLAN-M2c-pi: Infra on the Pi (D-001)

Runs after M8 lands and before M10 (D-001, §11.1).

1. Goal

Deploy Kvitt's production stack on the Raspberry Pi 3: Caddy with the Let's Encrypt certificate synced from the Home Assistant Pi, the server, cert-sync and nightly Drive backups, with images in the Gitea registry at http://gitea.lan. Write the runbooks so the owner can provision, deploy, publish the APK and restore without an agent.

2. Read first

1. SPEC §10 Deployment & ops, all of it: intro "Development first (D-001)", §10.1 Hosts and network, §10.2 Compose stack, §10.3 Images, registry and build, §10.4 Server configuration and CLI, §10.5 TLS (10.5.1 Certificate sync, 10.5.2 Caddyfile, 10.5.3 Fallback), §10.6 APK hosting and release, §10.7 Firebase setup (step 7), §10.9 Backups and restore, §10.10 Operations.
2. SPEC §8.5 Transport, §8.9 Server hardening, §8.7 Privacy and logging.
3. SPEC §4 FR-18 Backups and restore, FR-20 Health (AC-20.2).
4. SPEC §11.2 (rows M2c-dev, M2c-pi, M10), §11.3 (note M2c-dev / M2c-pi), §12 (OQ-1, OQ-3, OQ-4), §14.7.
5. docs/decisions.md D-001, D-002.
6. Files: everything under infra/ from M2c-dev (infra/dev/**, infra/backup/**, infra/env.example), server/Dockerfile, .gitignore, CLAUDE.md (EXECUTION PROTOCOLS: Stay inside the repository, Stop and ask; THE OWNER).

3. Already established

• Hosts: Kvitt Pi (Raspberry Pi 3, 1 GB, 64-bit Raspberry Pi OS Lite, Docker Engine with compose plugin, static LAN address); Home Assistant Pi owns 80/443 and the certificate; ASUS router forwards external TCP 8443 to Kvitt Pi 8443; the Pi never builds anything (§10.1).
• Registry: Gitea at http://gitea.lan, plain HTTP, home Wi-Fi only; the Pi's Docker daemon trusts it via insecure-registries; images will be built by Gitea Actions from the owner's example workflow; until then infra/build-images.sh on the Mac pushes to gitea.lan (D-001, §10.1, §10.3). Gitea credentials, if needed, come from the owner and live in infra/secrets/ (§10.1).
• Compose stack exactly as §10.2: services caddy, server, cert-sync, backup, their images, volumes, memory limits, healthchecks, depends_on, restart: unless-stopped, json-file logging 10m × 3, TZ=Europe/Stockholm, network kvitt; .env keys exactly KVITT_REGISTRY, KVITT_TAG, HA_HOST, HA_PORT, HA_USER, HA_CERT_DIR, RCLONE_REMOTE (default gdrive:), RCLONE_FOLDER_ID.
• Files deployed to /opt/kvitt/compose.yaml, /opt/kvitt/.env, secrets in /opt/kvitt/secrets/ (§10.2, §10 intro).
• Images: server per §10.3 (M2a's Dockerfile); cert-sync = alpine + openssh-client, curl, infra/cert-sync/sync.sh under crond; backup from M2c-dev (§10.3).
• Scripts: infra/build-images.sh [tag] (buildx linux/arm64 --push, tag default short SHA, also latest, refuses a dirty tree); infra/deploy.sh <tag> (copy compose and Caddyfile over SSH, set KVITT_TAG, pull, up, wait healthy, print /health; triggers a backup and waits for last-success before a deploy with a migration); infra/publish-apk.sh (assembleRelease via tools/gradle-serial.sh, SHA-256 and size, copy to apk/kvitt-<version_code>.apk, atomic apk/latest.json, keep newest 5) (§10.3, §10.6, §10.10).
• cert-sync: at start and daily 04:00; SSH with StrictHostKeyChecking=yes; restrict,command="tar -C <cert dir> -cf - fullchain.pem privkey.pem" where the HA SSH setup allows it, and the plan records which variant the add-on supports; installs only valid, newer, changed PEMs with mode 0640, reloads Caddy through its admin API; failures keep the old certificate (§10.5.1).
• Caddyfile exactly §10.5.2; Caddy must not log Authorization (verify); fallback §10.5.3 documented in infra/README.md, not deployed (§10.5).
• Backups: daily 03:30; Drive root folder id 1jDp1dGE5R3H2DBcXCqIPN1iWzQnPkdlV as RCLONE_FOLDER_ID / --drive-root-folder-id; rclone copy --immutable, never sync, never delete on Drive; local files deleted as soon as both are confirmed on Drive with rclone lsf (D-002, §10.9, OQ-4). rclone remote [gdrive], type = drive, scope = drive, token from rclone authorize "drive" (§10.9).
• FCM key on the Pi at /opt/kvitt/secrets/fcm-service-account.json, mode 0440, group 10001 (§10.7 step 7).
• Restore steps are §10.9 1 to 7, documented in infra/RESTORE.md (§10.9).

4. Owned paths

From SPEC §14.7, verbatim: infra/** (owner "M2c-dev, then M2c-pi (D-001)"; after landing: "M10 updates runbooks").

Edit nothing outside these paths; a needed change elsewhere is a contract request to the orchestrator.

Open points the orchestrator must settle in the start prompt's notes: (a) agent access to the Kvitt Pi over SSH from the Mac (key-based login) and permission to act outside the repository (the Pi, the HA Pi, Gitea, Google Drive) per CLAUDE.md "Stay inside the repository"; (b) where the Gitea Actions workflow file lives (Gitea reads .gitea/workflows/ at a repository root, outside infra/**) and whether the repository is mirrored to Gitea (a push needs the owner's explicit ask); (c) file modes and owners on the Pi for ha_ssh_key, ha_known_hosts and rclone.conf, and the uid the cert-sync and backup containers run as (only the FCM key's mode is in §10.7).

5. Deliverables

• infra/compose.yaml: the §10.2 stack.
• infra/Caddyfile: §10.5.2 verbatim.
• infra/env.example: updated for the Pi (KVITT_REGISTRY on gitea.lan, RCLONE_FOLDER_ID 1jDp1dGE5R3H2DBcXCqIPN1iWzQnPkdlV; no secrets).
• infra/cert-sync/Dockerfile, infra/cert-sync/sync.sh: §10.5.1.
• infra/backup/backup.sh: D-002 deletion after Drive confirmation (kept local mode from M2c-dev).
• infra/build-images.sh, infra/deploy.sh, infra/publish-apk.sh: §10.3, §10.6, §10.10.
• Gitea Actions workflow from the owner's example (path per open point b).
• infra/README.md: Pi provisioning, Docker install, gitea.lan registry trust, router forwarding, HA SSH add-on key setup and which authorized_keys variant it supports, the §10.5.3 fallback, deploy and publish, operations of §10.10.
• infra/RESTORE.md: §10.9 restore steps 1 to 7, with exact commands.
• On the Pi (not in git): /opt/kvitt/compose.yaml, /opt/kvitt/.env, /opt/kvitt/secrets/{fcm-service-account.json, ha_ssh_key, ha_known_hosts, rclone.conf}.
• In infra/secrets/ on the Mac (git-ignored, main checkout): ha_ssh_key, ha_ssh_key.pub, ha_known_hosts, rclone.conf, Gitea credentials if any.

6. Steps

1. Worktree. From the main checkout /Users/jhag/projects/kvitt: git worktree add .claude/worktrees/agent-m2c-pi -b agent-m2c-pi main, then in .claude/worktrees/agent-m2c-pi: git reset --hard main. Copy infra/secrets/ from the main checkout (mkdir -p infra/secrets && cp -R /Users/jhag/projects/kvitt/infra/secrets/. infra/secrets/) and android/local.properties (needed by publish-apk.sh only). Run tools/install-git-hooks.sh.
2. Read §2 in order. Confirm OQ-3 is answered in the start prompt (or SPEC §12); without it only steps 3 to 6 can run; stop before step 7 and report.
3. Versions: resolve from official sources and record: caddy image version and digest (Docker Hub official image), alpine tag and digest, openssh-client and curl package versions in that Alpine release, Docker Engine install method for Raspberry Pi OS (docs.docker.com, Debian/Raspberry Pi OS page).
4. Write infra/compose.yaml, infra/Caddyfile, infra/cert-sync/**, the D-002 change in infra/backup/backup.sh, the three scripts, infra/README.md, infra/RESTORE.md. Generate the dedicated cert-sync key in the main checkout: ssh-keygen -t ed25519 -N '' -C kvitt-cert-sync -f /Users/jhag/projects/kvitt/infra/secrets/ha_ssh_key.
5. Run docker compose -f infra/compose.yaml config (with a .env made from infra/env.example in a temp location, never committed) and shellcheck infra/**/*.sh (globstar on).
6. Gitea Actions: write the workflow from the owner's example (H-2); until it exists, build with infra/build-images.sh on the Mac (no Gradle build running) and push to gitea.lan.
7. Pi provisioning over SSH (needs OQ-3, H-1, H-3, H-4): create /opt/kvitt/ and /opt/kvitt/secrets/; copy the secrets with the modes of open point (c) and §10.7 step 7; install insecure-registries for gitea.lan per H-4.
8. cert-sync: ssh-keyscan -p <HA port> <HA host> > /Users/jhag/projects/kvitt/infra/secrets/ha_known_hosts; the owner installs the public key (H-6); test the tar-stream variant first, fall back to plain copy if the add-on refuses authorized_keys options, and record the variant.
9. rclone: after H-7, write /Users/jhag/projects/kvitt/infra/secrets/rclone.conf with [gdrive], type = drive, scope = drive, the token; copy to the Pi.
10. Deploy: infra/deploy.sh <tag>; on the Pi docker compose ps shows all four services healthy.
11. Router: the owner sets the forward (H-5); then check https://icehack.asuscomm.com:8443/health from the phone on mobile data (H-8).
12. Backup: docker compose exec backup /backup.sh on the Pi; rclone lsf shows the new files in the Drive folder; local files are gone afterwards (D-002).
13. Verify Caddy logs contain no Authorization header (one authenticated request, then grep docker compose logs caddy).
14. Run the gate (§7). Commit on agent-m2c-pi (never a secret), git rebase main, rerun the gate. Never merge, push or remove the worktree.

7. Gate

From SPEC §11.2, verbatim: "docker compose -f infra/compose.yaml config succeeds; shellcheck infra/**/*.sh clean if shellcheck is installed; on the Pi: cert-sync fetched a valid certificate, https://icehack.asuscomm.com:8443/health answers from the phone on mobile data; one backup file appears in the Drive folder". Green means: config exits 0; shellcheck clean (or "not installed" stated); docker compose exec cert-sync shows /certs/fullchain.pem with a not-after in the future and openssl s_client -connect icehack.asuscomm.com:8443 (from the Mac) presents that certificate; the phone on mobile data gets "status":"ok" (H-8); rclone lsf lists the new kvitt-*.sqlite.gz and pictures-*.tar.gz in folder 1jDp1dGE5R3H2DBcXCqIPN1iWzQnPkdlV.

8. HUMAN steps

From SPEC §11.2, verbatim: "Answer OQ-3; provide the example Gitea Actions workflow (and Gitea credentials if the registry needs them); install Docker on the Pi if missing; set the router forward 8443 → Kvitt Pi; add the cert-sync public key to the Home Assistant SSH add-on; rclone authorize "drive"". Each with where it is needed, the exact command, and what blocks it (OQ-1 and OQ-4 are answered; OQ-3 is the only open question):

• H-1, before step 7: answer OQ-3 (Kvitt Pi LAN address and SSH user; HA Pi LAN address, SSH port and user; certificate directory; which SSH add-on). Blocks H-3, H-5, H-6 and steps 7 to 13.
• H-2, step 6: provide the example Gitea Actions workflow, and Gitea credentials if push or pull needs them. Not blocked by an open question; blocks only the Gitea Actions part (manual build-images.sh works meanwhile, unless credentials are required).
• H-3, step 7, on the Kvitt Pi (only if docker version fails there), using the method from docs.docker.com for Raspberry Pi OS, for example: curl -fsSL https://get.docker.com -o get-docker.sh && sudo sh get-docker.sh && sudo usermod -aG docker <ssh user>, then log out and in. Blocked by OQ-3.
• H-4, step 7, on the Kvitt Pi (sudo; derived from §10.3, not a separate §11.2 step): add {"insecure-registries": ["gitea.lan"]} to /etc/docker/daemon.json and run sudo systemctl restart docker. Blocked by OQ-3.
• H-5, step 11, in the ASUS router web interface: WAN, Virtual Server / Port Forwarding: add a TCP rule, external port 8443, internal IP = the Kvitt Pi's LAN address, internal port 8443; Apply. Blocked by OQ-3.
• H-6, step 8, in Home Assistant: Settings, Add-ons, , Configuration: add the one line from infra/secrets/ha_ssh_key.pub (with the restrict,command=… prefix the agent gives) to authorized_keys; Save; restart the add-on. Blocked by OQ-3.
• H-7, step 9, on the owner's Mac: rclone authorize "drive", sign in with the owner's Google account in the browser, and leave the terminal output for the agent (the agent reads the token from the terminal session or the owner pastes it into a file the agent names inside infra/secrets/). Not blocked (OQ-4 answered). Needs rclone installed on the Mac.
• H-8, step 11 (needed by the gate): on the phone with Wi-Fi off, open https://icehack.asuscomm.com:8443/health in Chrome; answer yes/no: the page shows "status":"ok" without a certificate warning. Blocked by H-5.
• Prerequisite not listed in §11.2 (open point a): key-based SSH login from the Mac to the Kvitt Pi, for example ssh-copy-id <ssh user>@<Kvitt Pi address> on the owner's Mac. Blocked by OQ-3.

9. Out of scope

• The development stack infra/dev/** (M2c-dev; do not break it).
• Firebase project and app creation (done in M2c-dev); only copying the key to the Pi is here.
• Release keystore, signed release, publishing the first real APK, pairing both phones, restore drill, memory check (M10).
• Server or Android code changes; the Splitwise import (M11).
• Changing the Home Assistant Pi beyond adding the one authorized_keys line; touching certbot there.

10. Report

• Branch agent-m2c-pi, head commit hash after rebasing on main.
• Gate output lines: config exit status, shellcheck result, certificate not-after and issuer, phone health result (H-8), rclone lsf lines (file names only).
• Versions chosen (images with digests, packages, Docker install method) with sources.
• The authorized_keys variant the HA add-on supports.
• Image tag deployed; docker compose ps summary.
• Paths of secrets written (never contents), modes set on the Pi.
• How open points (a) to (c) were resolved.
• Numbering used or TODO(spec) occurrences.
• HUMAN steps done and outstanding, worded for relay.
• Contract requests, open questions, spec gaps (with section numbers).

11. Numbering

Decision ids, spec version and schema version are assigned by the orchestrator in the start prompt; use TODO(spec) if none was given.