adr-sml/docs/06-deployment.md

# 06 — Deployment and cutover

Authority: `AGENTS.md` §3 D3 (git + GitHub Actions → existing S3/CloudFront) and
D11 (build everything, one clean cutover).
Existing infrastructure: `AWS-Hosting-Guide.md`.

---

## Topology

```
GitHub push to main
  └─ GitHub Actions
       ├─ npm ci && npm run build        → ./dist
       ├─ assume AWS role via OIDC        (no stored keys)
       ├─ aws s3 sync ./dist s3://<bucket>
       └─ cloudfront create-invalidation
Namecheap DNS → CloudFront → S3 (OAC)
API Gateway → Lambda → DynamoDB / SES     (intake, unchanged path)
```

DNS is at **Namecheap, not Route 53** `[verified 2026-08-25]`. Nothing in the
pipeline touches DNS. Certificate renewal is ACM-automatic as long as the
validation CNAME stays in place at Namecheap — **do not delete it.**

## CI runs on Gitea, not GitHub

`AGENTS.md` D3 as amended, 2026-08-26: self-hosted **Gitea**, repo `adr-sml`,
local clone at `/Users/pouya/Dev/Websites/adr-sml`.

**The live pipeline is `.gitea/workflows/deploy.yml`.** Gitea Actions speaks
GitHub Actions syntax, so it is a near-direct port — the build steps, the
two-pass sync, and the cache headers are unchanged. `.github/workflows/deploy.yml`
stays in the repo as the OIDC reference in case the project ever moves.

### The one real difference: no OIDC

Gitea is not an AWS OIDC provider. There is no role to assume, so deploys
authenticate with a **scoped IAM user** whose access key lives only in the
repository's Gitea secrets.

This is a genuine step down in security from the GitHub setup, and it should be
treated as one. The mitigations are the policy scope and the rotation schedule.

**Create the user:**

1. IAM → Users → `adr-sml-deploy`. **Programmatic access only** — no console
   password, no MFA device, no group membership.
2. Attach this inline policy and nothing else. Substitute the real bucket name,
   account ID, and distribution ID from `scripts/aws-discover.sh`:

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ListSiteBucket",
      "Effect": "Allow",
      "Action": "s3:ListBucket",
      "Resource": "arn:aws:s3:::BUCKET_NAME"
    },
    {
      "Sid": "WriteSiteObjects",
      "Effect": "Allow",
      "Action": ["s3:PutObject", "s3:PutObjectAcl", "s3:DeleteObject"],
      "Resource": "arn:aws:s3:::BUCKET_NAME/*"
    },
    {
      "Sid": "InvalidateOneDistribution",
      "Effect": "Allow",
      "Action": "cloudfront:CreateInvalidation",
      "Resource": "arn:aws:cloudfront::ACCOUNT_ID:distribution/DISTRIBUTION_ID"
    }
  ]
}
```

No `s3:*`. No `cloudfront:*`. No wildcard resources. If a deploy step needs a
permission this policy lacks, the correct response is to question the step, not
to widen the policy.

3. Create an access key. **Copy it once** — AWS will not show the secret again.

### Gitea configuration

**Repository → Settings → Actions → Secrets:**

| Name | Value |
|---|---|
| `AWS_ACCESS_KEY_ID` | from the IAM user |
| `AWS_SECRET_ACCESS_KEY` | from the IAM user |

**The real values** (captured 2026-08-26, `aws-inventory.txt`):

| Variable | Value |
|---|---|
| `AWS_REGION` | `ca-central-1` |
| `S3_BUCKET` | `adr-smlcompany-site` |
| `CLOUDFRONT_DISTRIBUTION_ID` | `E1OK7G98KNKUTA` |
| `INTAKE_ENDPOINT` | `https://4tl0m5igkj.execute-api.ca-central-1.amazonaws.com` |
| `BOOKING_URL` | *(empty — parked, R6)* |

IAM policy substitutions: `BUCKET_NAME` = `adr-smlcompany-site`,
`ACCOUNT_ID` = `327082975128`, `DISTRIBUTION_ID` = `E1OK7G98KNKUTA`.

