Files
AndreaSlopFotografie/aidlc-docs/features/prerendering/construction/hosting-and-targets/infrastructure-design/deployment-architecture.md
T
2026-11-01 02:17:28 +01:00

12 KiB

Deployment Architecture: Unit 3 "hosting-and-targets"

Rules and rationale: 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 and instructions; only differences are described here.

1. Topology

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)

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):

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

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.

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-<timestamp> 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.