ResumeSite/docs/spec/DEPLOYMENT_SPEC.md

DEPLOYMENT_SPEC.md

1. Environments

Env	Where	Purpose	URL
dev	Local (Docker compose dev stack)	Inner loop, HMR	localhost:4321
staging	Same server, separate compose project	Pre-release verification on real infra (headers, proxy, relay SMTP against a mailbox test)	staging.cesnimda.co.uk (basic-auth gated at the proxy, noindex everywhere)
prod	Server, compose stack resumesite	Live	cesnimda.co.uk

Staging exists chiefly for the cutover and for occasional risky changes; day-to-day content edits may go dev → prod (single-owner pragmatism, gates make it safe).

2. Pipeline (Gitea Actions, all self-hosted)

push / PR to main
  ├─ lint + typecheck + astro check
  ├─ unit (vitest: i18n parity, slug-map bijection, JSON-LD builders)
  ├─ build site (static)  ──► Playwright e2e vs built output + relay container
  │                        ──► axe a11y scan (both locales, both themes)
  │                        ──► Lighthouse CI budgets (fail = red)
  ├─ build + push images  :sha and :latest  → Gitea registry        (main only)
  └─ deploy job (main only, manual approval toggle):
        ssh to server → compose pull → compose up -d → smoke check
        (curl /, /no/, /api/contact healthz, spot-check headers) → notify

• Rollback: redeploy previous :sha tag (one command, documented runbook); HTML no-cache means rollback is immediate. Registry retains last N images.
• Content-only changes ride the same pipeline — content errors are build errors by design (schema + parity tests), which is the safety that replaces CMS preview.
• Scheduled workflow (weekly): external link check (DATA_MODEL §8.6) + Lighthouse drift report + Renovate PRs.

3. Cutover plan (WordPress → new site)

1. Pre-launch: staging fully verified (both locales, CV downloads, form → real mailbox, redirects incl. /Linkedin, 410 map, OG previews via LinkedIn/Slack debuggers, Search Console fetch).
2. URL inventory + redirect/410 map finalised (SEO_SPEC §6).
3. Cutover = move the cesnimda.co.uk Traefik Host router from the WordPress container to the site container (a label change + compose up -d; WP left running dark for 2 weeks as instant rollback).
4. Post-launch checklist: submit sitemaps, watch Search Console coverage + relay logs for form spam patterns, then decommission WP + its PHP/MySQL surface (attack-surface win worth noting on the colophon).

4. Operational guardrails

• Uptime: monitored by existing homelab monitoring (add checks: / 200 + content match, /no/ 200, relay healthz); alerting via his current channel.
• TLS: unchanged at the existing edge proxy (already terminating for Gitea etc.).
• Logs: site-nginx access logs minimal (no query bodies, standard rotation); relay logs metadata only (timestamp, IP hash, outcome) — privacy stance documented on colophon.
• CV updates: replace PDF in repo → pipeline redeploys; stable URLs mean previously shared links always fetch the newest CV — an explicit product decision.
• Secrets rotation: SMTP credential rotation runbook (env file update + compose up -d relay), noted in deploy README.

5. Definition of Done for Phase 3 (deployment perspective)

1. All CI gates green on main; images in registry.
2. Staging sign-off checklist complete (incl. native-Norwegian content review — I18N_SPEC §6).
3. Cutover executed; WP dark-standby; monitoring green 48h.
4. Search Console: sitemaps accepted, no coverage regressions after 4 weeks (watch item, not blocker).
5. Colophon page published describing the stack honestly (the P2 hook).