> **Read this before creating the key.** Account `327082975128` is shared across
> `meshkinilaw.ca`, `demesne.media`, `orynenergy.ca`, `lajirugs.ca`, and
> `mlp-clientdb-prod-backups` — a law firm's client-database backups. A static
> deploy key for a marketing site lives in the same account. The scoped policy is
> what keeps a compromised Gitea runner from reaching any of that. Do not widen
> it, and never put the `user/pouya` credentials in CI.

**Repository → Settings → Actions → Variables** (not secrets — these are not
sensitive, and keeping them as variables means they appear in run logs where they
are useful for debugging):

| Name | Value |
|---|---|
| `AWS_REGION` | e.g. `ca-central-1` |
| `S3_BUCKET` | the site bucket |
| `CLOUDFRONT_DISTRIBUTION_ID` | the `E...` ID |
| `INTAKE_ENDPOINT` | API Gateway invoke URL |
| `BOOKING_URL` | once chosen (Q5) |

### A runner must exist

Gitea Actions needs `act_runner` registered to this repository or its
organisation, and Actions enabled both site-wide in `app.ini`
(`[actions] ENABLED = true`) and per-repository. Without a runner the workflow
queues silently and never runs — which looks exactly like a broken pipeline.

The workflow installs the AWS CLI if the runner image lacks it, and runs
`aws sts get-caller-identity` before touching anything, so a credential problem
fails loudly and early rather than halfway through a sync.

### Key rotation — an operational obligation

**Rotate `adr-sml-deploy` quarterly.** OIDC would have made this unnecessary;
with a static key it is a standing task:

1. Create a second access key on the same user.
2. Update the Gitea secrets.
3. Run the workflow and confirm it succeeds.
4. **Delete the old key.** Rotation that leaves the old key active is not
   rotation.

Set a calendar reminder. A key that is never rotated is the failure mode this
whole section exists to bound.

## Finding the AWS identifiers

`scripts/aws-discover.sh` collects everything Q10 needs — bucket, distribution
ID, regions, API endpoint, certificate, SES identities, and whether S3 versioning
is on. Read-only; every call is a list or describe.

```bash
chmod +x scripts/aws-discover.sh
./scripts/aws-discover.sh > aws-inventory.txt
```

The output contains resource names and IDs but no secrets.

## Why OIDC and not access keys

The alternative is a long-lived `AWS_ACCESS_KEY_ID` in GitHub secrets: a
credential that never expires, is invisible once set, and grants its permissions
to anyone who can reach the repository. OIDC issues a short-lived token per run,
scoped to this repository and this branch.

One-time setup:

1. IAM → Identity providers → add OIDC provider `token.actions.githubusercontent.com`,
   audience `sts.amazonaws.com`.
2. Create role `adr-site-deploy` trusting that provider, with a condition on
   `token.actions.githubusercontent.com:sub` equal to
   `repo:<org>/<repo>:ref:refs/heads/main` (**Q9**).
3. Attach a policy granting **only**: `s3:PutObject`, `s3:DeleteObject`,
   `s3:ListBucket` on the site bucket, and `cloudfront:CreateInvalidation` on the
   one distribution. Nothing else. No `s3:*`, no `cloudfront:*`.
4. Store the role ARN, bucket name, and distribution ID as repository
   **variables** (they are not secrets), and reference them in the workflow.

## Cache policy

The mistake to avoid is caching HTML aggressively — a stale index page is a site
that does not update.

| Pattern | `Cache-Control` |
|---|---|
| `*.html` | `public, max-age=0, must-revalidate` |
| `/_astro/*` (hashed) | `public, max-age=31536000, immutable` |
| Fonts | `public, max-age=31536000, immutable` |
| Images | `public, max-age=604800` |
| `robots.txt`, `sitemap*.xml` | `public, max-age=3600` |

Sync in two passes: hashed assets first with the long TTL, then HTML with the
short one. Uploading HTML last means a user never fetches a new page whose assets
have not landed yet.

