Finalises the third unit's infrastructure design

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-01 02:21:39 +01:00
co-authored by Claude Opus 5.5
parent 7ccffe3d71
commit 1a4a432625
4 changed files with 134 additions and 104 deletions
@@ -42,18 +42,17 @@ Text alternative: the developer pushes to Gitea, which builds one artifact; test
| 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) |
| 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 |
| `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"]
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"]
@@ -86,7 +85,7 @@ mirror --reverse --delete --verbose dist/ $FTP_DIR/;
```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"]
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"]
@@ -117,9 +116,8 @@ Timing relative to the merge:
| `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) |
| `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 |
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`)
@@ -150,30 +148,26 @@ curl -s -D - -o /dev/null "$B/onbekend" | grep -iE '^(HTTP|content-security-poli
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)
## 6. Verification matrix, production (before go-live on IIS)
Probe kit, per folder (`P=https://andreaslop.nl`, host via `hosts` entry; the kit README holds the exact commands):
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:
| 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.
| 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`) | 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" |
| New nginx file rejected (`nginx -t`) or accepted but the matrix fails | The owner restores the `.bak-<timestamp>` 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
@@ -14,10 +14,10 @@ Unit 3 skips Functional Design ([execution-plan.md](../../../inception/plans/exe
| 4 | `/404` and `/404.html` answer with status 404 on every server; Lighthouse audits the 404 page through an opt-in preview route, not through a 200 at `/404.html` | BR-HST-05, 22 |
| 5 | Directories next to page files never redirect or list (`try_files` without `$uri/`; IIS rules that pre-empt the directory redirect) | BR-HST-07 |
| 6 | nginx compresses itself (own `gzip` block, valid behind a proxy that talks HTTP/1.0). IIS compression can only be switched on per site, the rest belongs to the webhost | BR-HST-09 to 11 |
| 7 | IIS risk is limited by a probe kit (one `web.config` per section in sub folders), two committed fallback variants and a rehearsal before DNS | BR-HST-19, 20 |
| 8 | Upload order: assets, `web.config`, all HTML, cleanup. nginx on the Pi is updated by hand before the merge and proven with a branch deploy | BR-HST-14 to 18 |
| 7 | The IIS rules are generated and checked as text only. They are unverified until a host exists; a "Before go-live on IIS" list (section 7) records the questions and the unverified points | BR-HST-19 |
| 8 | Upload order: assets, `web.config`, all HTML, cleanup. nginx on the Pi is updated by hand before the merge and proven with a branch deploy; `deploy-production` stays dispatch-only (no host yet) | BR-HST-14 to 18 |
| 9 | `lighthouserc.cjs` gets a data-driven exception list, empty by default; no target changes without a recorded owner decision | BR-HST-21, 23 |
| 10 | The nginx rules are proven with a real nginx process in CI (apt, same 1.24 as the Pi); IIS rules are checked by a rule simulator | BR-HST-24 |
| 10 | The nginx rules are proven with a real nginx process in CI (apt, 1.24; the Pi runs 1.30.6, an accepted gap), with parity tests against the preview server. IIS rules are only tested as generated text | BR-HST-24 |
## 2. Findings that shape the design
@@ -35,18 +35,22 @@ Unit 3 skips Functional Design ([execution-plan.md](../../../inception/plans/exe
### 2.2 Compression cause (FR-PR-23)
Established: nothing on the path compresses, for the test site and for WordPress alike. The repo's `andreaslop-test.conf` has no `gzip` directives, so the test block depends on the Pi's global `nginx.conf`. The repo's proxy config has no `proxy_http_version`, so nginx talks HTTP/1.0 to the hosting Pi by default, and nginx only compresses requests of version 1.1 or higher (`gzip_http_version` defaults to 1.1).
Established from outside (2026-11-01): nothing on the path compresses, for the test site and for WordPress alike.
Not established (needs the Pi, see Human task H1): which of these is the cause.
Established on the hosting Pi `web1` (192.168.1.103, read-only checks by the Pi-Main session): **no `gzip` directive is active.** `/etc/nginx/nginx.conf:36` is `#gzip on;` and nginx's default is off. Requests over HTTP/1.1 and HTTP/1.0 to 127.0.0.1 both return HTML and JavaScript without `Content-Encoding` or `Vary`. That is candidate B, confirmed. The hosting Pi's stock file is not Ubuntu's (which ships `gzip on;`), so my earlier assumption was wrong.
| Candidate | Fits the evidence | Fix |
Not established: the proxy Pi (192.168.1.102, public 217.121.250.215) was not checked. The repo's proxy config has no `proxy_http_version`, so nginx talks HTTP/1.0 to the hosting Pi by default, and nginx only compresses requests of version 1.1 or higher (`gzip_http_version` defaults to 1.1). That would be a second obstacle once gzip is on.
| Candidate | Status | Fix |
|---|---|---|
| A. HTTP/1.0 from the proxy meets `gzip_http_version 1.1` on the hosting Pi | HTML is not compressed although Ubuntu's stock `nginx.conf` ships `gzip on;` (stock `gzip_types` covers `text/html` only, so JavaScript would stay plain anyway). This is the most likely single cause of the HTML result | `gzip_http_version 1.0` in the generated test block (self-sufficient); optionally `proxy_http_version 1.1` on the proxy |
| B. `gzip` is off, or has no JS/CSS/SVG types, in the hosting Pi's global config | Explains the JavaScript result in any case | Own `gzip` block in the generated test block (BR-HST-09) |
| C. The proxy strips or empties `Accept-Encoding` | Would hide everything; the repo's proxy config does not do this | Check with H1; no change if absent |
| D. The proxy re-writes or decompresses the response | Would need `gunzip on` or Lua; not in the repo | Check with H1 |
| B. `gzip` off in the hosting Pi's global config | Confirmed | Own `gzip` block in the generated test block (BR-HST-09) |
| A. HTTP/1.0 from the proxy meets `gzip_http_version 1.1` | Possible second obstacle, unchecked | `gzip_http_version 1.0` and `gzip_proxied any` in the same block cover it; optionally `proxy_http_version 1.1` on the proxy |
| C. The proxy strips or empties `Accept-Encoding` | Unchecked; the repo's proxy config does not do this | Owner checks the proxy part of H1 |
| D. The proxy re-writes or decompresses the response | Unchecked; would need `gunzip on` or Lua; not in the repo | Owner checks the proxy part of H1 |
The generated test block fixes A and B together without a global setting, so the repo change is safe whichever candidate H1 confirms. H1 documents the cause for the record and rules out C and D, which the repo cannot fix.
The generated test block fixes B and A without a global setting. C and D, if present, can not be fixed in the repo; only the proxy part of H1 can rule them out, and it is the owner's.
Version note: the `Server: nginx/1.24.0` header seen from outside is the proxy Pi's (nginx replaces the upstream `Server` header). The hosting Pi runs nginx 1.30.6.
### 2.3 Spike: letter case, trailing slash and the router (BR-404-07)
@@ -215,8 +219,8 @@ Notes:
- Rule 5 excludes a leading `/` or `\` in the captured part so that `//evil.example/` cannot become the target `//evil.example` (BR-HST-06). `ToLower` applies only to the alternation of known pages, so hashed asset names with upper-case letters are never touched.
- Rules 7 and 8 are the directory trap (BR-HST-07). URL Rewrite runs before the handler stage. Rule 7 rewrites `/soorten-fotoshoots` to the file although a directory of that name exists. Rule 8 catches directory-only names such as `/assets`; without it the handler would redirect `/assets` to `/assets/` and rule 5 would redirect back (loop). The condition of rule 7 does not use `IsDirectory negate` (the old SPA rule did).
- `/` is served by the default document `index.html` as today; a `^$` rewrite to `/index.html` is added only if the rehearsal shows the default document is not applied (V6 in section 12).
- Custom 404 page: `<httpErrors errorMode="Custom" existingResponse="Replace">` with `<error statusCode="404" subStatusCode="-1" path="/404.html" responseMode="ExecuteURL" />` after a `<remove statusCode="404" subStatusCode="-1" />`. `ExecuteURL` takes a site-relative URL, so `allowAbsolutePathsWhenDelegated` (which concerns physical paths in `File` mode) is not needed. Rule 6 together with `ExecuteURL` is the least certain part: if URL Rewrite also evaluates the executed child request `/404.html`, rule 6 would answer it with an empty 404. The probe kit tests exactly this (section 7); fallback F2.
- `/` is served by the default document `index.html` as today; a `^$` rewrite to `/index.html` is added if the first test on a real host shows the default document is not applied (open point U6).
- Custom 404 page: `<httpErrors errorMode="Custom" existingResponse="Replace">` with `<error statusCode="404" subStatusCode="-1" path="/404.html" responseMode="ExecuteURL" />` after a `<remove statusCode="404" subStatusCode="-1" />`. `ExecuteURL` takes a site-relative URL, so `allowAbsolutePathsWhenDelegated` (which concerns physical paths in `File` mode) is not needed. Rule 6 together with `ExecuteURL` is the least certain part: if URL Rewrite also evaluates the executed child request `/404.html`, rule 6 would answer it with an empty 404. Unverified until a host exists (open point U1).
- Headers (`customHeaders`) and `clientCache` stay as now: `DisableCache` site-wide, `UseMaxAge 365.00:00:00` for `/assets` (BR-HST-12).
- Compression: section 5.
@@ -225,7 +229,7 @@ Notes:
| Rule | Statement |
|---|---|
| BR-HST-09 | nginx: the generated test block compresses HTML, JavaScript, CSS, SVG, JSON and XML (and plain text) with the `gzip` block of section 4.2, valid behind a proxy that uses HTTP/1.0, with `Vary: Accept-Encoding`. Fonts, images and other binary files are not listed. Nothing relies on the Pi's global settings |
| BR-HST-10 | IIS: `web.config` sets `<urlCompression doStaticCompression="true" doDynamicCompression="false" />` and pins MIME types so the server's default compressible set matches (`.js` as `text/javascript`, `.css`, `.svg` as `image/svg+xml`, `.json`, `.xml` as `text/xml`, `.html`). `httpCompression` (which types, the compression level, the cache directory) cannot be set in `web.config`; it belongs to `applicationHost.config`, so the webhost owns it. The result is only proven by `curl` in the rehearsal (V6); the owner asks the webhost (section 8, Q6). A site without compression still works |
| BR-HST-10 | IIS: `web.config` sets `<urlCompression doStaticCompression="true" doDynamicCompression="false" />` and pins MIME types so the server's default compressible set matches (`.js` as `text/javascript`, `.css`, `.svg` as `image/svg+xml`, `.json`, `.xml` as `text/xml`, `.html`). `httpCompression` (which types, the compression level, the cache directory) cannot be set in `web.config`; it belongs to `applicationHost.config`, so the webhost owns it. Unverified until a host exists (open point U3); the owner asks the webhost (Q4). A site without compression still works |
| BR-HST-11 | One list: `{extension, MIME types}` for the compressible types lives in one module. The preview server's `COMPRESSIBLE` extension set, the nginx `gzip_types`, and the IIS MIME pins are all derived from it, and a test checks that they agree |
IIS behaviour to know: static compression starts only after a file has been requested a few times in a short time (`frequentHitThreshold`), so the first requests can be plain; and it is skipped for requests that arrive through a proxy (`noCompressionForProxies`). Rehearsal must therefore request each file several times.
@@ -239,9 +243,9 @@ The preview server keeps its gzip (BR-SRV-08). Lighthouse therefore measures com
| BR-HST-12 | `/assets/*` (hashed names): `public, max-age=31536000, immutable`. Everything else, including HTML, `robots.txt`, `sitemap.xml`, `favicon.png` and unhashed images: `no-cache`. 301 responses carry no extra cache header (browsers may keep a 301; acceptable because the redirect set is fixed by the page list) |
| BR-HST-13 | The five security headers of `securityHeaders('production')` are present on every response: 200, 301, 404, the 404 page, 405 and error responses. Test adds `X-Robots-Tag`. nginx uses `add_header ... always` in every location and at server level; IIS uses `customHeaders`; the preview server merges them in `send()` |
Your brief lists `robots.txt`, `sitemap.xml` and the favicon as long-cached. They are not hashed, so a long lifetime would keep a stale `robots.txt` after go-live. They revalidate instead (a 304 is cheap with `ETag`). Lighthouse's cache audit is informational and does not weigh in the score. See decision O3.
Only `/assets` is long-cached (owner decision O3). `robots.txt`, `sitemap.xml`, the favicon and other unhashed files revalidate: a long lifetime would keep a stale `robots.txt` after go-live, and a 304 is cheap with `ETag`. Lighthouse's cache audit is informational and does not weigh in the score.
## 7. IIS unknowns and risk limiting
## 7. IIS: unverified rules and "Before go-live on IIS"
### 7.1 What may be locked or missing at the webhost
@@ -259,24 +263,31 @@ The package is shared hosting ("ASP.NET Core 10", Windows/IIS, URL Rewrite per t
What happens when a locked setting is used: IIS cannot read the configuration and answers every request under that folder with HTTP 500 (500.19), static files included, until a valid `web.config` is uploaded again. A remote visitor sees a generic 500 page, not the detail (which is also what we want for SECURITY-09).
### 7.2 Risk limiting
### 7.2 Status and scope
The webhost package has **not been purchased** (owner, 2026-11-01). The `web.config` rules of section 4.3 are generated from the page list and checked as text only (as `serverConfig.test.ts` does today: the file contains the rules, in the designed order, with no SPA fallback). **They are unverified until they run on a real IIS host.** Test runs nginx, so nothing in CI exercises them.
| Rule | Statement |
|---|---|
| BR-HST-19 | Probe kit. A generated, committed set of tiny sites under `web/deploy/iis-probe/` (not part of `dist/`, never uploaded by the pipeline), one folder per feature group, each with its own `web.config` and a few files: `_probe-rewrite` (page mapping, slash, case, directory next to file), `_probe-errors` (`httpErrors` ExecuteURL plus a CustomResponse rule on the executed page), `_probe-headers` (customHeaders, mimeMap, clientCache), `_probe-compress` (`urlCompression` and 100 KB files of every compressible type). A locked section breaks only its folder, so the owner learns which section fails without risking the site. The first real deploy (`mirror --delete`) removes the probe folders. The probe folders use the same rule text as the real `web.config` (generated from the same functions), so a pass means the real file will pass |
| BR-HST-20 | Fallback variants. The generator also writes `deploy/iis/variants/web.no-httperrors.config` (F1) and `web.no-compression.config` (F3), tested like the main file. The production job copies `deploy/iis/${IIS_WEB_CONFIG_VARIANT:-full}` as `web.config`, so switching variant is a repository variable change followed by a deploy, not a code change |
| BR-HST-19 | Scope for IIS in this unit: the generated `web.config`, the upload order and guard in `deploy-production` (BR-HST-14, 15), and the list below. `deploy-production` can not run without a host and stays dispatch-only from `release/*`. No probe kit, no fallback variants, no `IIS_WEB_CONFIG_VARIANT` and no rule simulator are built (withdrawn by the owner; BR-HST-20 is withdrawn with them) |
Fallbacks, in the order they would be used:
**Before go-live on IIS** (a short list, no tooling):
| Id | When | Effect |
1. Ask the host Q1 to Q6 (section 8) before buying or configuring anything.
2. Open points that stay open until a host exists:
| Id | Unverified point | Consequence if it fails |
|---|---|---|
| F1 `no-httperrors` | `httpErrors` locked | No custom 404 page. IIS answers unknown URLs with its generic 404 (status 404, no internal detail) and rules 6 and 8 answer with an empty 404 CustomResponse. FR-PR-14 is not met on production (owner decision O5); the status code stays correct |
| F2 drop rule 6 | ExecuteURL re-triggers rule 6 (empty 404 body) | `/404.html` serves the 404 page with 200 (it is `noindex` and unlinked). `/404` is excluded from rule 7 by a pattern instead. Documented parity exception (owner decision O4) |
| F3 `no-compression` | `urlCompression` locked | Site works uncompressed; ask the webhost to enable compression server-side |
| U1 | URL Rewrite `CustomResponse` 404 (rules 6 and 8) together with `httpErrors` `ExecuteURL` to `/404.html`: whether rule 6 re-fires on the executed child request (empty 404 body) and whether `existingResponse="Replace"` is honoured | Unknown URLs or `/404.html` return an empty or default 404. Options then: drop rule 6 (`/404.html` serves the page with 200, `noindex`), or accept the host's generic 404 page. The owner decides when a host exists (this covers the former O4 and O5) |
| U2 | Directory handling: rule 7 before the handler's own directory redirect, rule 8 for directory-only names (`/assets`), `/soorten-fotoshoots` next to its directory | A redirect loop, or a directory redirect instead of the page |
| U3 | `httpCompression` is server level and can not be set in `web.config`; only `urlCompression` can | No compression on production unless the host enables it for HTML, JS, CSS, SVG, JSON, XML. FR-PR-23 then depends on the host |
| U4 | 500.19 risk: any locked or missing section (`rewrite`, `httpErrors`, `customHeaders`, `staticContent`, `urlCompression`) makes IIS answer every request under that folder with 500, static files included | Whole site down until a valid `web.config` is uploaded. Remove the offending section once the host names it |
| U5 | Site root: FTP root versus the `wwwroot` folder (Q1); `FTP_REMOTE_DIR` depends on it | Rules silently absent |
| U6 | Default document for `/`, security headers on 301 and 404 responses, MIME pins | Check on the first requests |
Staged rollout (also in [deployment-architecture.md](deployment-architecture.md)): A probe kit on the unlaunched site root (no DNS dependency), B full production deploy from a `release/*` branch and the curl matrix against the new host with a `hosts` entry (the existing dress rehearsal, now with the new matrix), C DNS switch, D every later change of `web.config` may use only sections proven in A and B.
Rollback if a bad `web.config` is live: upload the previous `web.config` (or a variant) by FTP, or redeploy the previous release (rollback-plan.md). Before the DNS switch no visitor is affected.
3. Try the generated `web.config` on a temporary URL first (the host's preview URL, or the A-record IP with a `hosts` entry) before the DNS switch, and run the matrix of deployment-architecture.md section 6 by hand. Nothing is built for this.
4. After the first run on a real host, record the result in a verification log and close or re-open U1 to U6.
5. Rollback if a bad `web.config` is live: upload the previous `web.config` by FTP, or redeploy the previous release (rollback-plan.md). Before the DNS switch no visitor is affected.
## 8. What the owner must ask or try at the webhost
@@ -287,16 +298,16 @@ Ask (support ticket, one message):
3. Q3. Are `system.webServer/httpErrors`, `httpProtocol/customHeaders` and `staticContent` delegated (Read/Write) to `web.config` at site level? Is a host-wide custom error page configured that would override ours?
4. Q4. Is the static compression module installed, is `urlCompression` delegated, and which MIME types are in the server's `httpCompression/staticTypes` (we need HTML, JavaScript, CSS, SVG, JSON, XML)? If not, can they add them?
5. Q5. Is `IIS 10` (or later) used, and may directory browsing stay off?
6. Q6. Does the package exist and is a temporary URL or the A-record IP available for a rehearsal before DNS changes?
6. Q6. Does the package exist or can it be tried before buying, and is a temporary URL or the A-record IP available before DNS changes?
Try (no webhost help needed): H5 below (probe kit).
Try: the generated `web.config` on a temporary URL, as in section 7.2, step 3.
## 9. Deployment rules
| Rule | Statement |
|---|---|
| BR-HST-14 | `deploy-production` uploads in three passes: (1) every file except `*.html` and `web.config`; (2) `web.config` and then all HTML files, including `404.html` and nested ones; (3) `mirror --delete`. The `--exclude-glob index.html` option disappears. A visitor can reach HTML only after every asset it refers to exists (FR-PR-18). The exact lftp exclusion syntax (glob against the relative path, or a regex) is proven locally with a dry run against a `file:` target (section 12, V10) |
| BR-HST-15 | `web.config` is copied from `deploy/iis/${IIS_WEB_CONFIG_VARIANT:-full}/web.config` to `dist/web.config`, next to `index.html` (the artifact root is `dist/`; `server/` is not in it). Before uploading, the job fails if `dist/index.html`, `dist/404.html` or `dist/over-mij.html` is missing, if `dist/server` exists, or if any `*.map` file is present (FR-PR-17, NFR-PR-SEC-03). Q1 decides whether `FTP_REMOTE_DIR` is `wwwroot` or the root |
| BR-HST-15 | `web.config` is copied from `deploy/iis/web.config` to `dist/web.config`, next to `index.html` (the artifact root is `dist/`; `server/` is not in it). Before uploading, the job fails if `dist/index.html`, `dist/404.html` or `dist/over-mij.html` is missing, if `dist/server` exists, or if any `*.map` file is present (FR-PR-17, NFR-PR-SEC-03). Q1 decides whether `FTP_REMOTE_DIR` is `wwwroot` or the root |
| BR-HST-16 | `deploy-test` keeps emptying the folder and copying `dist/*`. This is acceptable for a noindex test site: the gap is a few seconds of nginx's plain 404, no old build is kept, and the WordPress guard stays. The new `dist` contains `404.html` and nested folders; `scp -r` handles them |
| BR-HST-17 | The nginx update on the Pi is a human task, done before the merge and proven by a branch deploy (H2, H3, deployment-architecture.md). A merge to `master` deploys automatically; with the old nginx config the new build would serve the home page for `/over-mij` (the old `try_files ... /index.html`). The post-deploy check (BR-HST-18) turns that case into a red job |
| BR-HST-18 | One shared post-deploy script (`web/deploy/verify-deployment.sh <base-url> <dist-dir> [--test]`) used by both jobs. It fails the job unless: `/`, `/over-mij` and `/soorten-fotoshoots/newborn` return bytes identical to the matching files in `dist` (without `Accept-Encoding`, so an old nginx that serves the home page for `/over-mij` is caught); an unknown URL returns 404 with the bytes of `404.html`; `/over-mij/` returns 301 to `/over-mij` and `/Over-Mij` to `/over-mij`; all five security headers are on the 200, the 301 and the 404; `--test` adds `X-Robots-Tag`. A gzip request for the JavaScript bundle must return `Content-Encoding: gzip` on test; on production it only warns (webhost) |
@@ -307,7 +318,7 @@ Try (no webhost help needed): H5 below (probe kit).
|---|---|
| BR-HST-21 | Target state of `lighthouserc.cjs`: mobile performance 0.9 for every page; accessibility, best practices and SEO stay at 1 (S-01); desktop stays 0.9 (P-02, `lighthouserc.desktop.cjs` unchanged). The constants `homeMobilePerformance`, `photoPageMobilePerformance` and `photoPagePaths` are replaced by one exception table that is empty unless an owner decision names a page |
| BR-HST-22 | The 404 page is audited through an opt-in route. The preview server gets a flag (`--audit-route`) that only the Lighthouse start command passes; with it, `/__audit/404` serves `404.html` with status 200. Without the flag (every other use: `pnpm preview`, browser tests, parity tests) `/404.html` and `/404` are real 404s (BR-HST-05). `lighthouserc.cjs` uses `notFoundPath = '/__audit/404'` and the guard test in `app.test.tsx` follows. This replaces the unit 1 fallback (200 at `/404.html` on the preview only). Reason: Lighthouse refuses a main document with an error status (observed in unit 1), and the `ignoreStatusCode` setting (exists in the installed Lighthouse 12.6.1) would still log Chrome's console error for a 404 document, which probably fails the best-practices score of 1 on the 404 page; that was not measured here (Lighthouse was out of scope). V9 measures it; if it passes, `ignoreStatusCode: true` is the simpler alternative (decision O2) |
| BR-HST-23 | Exceptions are data. Sketch: `const mobileExceptions = { }` with entries `{ '/some-page': { minScore: 0.85, decision: 'owner, 2026-11-xx, measurement-final.md row N' } }`. A unit test enforces: every exception has a non-empty `decision`, `minScore < 0.9`, names a page that exists, and no page matches two matrix entries. The matrix builder creates one entry for all pages without exception and one per page with an exception. `numberOfRuns` for the blocking mobile run: see O6 |
| BR-HST-23 | Exceptions are data. Sketch: `const mobileExceptions = { }` with entries `{ '/some-page': { minScore: 0.85, decision: 'owner, 2026-11-xx, measurement-final.md row N' } }`. A unit test enforces: every exception has a non-empty `decision`, `minScore < 0.9`, names a page that exists, and no page matches two matrix entries. The matrix builder creates one entry for all pages without exception and one per page with an exception. `numberOfRuns` for the blocking mobile run: see O6 `numberOfRuns` stays 1 (owner decision). Known risk: pages exactly at 0.90 (zwangerschap, portret) can fail `pnpm check` at random. Final measurements for the owner decisions use three runs, taken separately (section 10). |
How the final measurement feeds the decision:
@@ -328,10 +339,10 @@ Generators: known pages x variants (case permutation, `.html`, 0 to 3 trailing s
| P-HST-04 | A redirect target starts with `/`, not with `//` or `/\`, has no control characters, and (for known pages) is one of the constants | same | Invariant (SECURITY-11) |
| P-HST-05 | The query string of the request is in the `Location` byte for byte | same | Invariant |
| P-HST-06 | Unknown, non-redirected paths give 404 with `404.html`; `/404` and `/404.html` give 404 only; `/` never redirects | same | Invariant |
| P-HST-07 | Generation: nginx map entries, IIS rule alternation and the page list are the same set; every nginx location (and the server level) contains all five headers; no `try_files` contains `$uri/`; no `index`, no `autoindex on`; no `return` or `rewrite` target built from `$uri` except `rewrite ... permanent`; `gzip_types` covers the required type list; IIS output is well-formed XML with the rule order of section 4.3 and no SPA fallback | `serverConfig.ts` | Invariant over the generated text |
| P-HST-08 | Generated files in `deploy/` equal the generator output, including the variants | `serverConfig.ts` | Existing round trip |
| P-HST-07 | Generation: nginx map entries, IIS rule alternation and the page list are the same set; every nginx location (and the server level) contains all five headers; no `try_files` contains `$uri/`; no `index`, no `autoindex on`; no `return` or `rewrite` target built from `$uri` except `rewrite ... permanent`; `gzip_types` covers the required type list; IIS output contains the rule order of section 4.3 and no SPA fallback (text check only) | `serverConfig.ts` | Invariant over the generated text |
| P-HST-08 | Generated files in `deploy/` equal the generator output | `serverConfig.ts` | Existing round trip |
| P-HST-09 | Parity oracle: for generated paths, a real nginx loaded with the generated block and the preview server agree on status, `Location`, and which file is served (body hash against `dist/client`); both carry the security headers; gzip request for compressible types gives `Content-Encoding: gzip` on nginx and the preview | nginx vs preview | Oracle / differential |
| P-HST-10 | IIS simulator: the redirect rules (3, 4, 5) and the 404 rules (6, 8), parsed from the generated `web.config` and evaluated with JavaScript regexes (`{R:n}`, `{ToLower:}`, `IsFile` from a file list), agree with `resolveRequest` on the same generated paths. Limits: no real URL Rewrite, no handler stage, no ExecuteURL | `serverConfig.ts` | Oracle / differential |
| P-HST-10 | Withdrawn (IIS rule simulator out of scope). The generated `web.config` text is tested as `serverConfig.test.ts` does now: it contains the rules of section 4.3 in order, the page alternation equals the page list, there is no SPA fallback, and the headers are present | `serverConfig.ts` | Example-based |
| P-HST-11 | Lighthouse config: no exception without `decision`, no exception at 0.9 or above, every URL matches exactly one matrix entry, `notFoundPath` equals the preview audit route | `lighthouserc.cjs` | Invariant |
Example-based tests keep the rows of section 3.1 as a table test, including `/soorten-fotoshoots` next to a directory.
@@ -340,23 +351,23 @@ Example-based tests keep the rows of section 3.1 as a table test, including `/so
| Option | Pros | Cons |
|---|---|---|
| 1. Real nginx from apt in the CI job, run unprivileged with a temporary prefix and `-c` (`sudo apt-get install -y nginx`, already the pattern for `sshpass` and `lftp`) | Same nginx 1.24 as the Pi (`Server: nginx/1.24.0`) on the Ubuntu 24.04 runner image; no nested containers (container actions do not work on Podman); seconds to run | Needs `sudo` on the runner (already used); on the PC runner image it depends on the same apt access |
| 2. `podman run nginx:1.24` in CI | Isolated | Podman inside the Podman runner job is not available; image pull each run |
| 3. Local only (owner's Podman) | No CI change | Podman machine is stopped by default; not enforced |
| 4. `nginx -t` only | Trivial | Proves syntax, not behaviour |
**BR-HST-24**: the nginx rules are proven by a real nginx process, not by reading. Recommendation: option 1, plus a local run through option 3 when `nginx` is not on the path (skipped with a visible message only when `CI` is not set; in CI a missing nginx fails the test). The test lives in `e2e/` (`serverRules.e2e.ts`), starts nginx on a free port with a `nginxTestConf({ listen, root })` generated from the same function (parameters default to the production values, so the committed file is unchanged), serves a copy of `dist/client`, and also runs a real HTTP/1.0 request to prove `gzip_http_version`. IIS can only be read: P-HST-10 plus the rehearsal.
| 1. Real nginx from the distribution (apt) in the CI job, run unprivileged with a temporary prefix and `-c` (`sudo apt-get install -y nginx`, already the pattern for `sshpass` and `lftp`) | No nested containers (container actions do not work on Podman); seconds to run; no new repository to trust | Version gap: the Ubuntu 24.04 runner image gives nginx 1.24, the hosting Pi runs 1.30.6. Needs `sudo` on the runner (already used) |
| 2. Official nginx.org package at 1.30.x in CI | Matches the Pi | Adds a third-party apt repository and signing key to the runner job; more setup for a small gain |
| 3. `podman run nginx:1.30` in CI | Isolated, matches the Pi | Podman inside the Podman runner job is not available |
| 4. Local only (owner's Podman) | No CI change | Podman machine is stopped by default; not enforced |
| 5. `nginx -t` only | Trivial | Proves syntax, not behaviour |
**BR-HST-24**: the nginx rules are proven by a real nginx process, not by reading. Recommendation (owner decision O8): option 1, and accept the version gap. Reason: every directive used is old and stable (`map`, `if` with `return`, `rewrite ... permanent`, `try_files`, `error_page`, `internal`, `absolute_redirect` since 1.11.8, `gzip*` including `gzip_http_version`), and none changes meaning between 1.24 and 1.30. In code generation each directive is checked against the nginx 1.30 documentation (V1), the test prints `nginx -v` so a mismatch is visible, and the real check on 1.30.6 is `nginx -t` plus the curl matrix during the Pi rollout (H2, H3). Option 2 stays available if a version-dependent difference ever shows up. A local run uses option 4 when `nginx` is not on the path (skipped with a visible message only when `CI` is not set; in CI a missing nginx fails the test). The test lives in `e2e/` (`serverRules.e2e.ts`), starts nginx on a free port with a `nginxTestConf({ listen, root })` generated from the same function (parameters default to the production values, so the committed file is unchanged), serves a copy of `dist/client`, and also runs a real HTTP/1.0 request to prove `gzip_http_version`. IIS is unverified until a host exists (section 7).
## 12. To verify in code generation
| Id | Check |
|---|---|
| V1 | `generated nginx` loads in real nginx 1.24 (`nginx -t`) as an `http`-level include without any other directive from the Pi; `map` before `server` works in `conf.d` |
| V1 | The generated nginx file loads in a real nginx (`nginx -t`) as an `http`-level include without any other directive from the Pi; `map` before `server` works in `conf.d`. Every directive is checked against the nginx 1.30 documentation (the Pi runs 1.30.6; CI has 1.24) |
| V2 | Server-level `if ... return 301` and `rewrite ... permanent` responses carry all five headers and `Cache-Control` with real nginx; `absolute_redirect off` gives a relative `Location`; `/` works without an `index` directive |
| V3 | `/soorten-fotoshoots` (file) and `/soorten-fotoshoots/` (directory) behave as in section 3.1 on nginx and preview; `/assets` and `/assets/` as well |
| V4 | `/404` and `/404.html` give 404 with the page and the five headers on nginx; `error_page` keeps the status; HEAD works |
| V5 | A HTTP/1.0 request with `Accept-Encoding: gzip` to the generated block gets `Content-Encoding: gzip` for `.html`, `.js`, `.css`, `.svg`, `.json`, `.xml` (all sizes above 256 bytes) and not for `.woff2`/images |
| V6 | IIS (rehearsal only): the 404 rule plus ExecuteURL, `/Over-Mij`, `/over-mij/`, `/assets`, `/soorten-fotoshoots`, headers on 301 and 404, compression after repeated requests, default document for `/`; recorded in `verification-log.md` |
| V6 | Withdrawn for this unit (IIS needs a host). The checks move to the "Before go-live" list, U1 to U6 |
| V7 | `previewServer.ts`: the new `resolveRequest` contract (redirect result, query handling, `--audit-route`); unit 1 tests for BR-SRV-07 are updated (the "interim" rules become final); `pageFiles.ts` stays the single path to file mapping |
| V8 | The 301 is followed by Chrome with the query string intact for `?pakket=` and `?shoot=` links, and the hydrated page has 1 title (extend the existing "URL die de server niet kent en de router wel" e2e) |
| V9 | One Lighthouse run of the 404 page on the preview audit route, and (as comparison) `/404.html` with `ignoreStatusCode`; record best-practices for both, then keep the simpler passing option (O2) |
@@ -364,75 +375,74 @@ Example-based tests keep the rows of section 3.1 as a table test, including `/so
| V11 | `verify-deployment.sh` fails against a copy of the old nginx config (home page for `/over-mij`) and passes against the new one |
| V12 | CI: the `lighthouse` job (or a new `server-rules` job) installs nginx, `pnpm e2e` includes `serverRules.e2e.ts`, and the job fails if nginx is missing |
| V13 | `lighthouserc.cjs`: the exception table is empty on delivery unless an owner decision exists; P-HST-11 passes; `pnpm lighthouse` still starts the preview with `--audit-route` and `Local` appears for `startServerReadyPattern` |
| V14 | The new nginx file works for a first-time install and for an update of an existing file (comment text in the header explains which) |
| V14 | The generated header comment fits the Pi: install path `/etc/nginx/conf.d/andreaslop-test.conf` (included from `nginx.conf:38`), no `sites-enabled`, no global `nginx.conf` change; the file works for a first install and for an update of an existing file |
## 13. Human tasks
Environment: PC (repo checkout on the feature branch), hosting Pi (`192.168.1.103`, nginx for test and WordPress), proxy Pi (public `217.121.250.215`), webhost control panel. Replace `PI_USER`, `PI_HOST` with the values of `PI_MAIN_*`.
Environment: PC (repo checkout on the feature branch), hosting Pi `web1` (192.168.1.103, nginx 1.30.6, test and WordPress), proxy Pi (192.168.1.102, public `217.121.250.215`, nginx 1.24.0), webhost control panel.
**H1. Diagnose compression on the Pi (read-only, any time, no repo change needed).**
**H1. Diagnose compression (read-only; runs through the Pi-Main session, no sudo).**
On the hosting Pi:
Hosting Pi: **done** (2026-11-01, Pi-Main session). `/etc/nginx/nginx.conf:36` is `#gzip on;`; HTTP/1.1 and HTTP/1.0 requests to 127.0.0.1 return HTML and JavaScript with no `Content-Encoding` or `Vary` (candidate B, section 2.2). The commands used, for the record (no sudo needed to read the files that the session can read; `nginx -T` is not required):
```bash
sudo nginx -T 2>/dev/null | grep -nE '^\s*(gzip|gzip_[a-z_]+)\s'
nginx -v
grep -rnE '^\s*#?\s*gzip' /etc/nginx/nginx.conf /etc/nginx/conf.d/
curl -s -o /dev/null -D - -H 'Host: test.andreaslop.nl' -H 'Accept-Encoding: gzip' http://127.0.0.1/ | grep -iE '^(HTTP|content-encoding|vary)'
curl -s -o /dev/null -D - --http1.0 -H 'Host: test.andreaslop.nl' -H 'Accept-Encoding: gzip' http://127.0.0.1/ | grep -iE '^(HTTP|content-encoding|vary)'
```
On the proxy Pi:
Proxy Pi (192.168.1.102): **open, for the owner** (the Pi-Main session has no access). Optional, read-only; it only rules out candidates C and D, since the generated block already covers A:
```bash
sudo nginx -T 2>/dev/null | grep -nE 'proxy_http_version|Accept-Encoding|gunzip|gzip|proxy_intercept_errors|error_page|proxy_pass'
curl -s -o /dev/null -D - -H 'Host: test.andreaslop.nl' -H 'Accept-Encoding: gzip' http://192.168.1.103/ | grep -iE '^(HTTP|content-encoding|vary)'
```
Read: `Content-Encoding: gzip` on the 1.1 request but not on the 1.0 request means candidate A (proxy HTTP/1.0). No `gzip` lines or no gzip on either means B. `Accept-Encoding` or `gunzip` in the proxy output means C or D. Send the output back; the design does not depend on the answer, but the cause is then recorded.
Read: `Accept-Encoding` or `gunzip` in the output means C or D. A gzip answer on the second command (once H2 is installed) means the hosting Pi side works; the public check is the matrix of deployment-architecture.md section 5.
**H2. Update nginx on the hosting Pi (before the merge).**
**H2. Update nginx on the hosting Pi (before the merge; only after the owner's separate approval).**
The Pi-Main session never uses sudo, and a change in `/etc/nginx` goes through a draft in the `server-ops` repository. Steps and owners:
1. Code generation produces `web/deploy/nginx/andreaslop-test.conf` (`pnpm server-config`). The vhost lives at `/etc/nginx/conf.d/andreaslop-test.conf`, which `/etc/nginx/nginx.conf:38` includes inside `http {}` (no `sites-enabled`). The header comment of the generated file names this install path and states that the file needs no change to the global `nginx.conf`.
2. The Pi-Main session delivers the generated file as a draft in `server-ops`. It does not install it.
3. The owner reviews the draft and installs it on `web1`, with backup, test and reload:
```bash
# on the PC, from the repo checkout on the feature branch
scp web/deploy/nginx/andreaslop-test.conf PI_USER@PI_HOST:/tmp/andreaslop-test.conf
# on the hosting Pi
sudo cp /etc/nginx/conf.d/andreaslop-test.conf /etc/nginx/conf.d/andreaslop-test.conf.bak-$(date +%Y%m%d%H%M)
sudo install -m 644 -o root -g root /tmp/andreaslop-test.conf /etc/nginx/conf.d/andreaslop-test.conf
sudo install -m 644 -o root -g root <draft file> /etc/nginx/conf.d/andreaslop-test.conf
sudo nginx -t
```
If `nginx -t` fails: `sudo cp` the `.bak-...` file back over `andreaslop-test.conf`, run `sudo nginx -t`, and stop. If it passes: `sudo systemctl reload nginx`. The backup ends in `.bak-<timestamp>`, so the `conf.d/*.conf` include ignores it. Do not touch the WordPress block.
Timing is unchanged: H2 happens before the merge, immediately followed by H3.
**H3. Prove it with a branch deploy, then merge.** In Gitea: Actions, Continuous Integration, Run workflow, branch `feature/prerendering`, tick "Deploy to Test". When the job is green (it now runs `verify-deployment.sh`), run the matrix of deployment-architecture.md section 5 from the PC. Only then merge the pull request. The merge deploys the same build again.
**H4. Optional, proxy Pi.** Only if H1 shows candidate A and you want it fixed at the source: edit `/etc/nginx/conf.d/test.andreaslop.nl.conf` in place (certbot owns it), add inside `location /`: `proxy_http_version 1.1;` and `proxy_set_header Connection "";`, then `sudo nginx -t && sudo systemctl reload nginx`. Not required for compression.
**H4. Optional, proxy Pi (the owner's).** Only if the proxy part of H1 or the public matrix shows the proxy side still blocks compression: edit `/etc/nginx/conf.d/test.andreaslop.nl.conf` in place (certbot owns it), add inside `location /`: `proxy_http_version 1.1;` and `proxy_set_header Connection "";`, then `sudo nginx -t && sudo systemctl reload nginx`. Not expected to be needed.
**Rollback of H2/H3.** On the hosting Pi: `sudo cp /etc/nginx/conf.d/andreaslop-test.conf.bak-<timestamp> /etc/nginx/conf.d/andreaslop-test.conf && sudo nginx -t && sudo systemctl reload nginx`. Then redeploy the previous build: create a branch at the last good commit (`git switch -c rollback/test c4c2f83 && git push -u origin rollback/test`) and run the workflow on it with "Deploy to Test". Test is noindex and has no visitors, so a few minutes of 404 is acceptable.
**H5. IIS probe kit (owner, once the hosting package exists; no DNS change).**
1. Run `pnpm server-config` on the feature branch (code generation adds the probe kit); upload `web/deploy/iis-probe/*` with FileZilla ("FTP over explicit TLS") into the site root (the folder Q1 identifies).
2. Add a `hosts` entry (`<A-record IP> andreaslop.nl`) or use the hoster's temporary URL.
3. Run the commands in `web/deploy/iis-probe/README` (one `curl` per folder; code generation writes it from the matrix in deployment-architecture.md section 6) and send the result. A 500 for a folder means that folder's section is locked: tell me which folder; I switch the variant (BR-HST-20).
4. Send the answers to Q1 to Q6 of section 8.
5. Remove the `hosts` entry afterwards. The probe folders disappear with the first real deploy.
**H6. Production rehearsal (before DNS).** As in deployment-instructions.md "Go-live", step 1, with the matrix of deployment-architecture.md section 6 instead of the old four checks. Set `IIS_WEB_CONFIG_VARIANT` only if H5 requires a fallback.
**Rollback of H2/H3 (the owner).** On the hosting Pi: `sudo cp /etc/nginx/conf.d/andreaslop-test.conf.bak-<timestamp> /etc/nginx/conf.d/andreaslop-test.conf && sudo nginx -t && sudo systemctl reload nginx`. Then redeploy the previous build: create a branch at the last good commit (`git switch -c rollback/test c4c2f83 && git push -u origin rollback/test`) and run the workflow on it with "Deploy to Test". Test is noindex and has no visitors, so a few minutes of 404 is acceptable.
**H5 and H6 (IIS probe kit and rehearsal) are withdrawn**; the "Before go-live on IIS" list in section 7.2 replaces them. There is no host yet.
## 14. Decisions for the owner
| Id | Question | Recommendation | Alternatives |
|---|---|---|---|
| O1 | How do server and router agree on letter case and trailing slash? | Server-side 301 to the canonical form on all three servers; router unchanged | Router `caseSensitive: true` (fixes nginx, breaks IIS); both (extra code, no gain); serve non-canonical URLs as 404 (impossible on case-insensitive IIS) |
| O2 | How does Lighthouse audit the 404 page while `/404.html` is a real 404? | Opt-in preview route `/__audit/404` (certain to work, default preview stays faithful) | `ignoreStatusCode: true` (no preview code; likely fails best practices because of Chrome's console error, measured in V9); keep unit 1's 200 at `/404.html` (preview unfaithful) |
| O3 | Cache lifetime of unhashed files (`robots.txt`, `sitemap.xml`, favicon, logos, OG images) | `no-cache` (revalidate); only `/assets` long-cached | Long cache for favicon, logos and OG images only (one day), at the cost of per-file IIS `location` blocks |
| O4 | `/404.html` on IIS if URL Rewrite plus ExecuteURL misbehaves | Try the 404 rule; if the probe shows an empty body, drop the rule (F2) and accept 200 with `noindex` | Block it another way (none known); accept an empty 404 |
| O5 | If the webhost locks `httpErrors` | Ask the host to unlock it first; otherwise F1 (generic IIS 404 page, correct status) | Soft 404 (rewrite to `404.html` with 200): wrong status; change host |
| O6 | `numberOfRuns` for the blocking mobile Lighthouse run | 3 (median; about 4 more minutes in `pnpm check`), because two pages sit exactly at 0.90 | Keep 1 (noise can fail a page that passes) |
| O7 | Which pages keep a mobile exception | Decided only after the final measurement (section 10); none pre-decided | Keep today's 0.8/0.85 values (not recommended: five of seven photo pages already pass) |
| O8 | Where the nginx rules are proven | Real nginx from apt in CI (option 1) | Podman container (not feasible in the Podman runner), local only |
| O9 | `pnpm check` when nginx is missing locally | Skip with a visible message locally, fail in CI | Require nginx everywhere |
Decided by the owner and the main session on 2026-11-01. Ids are kept.
| Id | Decision | Alternatives rejected |
|---|---|---|
| O1 | Server-side 301 to the canonical form on nginx and the preview server (and in the IIS rules, unverified); router unchanged | Router `caseSensitive: true` (fixes nginx, breaks IIS); serving non-canonical URLs as 404 (impossible on case-insensitive IIS) |
| O2 | Opt-in preview route `/__audit/404`, behind an explicit option that only the Lighthouse start command passes; `/404.html` stays a real 404. It exists only in the preview server and appears in no nginx or IIS rule | `ignoreStatusCode: true`; keeping the unit 1 fallback (200 at `/404.html`) |
| O3 | Only `/assets` is long-cached; every other file revalidates | Long cache for favicon, logos, OG images |
| O4 | Moot until a host exists; open point U1 | - |
| O5 | Moot until a host exists; open points U1 and U4 | - |
| O6 | `numberOfRuns: 1` stays. Known risk: pages right at 0.90 can fail `pnpm check` randomly. Final measurements for the owner's decisions use three runs, taken separately | `numberOfRuns: 3` in the config |
| O7 | Which pages keep a mobile exception is decided only after the final measurement (section 10) | Keeping the current 0.8/0.85 values |
| O8 | Real nginx from apt in CI, with parity tests against the preview server (P-HST-09) | Podman container (not feasible in the Podman runner); local only |
| O9 | Locally the nginx test is skipped with a visible message; in CI a missing nginx fails the job | Requiring nginx everywhere |
Pi steps: the hosting Pi part of H1 is done. The Pi-Main session never uses sudo; the nginx change (H2) is delivered as a draft in `server-ops` and installed by the owner only after the owner's separate approval, before the merge. Any proxy change (H4) is the owner's too.
## 15. Compliance notes
@@ -443,7 +453,7 @@ If `nginx -t` fails: `sudo cp` the `.bak-...` file back over `andreaslop-test.co
| SECURITY-04 | Compliant by design, proven in V2 and V4 | The five headers on every response: 200, 301, 404, the 404 page. nginx: `add_header ... always` in every location and at server level; IIS: `customHeaders`; preview: `send()`. P-HST-07 and P-HST-09 test it. The CSP is unchanged |
| SECURITY-09 | Compliant by design | No directory listing: nginx has no `autoindex on` and no `index`; IIS has `directoryBrowse` off (default) and rule 8; BR-HST-07 covers the file-next-to-directory case. Error pages are the static 404 page or the server's generic error; no stack traces, paths or versions are added (`server_tokens` is a Pi-level setting and outside this file; the `Server: nginx/1.24.0` header is visible today) |
| SECURITY-11 | Compliant | Misuse cases: path traversal (BR-SRV-06, P-HST-01), open redirect through `//host` or `/\host` (BR-HST-06, P-HST-04), CRLF injection through decoded `$uri` in a redirect (BR-HST-06, P-HST-07) |
| SECURITY-10 | Compliant | New dependency: none for the tests (nginx is a CI tool installed from the distribution; the probe kit and simulator are plain code) |
| SECURITY-10 | Compliant | New dependency: none for the tests (nginx is a CI tool installed from the distribution; no probe kit or simulator is built) |
| SECURITY-13 | Compliant | No external scripts; the 404 audit route is opt-in and absent from production hosts |
| SECURITY-15 | Compliant | The new post-deploy script fails closed; the artifact guard fails the upload on unexpected content |
| Others | N/A | No data stores, APIs, accounts or logging in this unit |