Splits nginx routing into a from-scratch procedure plus the example

New section walks through adding any domain from nothing - plain
HTTP block first (certbot's nginx plugin needs one to validate
against), then the certbot command, then a verification step. The
existing slpsoftware.nl blocks stay as the worked result of that
procedure rather than a separate one-off.

aidlc-docs/features/gitea-deployment-workflow/audit.md

@@ -1378,3 +1378,13 @@ by Infrastructure Design. U5 carries REF-U3-01's Umami origin gate plus FR-21 an
 **Context**: OPERATIONS — Deployment Setup, host-setup troubleshooting root cause confirmed and documented
 
 ---
+## Deployment Setup — nginx Routing Rewritten for a From-Scratch Procedure
+
+**Timestamp**: 2026-07-29T00:30:00Z
+
+**User Input**: "IN de deployment instructions zou ik voor nginx routing graag documentatie willen die uitgaat van een lege situatie. De huidige situatie mag ook gedocumenteerd blijven, maar bij aanmaken van nieuwe websites/API's moet ik vanaf niets iets op kunnen zetten. Dat mag pre-certbot + het certbot command wat ik zou moeten draaien"
+
+**AI Response**: "Restructured deployment-instructions.md § 1.7 into two parts: § 1.7.1 is a generic, repeatable from-scratch procedure for adding any new domain to this Pi (plain HTTP server block first, since certbot's nginx plugin needs a working HTTP block to attach to and validate against, then the certbot --nginx command which edits the file in place to add the SSL block and redirect, then a verification curl), explicitly reusable for future websites/APIs beyond this feature. § 1.7.2 keeps the existing slpsoftware.nl/test.slpsoftware.nl blocks as the worked example this procedure produces, not a separate step."
+
+**Context**: OPERATIONS — Deployment Setup, nginx documentation generalized for reuse
+---

aidlc-docs/features/gitea-deployment-workflow/operations/deployment/deployment-instructions.md

@@ -212,8 +212,65 @@ systemctl --user enable slpsoftware-production.service
 ```
 
 ### 1.7 nginx Routing
+
 The existing reverse proxy (`infrastructure-design.md` § 1, § 4) needs a server block per domain,
-routing to the matching local port:
+routing to the matching local port. Two subsections: § 1.7.1 is the repeatable, from-scratch
+procedure for adding *any* new site or API to this Pi (this deployment's domains included, the
+first time); § 1.7.2 is simply what that procedure produced for `slpsoftware.nl` — read it as the
+worked example, not a separate step.
+
+#### 1.7.1 Adding a New Domain From Scratch
+
+Starting from nothing — no existing server block, no certificate — for a new domain
+`<new-domain>` routing to a local port `<local-port>`:
+
+**Step 1 — plain HTTP block, no TLS yet.** Certbot's nginx plugin (step 2) needs a working HTTP
+server block for the domain to attach to and to answer the HTTP-01 validation challenge; asking
+for a certificate before this exists will fail.
+
+```nginx
+server {
+    listen 80;
+    server_name <new-domain>;
+    location / {
+        proxy_pass http://127.0.0.1:<local-port>;
+        proxy_set_header Host $host;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+}
+```
+
+Save as `/etc/nginx/sites-available/<new-domain>`, symlink it into `sites-enabled/`, then:
+```bash
+sudo nginx -t && sudo systemctl reload nginx
+```
+
+Confirm the domain's DNS `A`/`AAAA` record already points at this Pi before continuing — the
+HTTP-01 challenge in step 2 needs the domain to actually resolve here.
+
+**Step 2 — request and install the certificate.** The nginx plugin edits the file from step 1 in
+place: it adds the `listen 443 ssl` block, the certificate/key paths, and (by default) an
+HTTP→HTTPS redirect for the port 80 block:
+```bash
+sudo certbot --nginx -d <new-domain>
+```
+Certbot's own systemd timer handles renewal automatically — nothing further to set up for that.
+
+**Step 3 — verify.** After certbot finishes:
+```bash
+curl -I https://<new-domain>/health   # or whichever path this new site/API actually serves
+```
+Confirm it resolves over HTTPS with a valid certificate and reaches the expected local port.
+
+Repeat steps 1–3 once per domain. This is the same procedure regardless of whether the new domain
+is another environment for this feature, a completely different project's API, or a plain static
+site — nginx and certbot don't know or care what's listening on the local port they proxy to.
+
+#### 1.7.2 Current State for This Deployment
+
+Running the procedure above for `test.slpsoftware.nl` and `slpsoftware.nl` produces (after
+certbot has added its blocks) server blocks equivalent to:
+
 ```nginx
 server {
     listen 443 ssl;
@@ -223,6 +280,7 @@ server {
         proxy_set_header Host $host;
         proxy_set_header X-Forwarded-Proto $scheme;
     }
+    # certbot-managed ssl_certificate / ssl_certificate_key / include lines omitted here
 }
 
 server {
@@ -233,10 +291,9 @@ server {
         proxy_set_header Host $host;
         proxy_set_header X-Forwarded-Proto $scheme;
     }
+    # certbot-managed ssl_certificate / ssl_certificate_key / include lines omitted here
 }
 ```
-TLS certificate provisioning (e.g. certbot) is existing host operations, out of scope for this
-feature — assumed already handled the same way the reference project's domains are.
 
 ### 1.8 Database Backup Credentials (§ 4 depends on this)
 ```bash