Files
SluijsensandClaude Opus 5.5 6d4d01238a Hardens the upload path check and the deploy verification
A remote of . or .. could have made the cleanup pass delete the wrong folder, so
such paths are refused before anything runs. A connection error now ends in the
normal summary instead of aborting the check.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 19:31:21 +01:00

53 KiB

Infrastructure Design: Unit 3 "hosting-and-targets"

Feature: prerendering. Requirements: FR-PR-14 to 18, 23; NFR-PR-P-01, P-02, S-01 (requirements.md). Companion: deployment-architecture.md. Plan: hosting-and-targets-infrastructure-design-plan.md.

Unit 3 skips Functional Design (execution-plan.md), so its rules and testable properties (PBT-01) are recorded here. Rule ids are BR-HST-xx. Nothing in this document is implemented yet; no application or configuration file was changed.

1. Summary of decisions

# Decision Rules
1 One URL contract for nginx, IIS and the preview server, generated from one page list (sitePages) BR-HST-01 to 08
2 Unknown URLs get 404.html with a real 404; the SPA fallback is removed everywhere BR-HST-02
3 Trailing slash, .html, /index and letter case are canonicalised with one 301 for known pages; the client router stays unchanged BR-HST-03, 04, 08
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 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, 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

2.1 What is live today (read-only curl from this PC, 2026-11-01)

