# 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 `web1` nginx 1.30.6 (`/etc/nginx/conf.d/andreaslop-test.conf`, included from `nginx.conf:38`) | Test | All URL, 404, header and compression rules | Generated here, delivered as a `server-ops` draft, installed by the owner (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 | ## 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 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: owner installs the server-ops draft with backup, 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, copy of `web.config`, three-pass upload, `verify-deployment.sh "$HEALTH_URL" dist` (compression only warns). Stays dispatch-only from `release/*`; it can not run until a host exists | ## 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 (before go-live on IIS) The IIS rules are unverified until a host exists (infrastructure-design.md section 7). `deploy-production` can not run without a host and stays dispatch-only from `release/*`. When a host exists, try the generated `web.config` on a temporary URL (the host's preview URL, or the A-record IP with a `hosts` entry) before the DNS switch, by hand, with the matrix of section 5 and these differences: no `X-Robots-Tag`; `/robots.txt` and `/sitemap.xml` are the build's files; `/` also over `http://` (301 to https) and `www.` (one 301 to `https://andreaslop.nl/`, path kept); compression after repeated requests (IIS compresses static files only after a few hits). Points to watch, with the open point they belong to: | Request | Expected | Open point | |---|---|---| | `/soorten-fotoshoots`, `/soorten-fotoshoots/` | `200`; `301` to `/soorten-fotoshoots` | U2 | | `/assets`, `/assets/` | `404`; `301` to `/assets`, then `404`; no loop, no listing | U2 | | `/onbekend`, `/404.html`, `/404` | `404` with the 404 page body (not empty, not IIS's page) | U1 | | `/Over-Mij`, `/over-mij/` | `301` to `/over-mij` with the five security headers on the 301 | U6 | | JavaScript with `Accept-Encoding: gzip` | `Content-Encoding: gzip`, otherwise ask the host (Q4) | U3 | | Any request returns 500 | A section is locked or missing: remove it from `web.config` once the host names it | U4 | ## 7. Rollback summary | Situation | Action | |---|---| | New nginx file rejected (`nginx -t`) or accepted but the matrix fails | The owner restores the `.bak-` file, `nginx -t`, reload, and redeploys the last good commit to test (H2/H3 rollback) | | Bad `web.config` live on production | Upload the previous `web.config` by FTP, or redeploy the previous release (rollback-plan.md); before DNS no visitor is affected | | Post-deploy script red on test after a merge | The old nginx file is probably active: ask the owner to install the `server-ops` draft (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.