WebForm-mw/AMPLIFY_DEPLOY.md

# Deploying to AWS Amplify Hosting

First-time walkthrough for shipping this app on AWS Amplify Hosting. Amplify
auto-detects Next.js, runs the build, and routes SSR pages + API routes
through managed Lambda behind a CloudFront CDN. The `amplify.yml` and
`.nvmrc` in this repo are the only pieces Amplify needs from the codebase.

## Before you start

- An AWS account with billing enabled. Amplify Hosting has a free tier
  (1,000 build minutes + 15 GB served + 100 GB-hours of SSR Lambda per
  month for the first year) — typical traffic for this app stays comfortably
  inside it.
- GitHub access to `joelbrock/WebForm-mw`. Amplify connects via OAuth or a
  GitHub App; either works.
- The three required CiviCRM env vars in hand: `CIVI_BASE_URL`,
  `CIVI_API_KEY`, `CIVI_SITE_KEY`. Plus the optional `CIVI_HTTP_AUTH_*`
  pair if CiviCRM sits behind webserver-level Basic Auth.

## Step 1 — Create the Amplify app

1. Open the Amplify console: <https://console.aws.amazon.com/amplify/>
   - Pick a region near you / near CiviCRM. `us-east-1` (N. Virginia) is
     the default and has the lowest cold-start latency for most setups.
2. Click **Create new app** → **Host web app**.
3. Choose **GitHub** as the source. Authorize Amplify if prompted.
   The first time, AWS will install a GitHub App on your account; grant
   it access just to `joelbrock/WebForm-mw` (not "all repos").
4. Pick the repo `joelbrock/WebForm-mw` and the `main` branch.
5. **App name:** something like `coop-checkin` (this becomes the
   `*.amplifyapp.com` subdomain).
6. Amplify reads `amplify.yml` automatically; you do not need to edit
   the build spec on this screen. Click **Next**.

## Step 2 — Environment variables and Secrets

Amplify Gen 2 splits configuration across **two separate pages** in the
console sidebar (under **Hosting**):

- **Environment variables** — plaintext-at-rest, intended for non-sensitive
  config. Readable by anyone with `amplify:GetApp` permission on the AWS
  account.
- **Secrets** — values stored in AWS Systems Manager Parameter Store as
  SecureString, encrypted at rest. Injected into the build/runtime as
  normal environment variables under the same name, so application code
  doesn't need to know the difference.

Add each variable to the page indicated below:

| Variable | Page | Notes |
|---|---|---|
| `CIVI_BASE_URL` | Environment variables | e.g. `https://crm.fci.coop` |
| `CIVI_API_KEY` | **Secrets** | Required |
| `CIVI_SITE_KEY` | **Secrets** | Required |
| `CIVI_HTTP_AUTH_USER` | Environment variables | Only if CiviCRM has webserver-level Basic Auth in front of it |
| `CIVI_HTTP_AUTH_PASS` | **Secrets** | Only if above set |
| `HEALTH_TOKEN` | **Secrets** | Optional; gates `/api/health` in production |
| `PREVIEW_ADMIN_TOKEN` | **Secrets** | Optional; gates `/api/preview-link` |
| `STAFF_REPORT_KEY` | **Secrets** | Shared secret for `/staff/report` and `/api/staff/file` |

**`STAFF_REPORT_KEY`** — shared secret guarding the internal staff report
at `/staff/report` and the file proxy at `/api/staff/file`. Store in
Amplify SSM Parameter Store next to the `CIVI_*` secrets. Rotate by
changing the env value; all live links must be updated. Anyone with the
secret can view any organization's full activity history.

Rule of thumb: if leaking the value would let someone impersonate the app
to CiviCRM, or bypass a gate, it goes in **Secrets**. Hostnames and
usernames are fine in plaintext Environment variables.

> **Don't set `NODE_ENV=production` in either page.** Amplify and Next
> already set it correctly at runtime; setting it at build time causes
> `npm ci` to skip devDependencies, which breaks the Tailwind/PostCSS
> step. The `amplify.yml` in this repo guards against this with
> `--include=dev`, but it's cleaner not to set it at all.

> **Don't duplicate names across both pages.** If the same variable
> name appears in both Environment variables and Secrets, Amplify's
> precedence is undefined in Gen 2.

Click through, review, **Save and deploy**.

## Step 3 — First build

The first build takes about 4–6 minutes (later builds are 2–3 with cache).
You can watch progress in the **Hosting environments** view. When it
completes, three things are confirmed:

- The build succeeded → `next build` produced `.next/`.
- SSR functions deployed → API routes and dynamic pages have a Lambda
  function behind them.
