# Deployment Architecture: Unit 3 "hosting-and-targets" Rules and rationale: [infrastructure-design.md](infrastructure-design.md) (`BR-HST-xx`). Requirements: FR-PR-14 to 18, 23; NFR-PR-P-01, P-02, S-01. Based on the frontend-shell [deployment plan](../../../../frontend-shell/operations/deployment/deployment-plan.md) and [instructions](../../../../frontend-shell/operations/deployment/deployment-instructions.md); only differences are described here. ## 1. Topology ```mermaid graph LR Visitor["Visitor or Lighthouse"] Dev["Developer PC"] Gitea["Gitea Actions on the Pi runner"] Artifact["Build artifact: dist/client"] Proxy["Proxy Pi: nginx and certbot, TLS"] HostPi["Hosting Pi: nginx test block and WordPress"] Webhost["Webhost: IIS with web.config"] Preview["Preview server on dist/client"] Dev -->|"push or merge"| Gitea Gitea --> Artifact Artifact -->|"scp, test only"| HostPi Artifact -->|"FTPS, release branch only"| Webhost Artifact --> Preview Visitor -->|"test.andreaslop.nl"| Proxy Proxy -->|"HTTP, Host header kept"| HostPi Visitor -->|"andreaslop.nl after DNS switch"| Webhost Preview -->|"Lighthouse and browser tests"| Gitea classDef client fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000; classDef gateway fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000; classDef service fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000; classDef database fill:#fbd38d,stroke:#92400e,stroke-width:1px,color:#000; classDef external fill:#e9d5ff,stroke:#6b21a8,stroke-width:1px,color:#000; class Visitor,Dev client; class Proxy gateway; class Gitea,Preview service; class Artifact database; class HostPi,Webhost external; ``` Text alternative: the developer pushes to Gitea, which builds one artifact; test receives it over scp on the hosting Pi behind the proxy Pi, production receives it over FTPS on the IIS webhost, and the preview server serves the same files to Lighthouse and the browser tests. | Component | Environment | Role in this unit | Managed by | |---|---|---|---| | Proxy Pi nginx (`test.andreaslop.nl.conf`, certbot) | Test | TLS and pass-through; no URL logic; optional `proxy_http_version 1.1` | Human (H4) | | Hosting Pi nginx (`andreaslop-test.conf`) | Test | All URL, 404, header and compression rules | Generated, installed by hand (H2) | | Webhost IIS (`web.config`) | Production | Same rules, uploaded with every deploy | Generated, automatic | | Preview server (`previewServer.ts`) | CI and local | Same contract for Lighthouse and browser tests | Code | | `verify-deployment.sh` | CI | Post-deploy proof against the build | Code | | `iis-probe/` | Webhost, once | Finds locked sections without risking the site | Generated, uploaded by hand (H5) | ## 2. Upload order, production (BR-HST-14, 15) ```mermaid graph TD Art["Artifact dist with index.html at its root"] --> Guard["Guard: required files present, no server folder, no source maps"] Guard --> Cfg["Copy web.config variant into dist"] Cfg --> P1["Pass 1: all files except html and web.config, including /assets"] P1 --> P2a["Pass 2a: web.config"] P2a --> P2b["Pass 2b: all html including nested pages and 404.html"] P2b --> P3["Pass 3: mirror with delete removes stale files"] P3 --> Chk["verify-deployment.sh against the live host"] classDef service fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000; classDef gateway fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000; classDef database fill:#fbd38d,stroke:#92400e,stroke-width:1px,color:#000; class Art,Cfg database; class Guard,Chk gateway; class P1,P2a,P2b,P3 service; ``` Text alternative: after a guard and the `web.config` copy, assets go up first, then `web.config`, then all HTML, then a delete pass, and finally the post-deploy script checks the live host. Why this order: new hashed assets are harmless next to the old release, so they go first. New HTML refers to them only after they exist. The `web.config` goes just before the HTML because its rules (`/x` to `x.html`) fit the new files, and the old SPA index is replaced seconds later. The delete pass runs last, so old hashed assets stay available for visitors who still hold the old HTML until the new HTML is complete. The first deploy happens before DNS moves, so the one-time mismatch (new rules, old files) has no visitors. Sketch of the lftp section (final syntax proven in V10): ```text mirror --reverse --verbose --exclude-glob '*.html' --exclude-glob web.config dist/ $FTP_DIR/; put -O $FTP_DIR dist/web.config; mirror --reverse --verbose --include-glob '*.html' dist/ $FTP_DIR/; mirror --reverse --delete --verbose dist/ $FTP_DIR/; ``` `--exclude-glob index.html` is gone. The test deploy is unchanged except for the added guard and the new post-deploy script (BR-HST-16). ## 3. Test deploy and nginx rollout ```mermaid graph TD Cur["Today: old SPA build and old nginx config"] --> Bak["H2: back up and install the new nginx file, nginx -t, reload"] Bak --> Gap["Test serves the old build: only / and assets work, deep links 404"] Gap --> Dep["H3: run the workflow on the feature branch with Deploy to Test"] Dep --> Ver["verify-deployment.sh in the job, then the matrix of section 5 from the PC"] Ver -->|"all as expected"| Mrg["Merge the pull request: master deploys the same build"] Ver -->|"mismatch"| Rb["Rollback: restore the backup file, reload, redeploy the last good commit"] Mrg --> Done["Test and master agree"] classDef client fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000; classDef service fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000; classDef gateway fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000; classDef database fill:#fbd38d,stroke:#92400e,stroke-width:1px,color:#000; class Cur,Gap database; class Bak,Dep,Rb client; class Ver,Mrg,Done service; ``` Text alternative: install the new nginx file by hand, immediately deploy the feature branch to test, verify with the matrix, and only then merge; on a mismatch restore the backed-up nginx file and redeploy the last good commit. Timing relative to the merge: - The new nginx file must be active before the first deploy of the new build. A merge deploys automatically, so the nginx update comes before the merge. With the old file and the new build, `/over-mij` would show the home page (old `try_files ... /index.html`); the new post-deploy script fails that job (BR-HST-18). - With the new file and the old build, deep links give 404 for as long as the old build stays. That gap is kept short by running H3 right after H2 and is acceptable on a noindex test site. - Order of actions that touch test: H2 (nginx), H3 (branch deploy), matrix, merge. Do not merge between H2 and H3. ## 4. CI changes (code generation) | Job | Change | |---|---| | `check` | Unchanged; `pnpm test` runs the new unit and property tests (P-HST-01 to 08, 10, 11) | | `lighthouse` | Installs nginx (`sudo apt-get install -y nginx`), runs `pnpm e2e` including `serverRules.e2e.ts` (P-HST-09), starts the preview with `--audit-route` for Lighthouse | | `deploy-test` | Artifact guard, then the existing empty-and-copy, then `verify-deployment.sh "$HEALTH_URL" dist --test` (still skipped when `HEALTH_CHECK_URL_TEST` is empty; keep it set) | | `deploy-production` | Guard, variant copy of `web.config`, three-pass upload, `verify-deployment.sh "$HEALTH_URL" dist` (compression only warns) | Repository variable added: `IIS_WEB_CONFIG_VARIANT` (default `full`; `no-httperrors` or `no-compression` per BR-HST-20). ## 5. Verification matrix, test (`https://test.andreaslop.nl`) Run from the PC after H3. `B=https://test.andreaslop.nl`. ```bash for p in / /over-mij /soorten-fotoshoots /soorten-fotoshoots/newborn /contact '/over-mij?pakket=gezin' \ /over-mij/ /soorten-fotoshoots/ /over-mij.html /index.html /index /Over-Mij /Over-Mij/ '/Over-Mij?x=1' \ /404 /404.html /onbekend /onbekend/ /assets /assets/ /assets/missing.js /robots.txt /sitemap.xml; do printf '%-30s ' "$p"; curl -s -o /dev/null -w '%{http_code} %{redirect_url}\n' "$B$p" done curl -s -D - -o /dev/null -H 'Accept-Encoding: gzip' "$B/assets/$(curl -s $B/ | grep -o 'index-[A-Za-z0-9_-]*\.js' | head -1)" | grep -iE '^(HTTP|content-encoding|vary|cache-control)' curl -s -D - -o /dev/null "$B/onbekend" | grep -iE '^(HTTP|content-security-policy|strict-transport|x-content-type|x-frame|referrer|x-robots)' ``` | Path | Expected | |---|---| | `/`, `/over-mij`, `/soorten-fotoshoots`, `/soorten-fotoshoots/newborn`, `/contact`, `/over-mij?pakket=gezin` | `200` | | `/over-mij/`, `/over-mij.html`, `/Over-Mij`, `/Over-Mij/` | `301` to `/over-mij` | | `/soorten-fotoshoots/` | `301` to `/soorten-fotoshoots` | | `/Over-Mij?x=1` | `301` to `/over-mij?x=1` | | `/index.html`, `/index` | `301` to `/` | | `/404`, `/404.html`, `/onbekend`, `/assets`, `/assets/missing.js` | `404` | | `/onbekend/`, `/assets/` | `301` to the path without slash, then `404` | | `/robots.txt` | `200`, `Disallow: /`; `/sitemap.xml` `200` | | JavaScript with `Accept-Encoding: gzip` | `Content-Encoding: gzip`, `Vary: Accept-Encoding`, `Cache-Control: public, max-age=31536000, immutable` | | The 404 response | all five security headers and `X-Robots-Tag: noindex, nofollow` | Also open `/Over-Mij?pakket=gezin` and `/soorten-fotoshoots/` in Chrome: the address bar ends on the canonical URL, the page title is the page's own, no console error. ## 6. Verification matrix, production rehearsal (H5, H6) Probe kit, per folder (`P=https://andreaslop.nl`, host via `hosts` entry; the kit README holds the exact commands): | Folder | Request | Expected | If not | |---|---|---|---| | `_probe-rewrite` | `/_probe-rewrite/a` (a.html next to directory `a/`) | `200` and the body of `a.html` | 500: rewrite locked or module missing; 301 to `a/`: rule order wrong | | `_probe-rewrite` | `/_probe-rewrite/a/`, `/_probe-rewrite/A`, `/_probe-rewrite/dir`, `/_probe-rewrite/dir/` | `301` to `a`, `301` to `a`, `404`, `301` then `404` | A loop (too many redirects) means rule 8 is missing or not honoured | | `_probe-errors` | `/_probe-errors/nope` | `404` with the custom page body | 500: `httpErrors` locked (F1); `404` with IIS's own page: `existingResponse` ignored | | `_probe-errors` | `/_probe-errors/gone.html` (blocked by CustomResponse, also the ExecuteURL target) | `404` with the custom page body | Empty body or loop: F2 | | `_probe-headers` | `/_probe-headers/x.txt`, a `301` | all probe headers on both; `Cache-Control` as set; `.woff2` MIME | 500: `customHeaders` or `staticContent` locked | | `_probe-compress` | each probe file, 5 requests in a row, `Accept-Encoding: gzip` | `Content-Encoding: gzip` for HTML, JS, CSS, SVG, JSON, XML | 500: `urlCompression` locked (F3); 200 without encoding: ask the host (Q4) | Full deploy rehearsal (`P=https://andreaslop.nl` via `hosts`): the matrix of section 5 with these differences: no `X-Robots-Tag`; `/robots.txt` and `/sitemap.xml` are the build's files; `/` also tested over `http://` (301 to https) and `www.` (one 301 to `https://andreaslop.nl/`, path kept); compression after repeated requests; `/404` and `/404.html` per decision O4. ## 7. Rollback summary | Situation | Action | |---|---| | New nginx file rejected (`nginx -t`) | Copy the `.bak-` file back, `nginx -t`, stop | | New nginx file accepted but the matrix fails | Restore backup, reload, redeploy the last good commit to test (H2/H3 rollback) | | Bad `web.config` live on production | Upload the previous `web.config` or a variant by FTP, or redeploy the previous release (rollback-plan.md); before DNS no visitor is affected | | Locked section found | Set `IIS_WEB_CONFIG_VARIANT` and redeploy | | Post-deploy script red on test after a merge | The old nginx file is probably active: re-run H2, then run the workflow on `master` with "Deploy to Test" | ## 8. Monitoring No new monitoring. `verify-deployment.sh` is the deploy-time check; the UptimeRobot deep link `/portfolio` (monitoring-setup) now relies on the page file rule, so it also detects a broken rewrite after go-live.