diff --git a/docs/deploy-phase1.md b/docs/deploy-phase1.md new file mode 100644 index 0000000..ce7ac91 --- /dev/null +++ b/docs/deploy-phase1.md @@ -0,0 +1,76 @@ +# Phase 1 deployment runbook — `mail.lab.audasmedia.com.au` + +Status: **prepared, not executed.** The deploy is [AUD-61](/AUD/issues/AUD-61) and is +blocked on [AUD-58](/AUD/issues/AUD-58) (Phase 1.1 skeleton) and +[AUD-59](/AUD/issues/AUD-59) (Phase 1.2 login + dashboard). Do not run these steps +until both are done. + +## Target + +| Item | Value | +|---|---| +| App host | `.13` (`192.168.20.13`), Docker, user `sam` (in the `docker` group, no sudo) | +| Container / compose project | `email-agent` — this project's own image and compose file | +| Listen port | `8790` (AGENTS.md §9) | +| Public URL | `https://mail.lab.audasmedia.com.au` | +| Reverse proxy | Caddy on `.35` (`192.168.20.35`), container `caddy`, config `/Docker/Containers/caddy/Caddyfile` | + +## Verified facts (from [AUD-60](/AUD/issues/AUD-60), 2026-10-11) + +- Port 8790 is free on `.13`. In 8780–8800 only 8787 (headroom) and 8788 (hub) are used. +- Deploy convention on `.13` is one directory per stack at + `/home/sam/Docker/Containers//` holding a `docker-compose.yml`, then + `docker compose up -d` as `sam`. Source stays in this repo. +- `*.lab.audasmedia.com.au` is a wildcard DNS record to the external IP. No new record is needed. +- Caddy issues the Let's Encrypt certificate on the first request. Peer hosts such as + `prefect.lab` already serve valid certificates. +- Caddy reload works: `docker exec caddy caddy reload --config /etc/caddy/Caddyfile --adapter caddyfile`. +- Not confirmed: the external 80/443 port-forward to `.35`. It is inferred from the working + peer certificates. If `mail.lab` fails to obtain a certificate, check the port-forward first. +- `tokens.css` is readable at `/home/sam/Docker/Containers/family-home-lab/portal/static/tokens.css` + (needed by AUD-59, not by the deploy). + +## Steps + +1. **Confirm the blockers are done.** AUD-58 and AUD-59 are both `done`. +2. **Build and start on `.13`** from this repo: + ```sh + docker compose build + docker compose up -d + docker compose ps + ``` + Set `EMAIL_AGENT_SESSION_SECRET` in the host environment before the login phase + (AUD-59 records the secret name; never commit the value). +3. **Check the service locally on `.13`** + ```sh + curl -fsS http://127.0.0.1:8790/health + ``` + Expect HTTP 200 and `"status":"ok"`. +4. **Add the Caddy route on `.35`.** Append to `/Docker/Containers/caddy/Caddyfile`: + ``` + mail.lab.audasmedia.com.au { + reverse_proxy 192.168.20.13:8790 + } + ``` +5. **Reload Caddy** + ```sh + docker exec caddy caddy reload --config /etc/caddy/Caddyfile --adapter caddyfile + ``` +6. **Verify the public URL** + ```sh + curl -fsS https://mail.lab.audasmedia.com.au/health + ``` + Expect HTTP 200 and a valid certificate. + +## Phase 1 Definition of Done checklist + +- [ ] The app runs on `.13` (`docker compose ps` shows `email-agent` up and healthy). +- [ ] Login works (redirect from `/` to login, log in with the configured password). +- [ ] The empty dashboard renders. +- [ ] `/health` returns ok — locally and through `https://mail.lab.audasmedia.com.au`. +- [ ] Verified from a phone browser. + +## Rollback + +1. Remove the `mail.lab.audasmedia.com.au` block from the Caddyfile and reload Caddy. +2. `docker compose down` in this repo (keeps the `email_agent_data` volume).