Files
AndreaSlopFotografie/aidlc-docs/features/prerendering/construction/hosting-and-targets/infrastructure-design/pi-install-instructions.md
T
SluijsensandClaude Opus 5.5 33334b889d Generates the nginx rules for prerendered pages
Pages now map to their html file, other forms get one redirect, unknown URLs
get a real 404 and responses are compressed. A browser-free test suite runs the
rules against a real nginx, in CI only so far.

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

7.0 KiB

nginx Install Instructions for the Test Host

Written for: the owner, who places the config. Source: the Pi-Main session on web1.slpsoftware.nl (192.168.1.103), 2026-11-01, read-only and without sudo. nginx -t was not run; that happens at installation.

The final commands with full paths go into the draft in the server-ops repository, for example drafts/2026-11-xx-andreaslop-prerender/ with README.md and andreaslop-test.conf. The owner places it as pi-main with sudo, following that README and the checklist in drafts/2026-10-20-hardening/README.md. Nothing here has been carried out. The draft is requested separately, with the generated text.

Checked on the server

Point Finding
map and $andreaslop_canonical No clash. The only other map in /etc/nginx is $connection_upgrade in nginx.conf. All conf.d files are included in http (nginx.conf line 38), so a map at the top of the file is at http level
root /var/www/html is a symlink to /mnt/storage1/www/html/; /var/www/html/andreaslop-test exists (webadmin:www-data, 775). The owner confirmed DEPLOY_PATH_TEST is /var/www/html/andreaslop-test, which equals this root
gzip and headers from other vhosts gzip is on nowhere, and nginx.conf has no http-level add_header. gzip in this server block changes no other site
Default block Since 2026-10-21, /etc/nginx/conf.d/00-default.conf answers an unknown host with 444. The current comment that nginx would fall back to WordPress is out of date; correct it in the generator
nginx 1.30.6 Every directive in the sketch is standard there. if with only return at server level is safe
map matching Exact strings win over regexes, so /over-mij "" beats the variant regex and no loop arises
error_page Its internal redirect runs server-level rewrite and if again with $uri=/404.html. That matches no map rule. Keep it so: no map rule may match /404 or /404.html
Directories try_files $uri matches files only, so /assets gives 404

Installation

Order: place the config, reload, and start the deploy right after: manually from the branch, or by merging. 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 homepage there. A short mismatch is acceptable on test.

# Backup outside conf.d: a *.conf backup in conf.d would be loaded by nginx
sudo install -d -o root -g root -m 700 /mnt/storage1/backups/andreaslop-test-nginx
sudo cp -p /etc/nginx/conf.d/andreaslop-test.conf /mnt/storage1/backups/andreaslop-test-nginx/andreaslop-test.conf.spa

# Place (the current file is root:root 644)
sudo install -o root -g root -m 644 /home/claude/server-ops/drafts/<folder>/andreaslop-test.conf /etc/nginx/conf.d/andreaslop-test.conf
sudo nginx -t && sudo systemctl reload nginx

If nginx -t fails, nginx does not reload. Put the backup back. Use reload first. Reload has not been tested separately on 1.30.6 on this Pi, because nginx was restarted after that update. If the new config does not work after the reload, sudo systemctl restart nginx is the fallback.

Checks on the Pi

The Pi-Main session can run these too, without sudo. They need the new build deployed.

for p in / /over-mij /over-mij.html /over-mij/ /index.html /bestaat-niet /404 /robots.txt; do curl -s -o /dev/null -w "$p %{http_code} %{redirect_url}\n" -H 'Host: test.andreaslop.nl' http://127.0.0.1$p; done
curl -s -o /dev/null -D - -H 'Host: test.andreaslop.nl' -H 'Accept-Encoding: gzip' --http1.0 http://127.0.0.1/ | grep -iE '^(HTTP|content-encoding|vary|cache-control|content-security)'

--http1.0 is deliberate: that is how the proxy Pi talks to this Pi. Run the second command for one file in /assets/ too.

Expected:

  • / and /over-mij give 200.
  • /over-mij.html, /over-mij/ and /index.html give 301 with a relative Location.
  • /bestaat-niet and /404 give 404 with the content of 404.html.
  • /robots.txt gives 200.
  • Content-Encoding: gzip and Vary: Accept-Encoding are present.
  • The security headers are also on the 404.
  • Assets have immutable.

Also check that andreaslop.nl, gitea.slpsoftware.nl and phpMyAdmin still give 200. Then repeat the checks on https://test.andreaslop.nl/ from outside.

Rollback

sudo cp -p /mnt/storage1/backups/andreaslop-test-nginx/andreaslop-test.conf.spa /etc/nginx/conf.d/andreaslop-test.conf
sudo nginx -t && sudo systemctl reload nginx

Then deploy an old SPA build.

Proxy Pi (192.168.1.102): the owner checks

The proxy Pi handles TLS through certbot and forwards test.andreaslop.nl to 192.168.1.103:80. The Pi-Main session has no access to it. Run sudo nginx -T and look for:

Look for Why
proxy_set_header Accept-Encoding "" or similar The backend then never gets a gzip request, and gzip here has no effect
proxy_http_version When unset it is 1.0; gzip_http_version 1.0 in the new block is there for this
proxy_intercept_errors or error_page The proxy would replace 404.html with its own error page
Own add_header, especially HSTS, CSP, X-Frame-Options, Cache-Control Double or conflicting headers. Two CSP headers are both enforced
proxy_cache An old SPA index.html could stay cached for /over-mij
proxy_redirect Could change the relative 301s

Checked by the owner on 2026-11-01, reported through the Pi-Main session: no change needed on the proxy Pi. The server block has proxy_pass http://192.168.1.103 with Host, X-Forwarded-Proto, X-Forwarded-For and X-Real-IP, and no proxy_http_version (so HTTP/1.0 upstream), no change to Accept-Encoding, no proxy_intercept_errors and no add_header. At http level there is no gzip, proxy_cache, add_header or proxy_buffering. So gzip_http_version 1.0 must stay in the new block, all headers and the 404 page come from the hosting Pi, and no cache holds old pages. http2 on; in the 443 block is an optional, separate improvement, out of scope for this feature.

The proxy passes an already compressed response through unchanged. If the owner wants gzip for all sites, WordPress included, the proxy Pi is the place for that, and this block can keep its own.

Points for the generated config

  • add_header in a location replaces all server-level add_header. Every location with its own add_header repeats the whole set, certainly /assets/ (immutable), or it loses CSP and HSTS. A location without add_header inherits. /assets/ carries one Cache-Control, not a second one.
  • etag stays on (the default), so no-cache revalidates cheaply.
  • The deploy must empty the target folder, or a removed page stays at 200. The deploy-test step already does this with find -delete.
  • location = /robots.txt overrides the build's robots.txt, which is right for test. Production must serve the real robots.txt and sitemap.xml.
  • gzip_proxied any does little here, since the proxy sets no Via, but it does no harm. listen 80 on IPv4 is enough.