- The app is reachable at `https://main.<random>.amplifyapp.com`.

Smoke-test the deploy:

```
https://main.<random>.amplifyapp.com/healthz
```

Should return `200 OK` (lightweight platform check, doesn't hit CiviCRM).

If you set `HEALTH_TOKEN`, the richer diagnostic at
`/api/health?token=<value>` will probe the CiviCRM connection itself —
useful to confirm env vars are wired correctly.

## Step 4 — Custom domain (optional)

Amplify can attach a custom domain (e.g. `survey.fci.coop`) with
auto-issued TLS in a few minutes:

1. In the app, **Hosting** → **Custom domains** → **Add domain**.
2. Enter the apex (`fci.coop`) or a subdomain.
3. Amplify suggests DNS records (CNAME / ALIAS). Add them at your DNS
   provider (Cloudflare, Route53, Namecheap, etc.).
4. Wait 5–15 minutes for validation and certificate issuance.

The `*.amplifyapp.com` URL keeps working alongside the custom domain.

## Step 5 — Per-PR previews (optional, recommended)

Amplify can build a preview environment for every pull request:

- **Hosting** → **Previews** → enable for the `joelbrock/WebForm-mw` repo.
- PRs get their own `https://pr-<num>.<random>.amplifyapp.com` URL,
  posted as a comment on the PR.
- Previews inherit the main branch's environment variables unless you
  override on the preview branch.

Useful for reviewing form changes against live CiviCRM DEV before merging.

## What it'll cost

Realistic estimate for this app's expected traffic (a few hundred
form/report loads per month, very modest API throughput):

- **Hosting (CDN + static)**: pennies. Free tier covers it.
- **SSR Lambda**: ~$0.05–$0.50/month depending on traffic. Each form load
  triggers a couple of API calls into CiviCRM via Lambda; each call is a
  short-lived invocation.
- **Build minutes**: free tier covers up to ~300 small builds/month.

Expect **<$5/month** total at launch traffic. If usage grows
significantly, the costs scale roughly linearly with Lambda invocations.

## Things to know going in

- **Cold starts.** First request after a quiet period adds 500–1500ms of
  Lambda init. Subsequent requests reuse the warm container. For an
  internal-use form this is fine; users see the loading state during
  init.
- **Outbound IPs are not static.** Amplify SSR Lambda functions egress
  through AWS-managed IPs that change. If CiviCRM has an IP allowlist
  on its API, this won't work out of the box — you'd need a VPC + NAT
  Gateway + Elastic IP setup (significantly more complex). Most
  CiviCRM auth uses API keys, not IP allowlisting, so this usually
  isn't an issue.
- **No Render-style background workers.** Amplify is request/response
  only. Anything cron-shaped needs EventBridge + a separate Lambda.
  The current app doesn't have background jobs, so this doesn't apply.
- **Logs live in CloudWatch.** Each SSR function has its own log group;
  click into the function from the Amplify app view to jump to logs.
  Retention defaults to "never expire" — switch to 30 days unless you
  need more.
- **Secrets rotate manually.** No auto-rotation. To rotate
  `CIVI_API_KEY`, update it in Amplify env vars → trigger a redeploy.
- **`render.yaml` is now informational.** It's still in the repo for the
  Render path; Amplify ignores it. If you commit fully to Amplify and
  abandon Render, the `render.yaml` and the Render section of
  `DEPLOYMENT.md` can be removed.

## When something breaks

- **Build fails on `npm ci`** → usually a Node version mismatch. The
  `.nvmrc` pins Node 20; if Amplify's build image doesn't have it, the
  `amplify.yml` `nvm install` falls back. Open the build log, search
  for "Node version".
- **Build fails on `next build`** → typecheck or lint error. Reproduce
  locally with `npm run build`.
- **Site builds but routes 503** → SSR Lambda misconfig. Check the
  function's CloudWatch logs for the actual error. Most common cause:
  missing required env var (the app refuses to boot in production stub
  mode and the `lib/env.ts` validator throws).
- **CiviCRM calls fail with 401** → API key or Basic Auth credentials
  wrong. Re-check `CIVI_API_KEY` and `CIVI_HTTP_AUTH_*` in the Amplify
  env-vars panel; redeploy after changes.

## After the first successful deploy

- Bookmark the Amplify app URL and the CloudWatch log group.
- Run the email/link smoke test from `EMAIL_DELIVERY.md` against the
  Amplify URL to confirm `/api/preview-link` produces working tokenized
  URLs end-to-end.
- Update any docs / staff runbooks pointing at the old Render URL.