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 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)
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):
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: owner places 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-mijwould show the home page (oldtry_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.
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 backup from /mnt/storage1/backups/andreaslop-test-nginx/ (see pi-install-instructions.md), 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.