Check Result Meaning
test.andreaslop.nl and andreaslop.nl Both resolve to 217.121.250.215 One public address, one reverse proxy
https://andreaslop.nl/ Server: nginx/1.24.0, Link: .../wp-json/ Production name still serves WordPress on the Pi. The IIS host is not live; DNS has not moved (matches D12 of frontend-shell). Whether the hosting package exists is not visible from here
https://test.andreaslop.nl/over-mij 200, 3368 bytes, the old SPA index.html Test still has the old build and the old nginx config (SPA fallback)
https://test.andreaslop.nl/ with Accept-Encoding: gzip 200, Content-Length: 3368, no Content-Encoding, strong ETag, no Vary Not compressed
/assets/index-DE7NmAmk.js 536,695 bytes, application/javascript, no Content-Encoding Not compressed
WordPress on andreaslop.nl: HTML (chunked) and wp-content/.../*.min.css (17,798 bytes) no Content-Encoding Same chain, same result: not specific to the test block
http://192.168.1.103/ (hosting Pi) Timeout Private LAN address; not reachable from here

2.2 Compression cause (FR-PR-23)

Established from outside (2026-11-01): nothing on the path compresses, for the test site and for WordPress alike.

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.

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

Spike (scratch, not in the repo): a case-sensitive static server over the real dist/client, Chrome (system, playwright-core), requests of /over-mij variants. Mode A is today's rule (unknown path gives 404.html with 404). Mode B adds a 301 to the canonical form for known pages.

Request Mode A (today) Mode B (redirect)
/over-mij 200, 1 title, 0 robots same
/Over-Mij, /Over-Mij?x=1 404 body, router renders "Over mij": 2 titles, 1 noindex robots meta 301 /Over-Mij then 200 /over-mij (query kept): 1 title, 0 robots
/over-mij/, /over-mij/?x=1 404 body, same mismatch (router tidies the address bar to /over-mij) 301 then 200 /over-mij (query kept), clean
/soorten-fotoshoots/ 404 body, 2 titles 301 then 200 /soorten-fotoshoots, clean
/onbekend 404, 1 title, 1 robots (correct) same

No console errors or React #418 appeared in this run (the race described in the verification log); the stale second title and noindex meta appear in mode A, which is the SEO consequence of BR-404-07.

Why the router is not the fix: TanStack Router has a global caseSensitive option (router.d.ts) but the servers disagree. nginx is case-sensitive, IIS is not. With caseSensitive: true, nginx is consistent (404 body, router renders the catch-all) but IIS serves over-mij.html for /Over-Mij and the router renders the catch-all over it: a new mismatch. With the default (insensitive), IIS is consistent and nginx is not. No router setting suits both, so the servers must agree among themselves: redirect to the canonical form. The router then never sees a non-canonical known URL, and its settings stay as they are (default trailingSlash: 'never', case-insensitive). Whether caseSensitive: true would additionally be good defence was not run in Chrome (it needs a rebuild); it is not adopted because of the IIS mismatch above.

3. URL contract

Applies to nginx (test), IIS (production) and the preview server (Lighthouse, browser tests). "Page" means a path in sitePages (11 pages: / and 10 others). pageFile(path) is x.html; / is index.html.

Rule Statement Source
BR-HST-01 / serves index.html, status 200. /x (last segment without a dot) serves x.html with 200 when it exists, without a redirect, also when a directory x/ exists next to x.html. A file request (last segment with a dot) serves that file with 200. ?query is ignored for lookup FR-PR-16
BR-HST-02 Anything that does not exist serves 404.html with a real 404. There is no SPA fallback on any server (try_files ... /index.html and the IIS rule "SPA fallback" are removed). Responses to missing /assets/* also carry the 404 page FR-PR-14; D5
BR-HST-03 A path of more than one character that ends in one or more / gets one 301 to the path without trailing slashes. The query string is kept byte for byte. / stays. Applies to every path, known or not (/onbekend/ goes to /onbekend, which is a 404) FR-PR-16
BR-HST-04 For a known page, every variant is redirected with one 301 to its canonical path (the sitePages key): case variants, with or without .html, with or without trailing slashes, in any combination (/Over-Mij/ goes straight to /over-mij). /index, /index.html and their variants go to /. Unknown paths are never redirected for case (/Onbekend is a 404). Query kept FR-PR-16
BR-HST-05 /404 and /404.html answer with status 404 and the 404 page (not 200, not a redirect), on every server. The page stays noindex and out of the sitemap FR-PR-14; Application Design, Consequences
BR-HST-06 A redirect Location is built from the constant page list or from the request path minus trailing slashes, never starts with // or /\, and contains no control characters. On nginx it is never built from a decoded $uri in return (CRLF injection) SECURITY-11 misuse case
BR-HST-07 Directory trap. soorten-fotoshoots.html and the directory soorten-fotoshoots/ coexist in dist/client. nginx: try_files never contains $uri/ and the config has no index and no autoindex on. IIS: the page rule rewrites before the handler can issue its own directory redirect, and a directory-only name (/assets) is answered with a 404 by an explicit rule, so IIS cannot redirect it back to /assets/ and loop against BR-HST-03. No server ever lists a directory SECURITY-09
BR-HST-08 Server and router agree by canonicalisation (BR-HST-03, 04), not by a router setting. After a redirect the URL is lowercase, slash-free and .html-free, so the first browser render matches the HTML. The router configuration is unchanged BR-404-07

Empty segments inside a path (//x) stay undefined: nginx merges the slashes and serves the page, the preview server answers 404 (BR-SRV-07), IIS depends on HTTP.sys. This cannot produce a mismatch (the router matches the same page) and is outside the parity set; the redirect rules never produce a // target (BR-HST-06).

3.1 Result table

Request Result on all three servers
/, /over-mij, /soorten-fotoshoots, /soorten-fotoshoots/newborn, any of them with ?query 200, the page file
/over-mij/, /over-mij///, /soorten-fotoshoots/ (+ ?x=1) 301 to /over-mij, /over-mij, /soorten-fotoshoots (+ ?x=1)
/over-mij.html, /soorten-fotoshoots/newborn.html 301 to /over-mij, /soorten-fotoshoots/newborn
/index, /index.html, /index/ 301 to /
/Over-Mij, /OVER-MIJ.HTML, /Over-Mij/ 301 to /over-mij
/404, /404.html 404, the 404 page
/onbekend, /Onbekend, /x.html (unknown), /assets/missing.js 404, the 404 page
/onbekend/ 301 to /onbekend, then 404
/assets, /assets/ 404 (the second via one 301 to /assets); no listing
/assets/index-HASH.js, /robots.txt, /sitemap.xml, /favicon.png 200, the file
Other methods than GET/HEAD Preview: 405. nginx: its own 405. IIS: static handler default

Test host exception (unchanged): /robots.txt returns Disallow: / and every response carries X-Robots-Tag: noindex, nofollow.

3.2 Decision flow

graph TD
    Req["Request path"] --> Dec["Decode once, reject NUL, backslash and dot segments"]
    Dec -->|"bad"| NF["404 with 404.html"]
    Dec --> Canon{"Known page in a non-canonical form?"}
    Canon -->|"yes"| R1["301 to the canonical page, query kept"]
    Canon -->|"no"| Slash{"Trailing slash on a path longer than one char?"}
    Slash -->|"yes"| R2["301 to the path without slashes, query kept"]
    Slash -->|"no"| Direct{"Is it /404 or /404.html?"}
    Direct -->|"yes"| NF
    Direct -->|"no"| Root{"Is it the root?"}
    Root -->|"yes"| Idx["200 index.html"]
    Root -->|"no"| Dot{"Last segment has a dot?"}
    Dot -->|"yes"| F1{"File exists?"}
    Dot -->|"no"| F2{"Page file x.html exists?"}
    F1 -->|"yes"| OK["200 the file"]
    F1 -->|"no"| NF
    F2 -->|"yes"| OK
    F2 -->|"no"| NF
    classDef client fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000;
    classDef gateway fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
    classDef service fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
    classDef database fill:#fbd38d,stroke:#92400e,stroke-width:1px,color:#000;
    class Req client;
    class Dec,Canon,Slash,Direct,Root,Dot,F1,F2 gateway;
    class Idx,OK service;
    class R1,R2,NF database;

Text alternative: a request is decoded and checked, then known pages in a non-canonical form and trailing slashes get one 301, /404 and /404.html get the 404 page, and everything else is served as a file or a page file (200) or as the 404 page (404).

4. Server rules

4.1 Page list as the single source

The generator and the preview server take the page list from Object.keys(sitePages) through one pure module (proposed config/canonicalUrls.ts). It exports the canonical-redirect function used by the preview server and the data (page list, NOT_FOUND_PATH) from which the nginx map and the IIS rule are generated. A new page appears in all three at once; the build already fails if a page has no HTML file (FR-PR-03). A test fails if dist/client holds an HTML file other than index.html, 404.html and the page files, because such a file would be served by try_files without being canonicalised.

4.2 nginx (generated andreaslop-test.conf)

Normative sketch; the generator is the source of the final text. Constraints: everything lives inside the file (no change to the Pi's global nginx.conf), the file is included inside http {} (as now, through conf.d), variable names carry the prefix andreaslop_ to avoid clashes with the WordPress configuration.

map $uri $andreaslop_canonical {
    default "";
    # canonical forms: exact entries win over the regexes below
    /over-mij "";                     # one line per page except /
    # variants: case-insensitive, optional .html, optional trailing slashes
    ~*^/index(\.html)?/*$ /;
    ~*^/over-mij(\.html)?/*$ /over-mij;   # one line per page except /
}

server {
    listen 80;
    server_name test.andreaslop.nl;
    root /var/www/html/andreaslop-test;
    absolute_redirect off;
    autoindex off;                    # no index directive on purpose
    <security headers + Cache-Control no-cache + X-Robots-Tag, always>

    gzip on;
    gzip_vary on;
    gzip_proxied any;
    gzip_http_version 1.0;
    gzip_comp_level 5;
    gzip_min_length 256;
    gzip_types text/css text/plain text/xml application/xml application/javascript
               text/javascript application/json image/svg+xml;   # text/html is implicit

    if ($andreaslop_canonical) { return 301 $andreaslop_canonical$is_args$args; }
    rewrite ^/(.+?)/+$ /$1 permanent;   # BR-HST-03, safe escaping, query kept

    error_page 404 /404.html;

    location = /robots.txt { <headers> default_type text/plain; return 200 "User-agent: *\nDisallow: /\n"; }
    location = /404        { <headers> return 404; }
    location = /404.html   { internal; <headers + no-cache> }
    location /assets/      { <headers + immutable> try_files $uri =404; }
    location = /           { <headers + no-cache> try_files /index.html =404; }
    location /             { <headers + no-cache> try_files $uri $uri.html =404; }
}

Reasons for the non-obvious choices:

  • try_files $uri $uri.html =404: $uri without a trailing slash only matches files, so a directory soorten-fotoshoots/ is skipped and soorten-fotoshoots.html is served (BR-HST-07). $uri/ or an index directive would trigger nginx's own directory redirect. index is also dangerous here: it makes an internal redirect to /index.html, which BR-HST-04 redirects to /, a loop. Hence location = / with try_files /index.html =404.
  • Redirect targets: the map values are constants. The generic slash rule uses rewrite ... permanent, which escapes the target; return 301 $uri or $1 taken from $uri would allow header injection (BR-HST-06).
  • error_page 404 /404.html keeps the status 404 (no =). location = /404.html is internal: a direct request is answered 404, which error_page turns into the 404 page with status 404 (BR-HST-05). location = /404 returns 404 the same way; without it $uri.html would serve the page with 200.
  • Security headers are repeated in every location (as now) and at server level; always makes them apply to 301, 404 and the 404 page (SECURITY-04). Whether the server-level if redirect carries them must be proven with a real nginx (BR-HST-24).
  • gzip_http_version 1.0 makes compression work however the proxy talks to this block. gzip_proxied any covers requests that carry Via. gzip_types lists MIME types, so it includes both the types nginx's mime.types gives (application/javascript, text/xml) and the ones the preview server uses. It is generated from the same list as the preview server's COMPRESSIBLE set (BR-HST-11).
  • if is used only with return at server level, the one safe form.
  • No map rule may match /404 or /404.html. error_page's internal redirect runs the server-level if and rewrite again with $uri=/404.html; a matching rule would turn the 404 page into a redirect (P-HST-07 tests it).
  • Headers per location. add_header in a location replaces all server-level add_header. Every location with its own add_header repeats the whole set, and /assets/ carries exactly one Cache-Control. Tested in the generated text (P-HST-07) and against a real nginx on 301, 404 and the 404 page (P-HST-09). etag stays on.
  • The default block of the Pi (00-default.conf) answers an unknown host with 444; the test block is chosen by server_name. The header comment of the generated file says so (the old remark about a fallback to WordPress is removed).

Caching (nginx): /assets/* public, max-age=31536000, immutable; everything else no-cache (HTML, robots.txt, sitemap.xml, favicon.png, logos). See decision O3 for why unhashed files are not long-cached.

Proxy config (test.andreaslop.nl.proxy.conf, on the other Pi): not required to change for compression. Optional hygiene: add proxy_http_version 1.1; and proxy_set_header Connection ""; inside location /. Because certbot edits this file, the change is made by hand in place (H4), never by copying the repo file over it. The generated file may carry the two lines for new installs.

4.3 IIS (generated web.config)

Rule order inside <rewrite><rules> (all stopProcessing="true"). The two existing rules stay first; the "SPA fallback" rule is removed.

# Rule Match (url relative to the site root, ignore case) Conditions Action
1 www naar andreaslop.nl unchanged unchanged unchanged
2 HTTPS unchanged unchanged unchanged
3 Index naar root ^index(?:\.html)?/*$ none Redirect /, permanent
4 Pagina canoniek ^(?:pages joined by |)(?:\.html)?/*$ {R:0} does not match ^(?:pages)$ with ignoreCase false Redirect /{ToLower:{R:1}}, permanent
5 Slash weg ^([^/\\].*?)/+$ none Redirect /{R:1}, permanent
6 404 direct ^404(?:\.html)?$ none CustomResponse 404
7 Pagina bestand ^(.+)$ {REQUEST_FILENAME}.html IsFile Rewrite {R:1}.html
8 Map zonder pagina ^(.+)$ {REQUEST_FILENAME} IsDirectory CustomResponse 404

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

5. Compression (FR-PR-23)

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

The preview server keeps its gzip (BR-SRV-08). Lighthouse therefore measures compressed transfer sizes on the preview, which is also what the test and production hosts will now deliver; before this unit, test did not.

6. Caching and headers

Rule Statement
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 set no cache header of their own (browsers may keep a 301; acceptable because the redirect set is fixed by the page list). On nginx the 301s from the server-level if and rewrite do inherit the server-level Cache-Control: no-cache; that is harmless (a 301 is revalidated instead of kept) and needs no config change. Known difference: the preview server sends no Cache-Control on its 301s, so a parity test must not compare that header on redirects
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()

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: unverified rules and "Before go-live on IIS"

7.1 What may be locked or missing at the webhost

The package is shared hosting ("ASP.NET Core 10", Windows/IIS, URL Rewrite per the hoster's page) reached over FTPS. Production has never been deployed (production-readiness-checklist: "Never run yet"), so none of the web.config sections below has been proven on that host, including the ones frontend-shell already uses.

Section / feature Used for Can it be locked or missing? If it is
system.webServer/rewrite/rules (URL Rewrite 2.x) all URL rules The hoster names URL Rewrite, version unknown. {ToLower:} and CustomResponse need 2.0+ Module missing: web.config is rejected (500.19) for the whole site
system.webServer/httpErrors (existingResponse, responseMode, errorMode) the 404 page with status 404 Default delegation is usually Allow, but hosts lock it. allowAbsolutePathsWhenDelegated matters only for File mode, which this design avoids 500.19 for the whole site
system.webServer/httpProtocol/customHeaders security headers (SECURITY-04) Normally allowed 500.19 for the whole site
system.webServer/staticContent (mimeMap, clientCache) caching, MIME pins Normally allowed 500.19 for the whole site
system.webServer/urlCompression enabling compression Usually allowed; the static compression module must be installed 500.19 if locked; no effect if the module is missing
system.webServer/httpCompression which types and level Server level only (applicationHost.config). Not used in web.config Using it would give 500.19 for the whole site
Site root where web.config takes effect The FTP folder wwwroot may be the app's static web root below the real IIS site root, in which case a web.config placed there does not apply to / Rules silently absent. Unknown until probed

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

Before go-live on IIS (a short list, no tooling):

  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
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); in particular /404.html is answered by rule 6 as a 404 and then executed through ExecuteURL, so if rewrite rules also run on that child request, the 404 page could come back empty 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
  1. 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.
  2. After the first run on a real host, record the result in a verification log and close or re-open U1 to U6.
  3. 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

Ask (support ticket, one message):

  1. Q1. What is the physical path of the IIS site: the FTP root, or the FTP folder wwwroot? If an ASP.NET Core module (aspNetCore handler) is configured at the site root, may it be removed, since this site is static?
  2. Q2. Is URL Rewrite Module 2.1 or newer installed and delegated (system.webServer/rewrite/rules) at site level?
  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 or can it be tried before buying, and is a temporary URL or the A-record IP available before DNS changes?

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/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 (H2, pi-install-instructions.md): config placed and reloaded, and the deploy right after (a manual branch deploy or the merge), proven by the checks of H3. 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)

10. Lighthouse targets (NFR-PR-P-01, P-02, S-01)

Rule Statement
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 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:

  1. After code generation of this unit, Build and Test runs the same method as measurement-display.md (3 runs per URL, median, same PC, previewServer.ts, configs unedited) into construction/hosting-and-targets/code/measurement-final.md, one row per page with master, unit 1, unit 2 and final scores.
  2. Pages at 0.90 or higher on mobile need no exception. The exceptions in today's file disappear for them.
  3. Each page below 0.90 goes to the owner with its score, LCP element and the options: keep an exception at a stated floor, work on it, or accept a red pnpm check. Nothing is lowered or left in place without that answer (NFR-PR-P-01).
  4. Starting point from the unit 2 measurement (mobile, median of 3): / 0.85 (LCP element is the heading, 4356 ms, so it is not photo-bound; the trace V-D10 is still open), gezin 0.89, loveshoot 0.88; zwangerschap and portret exactly 0.90 (inside run-to-run noise, so a single run can flip them). All other pages are 0.91 or higher. Desktop 0.99 or better on all URLs.

11. Testable properties (PBT-01)

Generators: known pages x variants (case permutation, .html, 0 to 3 trailing slashes, query), unknown segments from a safe alphabet, and hostile strings (%2e%2e, //host, \, NUL, CR/LF, very long).

Id Property Component Style
P-HST-01 resolveRequest is total: never throws; status is 200, 301 or 404; file never contains .. and is never absolute previewServer.ts Invariant
P-HST-02 Every variant of a known page resolves to a 301 whose target is the canonical path, or (if canonical) to 200 with pageFile canonicalUrls.ts, preview Invariant
P-HST-03 Termination: following redirects from any input reaches a non-redirect in at most 2 hops; a canonical target is a fixpoint same Idempotence
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 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 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.

11.1 Proving the nginx rules without a production server

Option Pros Cons
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 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 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)
V10 lftp: dry run against a file: target proves that pass 1 skips all nested *.html and web.config, pass 2 uploads them, pass 3 deletes only stale files
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 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 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 (read-only; runs through the Pi-Main session, no sudo).

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

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

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:

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: 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 (the owner places it, after separate approval).

The exact steps, checks, expected results and rollback are in pi-install-instructions.md (written by the Pi-Main session; it holds the full commands). Summary of what differs from earlier drafts of this design:

  1. The generated web/deploy/nginx/andreaslop-test.conf is delivered as a draft in the server-ops repository; the Pi-Main session never uses sudo.
  2. The backup goes to /mnt/storage1/backups/andreaslop-test-nginx/andreaslop-test.conf.spa, outside conf.d (a *.conf backup in conf.d would be loaded by nginx).
  3. The owner places the file as root:root 644 at /etc/nginx/conf.d/andreaslop-test.conf, runs sudo nginx -t && sudo systemctl reload nginx; sudo systemctl restart nginx is the fallback if the reload does not take effect.
  4. Timing: place and reload the config, and start the deploy right after (a manual branch deploy from feature/prerendering, or the merge). Do not leave a day in between: the new config with the old build gives 404 on /over-mij, and the old config with the new build shows the home page there. A short mismatch is acceptable on test.

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. Proxy Pi (the owner checks; changes are the owner's). Use the table "Proxy Pi (192.168.1.102): the owner checks" in pi-install-instructions.md: Accept-Encoding overrides, proxy_http_version, proxy_intercept_errors/error_page, own add_header, proxy_cache, proxy_redirect. A proxy change (for example proxy_http_version 1.1; and proxy_set_header Connection ""; in location /, edited in place because certbot owns the file) is made only if a check shows a problem. Not expected to be needed for compression, because the new block works over HTTP/1.0.

Rollback of H2/H3 (the owner). As in pi-install-instructions.md: copy /mnt/storage1/backups/andreaslop-test-nginx/andreaslop-test.conf.spa back over /etc/nginx/conf.d/andreaslop-test.conf, sudo nginx -t && sudo systemctl reload nginx, then deploy an old SPA 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

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 and the install instructions exist (pi-install-instructions.md). 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

Security Baseline

Rule Status How
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; 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

Property-Based Testing

Rule Status Note
PBT-01 Compliant P-HST-01 to 11 above
PBT-09 Compliant fast-check is already a dependency; the oracle tests use it with a bounded number of runs because they make real HTTP requests
PBT-02 to 08, 10 N/A at this stage Enforced in Code Generation and Build and Test: seed logging, shrinking and example-based companions as in the existing suite