Invalidate `/*` on deploy. At this traffic volume the cost is nil, and partial
invalidation paths are a reliable source of confusing bugs.

## CloudFront configuration

- Origin: S3 with **Origin Access Control**, bucket not public. The guide's
  Part 2.2 bucket policy already does this — verify it was not loosened.
- Redirect HTTP → HTTPS. TLS 1.2 minimum.
- Default root object `index.html`.
- **Custom error response:** 404 → `/404.html` with **response code 404**, not
  200. Returning 200 for a missing page tells crawlers every bad URL is real
  content, and it is the single most common misconfiguration in this stack.
- Compression on. Response-headers policy from `05-backend-spec.md`.
- A CloudFront Function for trailing-slash normalisation, so `/about` and
  `/about/` do not both resolve as separate indexable URLs.

## Branch model

`main` is production; every push deploys. Work on short-lived branches, open a
PR, let CI build and run Lighthouse, merge.

**Pull request checks (blocking):** `npm run build` · `astro check` · lint ·
Lighthouse CI against the budgets in `04-seo-spec.md` · link check.

Tag every production deploy `v<year>.<n>` so a rollback has something to name.

## Rollback

1. Re-run the workflow at the last good tag, or
2. `git revert` and push, or
3. Restore from S3 object versioning — **enable versioning on the bucket if it is
   off**; it is the difference between a rollback and a rebuild.

Then invalidate `/*`.

## Cutover checklist — D11 is a single shot, so run all of it

**Content and compliance**
- [ ] Every claim traced to `AGENTS.md` §4 Verified
- [ ] No `TODO(pouya)` remains in any shipped page
- [ ] No matter counts, rates, dollar figures, or testimonials anywhere
- [ ] Q.Arb described as in progress everywhere it appears
- [ ] `/fees/` carries real numbers (Q4) or the page does not ship
- [ ] Privacy policy matches the backend as actually built

**Technical**
- [ ] Lighthouse ≥ 95 mobile on `/`, `/about/`, a practice page, an article
- [ ] Every page renders fully with JavaScript disabled
- [ ] `curl` of each URL returns real content, not a shell
- [ ] All internal links resolve; no orphan pages
- [ ] Sitemap generated and correct; `robots.txt` served, not 403
- [ ] Rich Results Test passes; OG previews render in LinkedIn and Slack
- [ ] 404 returns a 404 status
- [ ] Security headers present (`securityheaders.com` A or better)
- [ ] **SES identities verified for sending** (Q18) — `aws sesv2 get-email-identity --email-identity smlcompany.ca` and confirm `VerifiedForSendingStatus: true`
- [ ] **SES out of the sandbox** (Q19) — `aws sesv2 get-account --query 'ProductionAccessEnabled'`. In sandbox, mail reaches only pre-verified addresses and the inquirer's confirmation silently fails
- [ ] Intake form tested end to end: DynamoDB record written to `adr-intake-submissions`, both emails delivered to a real inbox, TTL set
- [ ] Booking link works, including the no-JavaScript fallback
- [ ] Favicon set complete
- [ ] Tested on iOS Safari, Android Chrome, desktop Safari/Chrome/Firefox
- [ ] Tested at 320 px and at 200% zoom

**Infrastructure**
- [ ] S3 versioning enabled
- [ ] Bucket not publicly readable; OAC in force
- [ ] ACM certificate valid; Namecheap validation CNAME still present
- [ ] CloudWatch alarms: Lambda errors, DLQ depth, 5xx rate
- [ ] Billing alarm still active (guide Part 0.3)

**Post-cutover, same day**
- [ ] Sitemap submitted to Google Search Console and Bing Webmaster Tools
- [ ] Live site fetched as an anonymous crawler to confirm indexable content
- [ ] LinkedIn profile and ADRIC/ADRIO listings updated to point here
- [ ] Archive the old single-file build to `_archive/` — do not delete it
- [ ] `AGENTS.md` Change Log entry recording the cutover