diff --git a/aidlc-docs/features/prerendering/audit.md b/aidlc-docs/features/prerendering/audit.md index cbde3da..d7b3285 100644 --- a/aidlc-docs/features/prerendering/audit.md +++ b/aidlc-docs/features/prerendering/audit.md @@ -347,3 +347,27 @@ **Context**: Code Generation unit 2 complete. --- + +## Infrastructure Design - Unit 3 Owner Answers + +**Timestamp**: 2026-11-01T04:30:00Z + +**User Input**: "continue to next stage" (answers through the chat dialog: webhost "Nog niet afgenomen"; Lighthouse "1 run, zoals nu"; Pi "Via sessie Pi-Main") + +**AI Response**: "Webhost not purchased, so the IIS probe kit and fallback variants are dropped; only the generated config and the host questions stay. numberOfRuns stays 1. The read-only compression check goes to the Pi-Main session; the owner gives separate approval for the nginx change. Remaining decisions made by the main session: O1 server 301 with an unchanged router; O2 opt-in audit route; O3 only /assets long-cached; O4 and O5 settled when a host exists; O8 and O9 real nginx in CI, skipped locally with a message." + +**Context**: Infrastructure Design unit 3. + +--- + +## Infrastructure Design - Unit 3 Approval Prompt + +**Timestamp**: 2026-11-01T05:00:00Z + +**User Input**: "(none: updated design reviewed by the main session; Pi-Main session reported the hosting Pi has no gzip active, nginx 1.30.6, vhost at /etc/nginx/conf.d/andreaslop-test.conf, changes through a server-ops draft)" + +**AI Response**: "Design updated. Asked for approval." + +**Context**: Infrastructure Design unit 3. Awaiting approval. + +--- diff --git a/aidlc-docs/features/prerendering/construction/hosting-and-targets/infrastructure-design/deployment-architecture.md b/aidlc-docs/features/prerendering/construction/hosting-and-targets/infrastructure-design/deployment-architecture.md index 2a6ed16..0f2bf1c 100644 --- a/aidlc-docs/features/prerendering/construction/hosting-and-targets/infrastructure-design/deployment-architecture.md +++ b/aidlc-docs/features/prerendering/construction/hosting-and-targets/infrastructure-design/deployment-architecture.md @@ -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-` 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-` 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 diff --git a/aidlc-docs/features/prerendering/construction/hosting-and-targets/infrastructure-design/infrastructure-design.md b/aidlc-docs/features/prerendering/construction/hosting-and-targets/infrastructure-design/infrastructure-design.md index a0cab13..ca94da3 100644 --- a/aidlc-docs/features/prerendering/construction/hosting-and-targets/infrastructure-design/infrastructure-design.md +++ b/aidlc-docs/features/prerendering/construction/hosting-and-targets/infrastructure-design/infrastructure-design.md @@ -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: `` with `` after a ``. `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: `` with `` after a ``. `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 `` 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 `` 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 [--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 /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-`, 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- /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 (` 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- /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 | diff --git a/aidlc-docs/features/prerendering/construction/plans/hosting-and-targets-infrastructure-design-plan.md b/aidlc-docs/features/prerendering/construction/plans/hosting-and-targets-infrastructure-design-plan.md index baceeea..0746a0a 100644 --- a/aidlc-docs/features/prerendering/construction/plans/hosting-and-targets-infrastructure-design-plan.md +++ b/aidlc-docs/features/prerendering/construction/plans/hosting-and-targets-infrastructure-design-plan.md @@ -2,7 +2,7 @@ Feature: prerendering. Unit: 3 "hosting-and-targets" (see [execution-plan.md](../../inception/plans/execution-plan.md) § Units of Work). Builds on unit 1 ([code summary](../start-migration/code/code-summary.md)) and unit 2 ([code summary](../display-fallbacks/code/code-summary.md), [measurement](../display-fallbacks/code/measurement-display.md)). Artifacts: [infrastructure-design/](../hosting-and-targets/infrastructure-design/). -No questions were needed. The brief fixed the scope and the open points; the choices that belong to the owner are written as recommendations with alternatives in `infrastructure-design.md` section 14 (O1 to O9). +No questions were needed. The owner and main session decided the open points on 2026-11-01; they are recorded as O1 to O9 in `infrastructure-design.md` section 14. Functional Design is skipped for this unit (execution plan); its rules (`BR-HST-xx`) and testable properties (PBT-01) are recorded in `infrastructure-design.md`. NFR Design is skipped; the logical components are the generated server configuration, the preview server, the CI jobs and the Lighthouse configuration. @@ -28,7 +28,7 @@ Functional Design is skipped for this unit (execution plan); its rules (`BR-HST- - [x] Step 6: Check the installed router (`caseSensitive`, `trailingSlash`) and Lighthouse 12.6.1 (`ignoreStatusCode`, `errors-in-console`) in `node_modules`, read only - [x] Step 7: Design the URL contract (BR-HST-01 to 08), the nginx and IIS rules, the directory trap and the redirect safety rules - [x] Step 8: Settle the compression cause as far as the evidence allows, design nginx and IIS compression (BR-HST-09 to 11) and write the Pi diagnosis commands -- [x] Step 9: Design IIS risk limiting: lock table, probe kit, fallback variants, rehearsal stages, questions for the webhost (BR-HST-19, 20; infrastructure-design §7, §8) +- [x] Step 9: Record the IIS unknowns (lock table, questions Q1 to Q6) and the "Before go-live on IIS" list; the probe kit, fallback variants and rule simulator were withdrawn by the owner because no host exists (BR-HST-19) - [x] Step 10: Design the deployment: upload order, `web.config` placement, guard, `deploy-test`, post-deploy script, nginx rollout order and rollback (BR-HST-14 to 18; deployment-architecture) - [x] Step 11: Design the Lighthouse targets, the 404 audit route and the owner-decision feed (BR-HST-21 to 23) - [x] Step 12: Record testable properties (P-HST-01 to 11) and the recommendation for proving nginx rules without a production server (BR-HST-24) @@ -38,3 +38,5 @@ Functional Design is skipped for this unit (execution plan); its rules (`BR-HST- - [x] Step 16: Create this plan and report to the orchestrator Not changed: application code, configuration, `audit.md`, `aidlc-state.md`, `requirements.md`; nothing installed, deployed or committed; no Lighthouse run; no login anywhere. +- [x] Step 17: Apply the owner and main-session decisions of 2026-11-01 (no IIS tooling, `numberOfRuns: 1`, O1 to O9) and update properties and verification list +- [x] Step 18: Apply the Pi-Main findings: gzip off on the hosting Pi (candidate B confirmed), nginx 1.30.6 version gap, vhost path `/etc/nginx/conf.d/andreaslop-test.conf`, `server-ops` draft process for H2