where_woof/openspec/changes/deploy-frontend/design.md

Context

The GOAT frontend is verified on .27 (dev). Production target per the plan: .13:/var/www/where-woof, port :3020, behind Caddy on .35, domain where-woof.com (currently at InMotion, DNS to be repointed). The DB already lives on .13 (wherewoof-db, :5434). .13 uses systemd user services (lan-mouse, engram) — the established pattern for app processes there. The Caddy block is already saved by the user.

Goals / Non-Goals

Goals:

• Frontend live on .13:3020 as a managed, restart-on-failure service.
• Reproducible build+rsync deploy step; secrets on .13 only.
• Caddy block verified; DNS/InMotion redirect documented as the user step.

Non-Goals:

• Admin (Laravel) deploy — Phase 8.
• TLS/cert automation specifics (Caddy handles it).
• Rolling deploys / zero-downtime — single binary, quick restart is fine.

Decisions

1. systemd user service (~/.config/systemd/user/where-woof.service) with Restart=on-failure, EnvironmentFile=/home/sam/.config/where-woof.env (chmod 600) holding DATABASE_URL, SESSION_SECRET, SMS_USER, SMS_PASSWORD, SMS_FROM. Matches .13 conventions (lan-mouse) and keeps secrets out of the repo. systemctl --user enable --now where-woof.
2. Run from /var/www/where-woof — the app resolves templates/ + static/ relative to cwd (proven in dev); WorkingDirectory=/var/www/where-woof. Uploads dir pre-created + writable.
3. Build on .27, rsync binary+assets (no Go on .13). make build exists; add make deploy → rsync + restart.
4. DB on localhost: the .13 service uses postgres://wherewoof:...@localhost:5434/wherewoof (container on .13).
5. Caddy/DNS: block already saved on .35; verify where-woof.home.lab → .35 → .13:3020 end-to-end once running. DNS repoint of where-woof.com (InMotion → .35) is the user's final step.

Risks / Trade-offs

• [Secrets in a plaintext file on .13] → chmod 600, matches existing convention; never committed.
• [Port 3020 conflicts] → verified free on .13.
• [Uploads lost on redeploy if rsync --delete] → do NOT use --delete on static/; keep uploads untouched.
• [systemd user service needs lingering for boot] → loginctl enable-linger sam so it starts at boot without login.

Migration Plan

1. make build on .27.
2. rsync binary + templates + static (no --delete) → /var/www/where-woof; chown sam:users; mkdir uploads.
3. Write env file (chmod 600) + unit file; systemctl --user daemon-reload && enable --now.
4. Verify: curl localhost:3020 on .13; then from .27 via 192.168.20.13:3020; then via Caddy home.lab if DNS local resolves.

Open Questions

• Whether to run real SMS creds on the live service now (suggest: yes — the account has funds, log sender would silently skip alerts otherwise).