update

README.md

@@ -16,46 +16,111 @@ nginx -t
 systemctl reload nginx
 ```
 
-## Usage
+## Contexts
 
-In server block:
+This repository is organized by nginx context:
+
+- `http/`: snippets that must be included inside `http {}`.
+- `ssl/`: HTTPS and TLS snippets for `server {}` blocks.
+- `proxy_pass/`: reverse proxy snippets for `location {}` blocks.
+- `redirect/`: host and canonical URL redirects for `server {}` blocks.
+- `templates/`: copy-and-edit starter snippets such as certificates.
+- `examples/`: working examples showing how to compose the snippets.
+
+## Common combinations
+
+### HTTPS site
+
+Include these inside a `server {}` block:
 
 ```nginx
 server {
 	# ...
 	include snippets/cert/mydomain.com.conf;
-	include	kit/ssl/security.conf;
+	include kit/security.conf;
-	include	kit/ssl/hsts.conf;
+	include kit/ssl/security.conf;
-	include	kit/ssl/force.conf;
+	include kit/ssl/hsts.conf;
+	include kit/ssl/force.conf;
 	# ...
 }
 ```
 
-### Tamplates
+See [examples/example.com.conf](examples/example.com.conf:1) for the full server-level example.
 
-#### SSL Certs
+### Reverse proxy with websocket support
+
+Websocket proxying needs one `http {}`-level `map` plus `location {}`-level proxy snippets:
+
+```nginx
+http {
+	include kit/http/websocket-map.conf;
+
+	server {
+		# ...
+		location / {
+			include kit/proxy_pass/forwarded.conf;
+			include kit/proxy_pass/timeout-300.conf;
+			proxy_pass http://app_backend;
+		}
+
+		location /ws/ {
+			include kit/proxy_pass/forwarded.conf;
+			include kit/proxy_pass/websocket.conf;
+			include kit/proxy_pass/timeout-300.conf;
+			proxy_pass http://app_backend;
+		}
+	}
+}
+```
+
+See [examples/reverse-proxy.nginx.conf](examples/reverse-proxy.nginx.conf:1) for a complete standalone config.
+
+## Templates
+
+### SSL certs
 
 ```bash
 cd /etc/nginx
-mkdir snippets/cert
+mkdir -p snippets/cert
 cp kit/templates/cert/example.com.conf snippets/cert/mydomain.com.conf
 vi snippets/cert/mydomain.com.conf
 ```
 
-Replace the path with yours, then include in your server block:
+Replace the certificate paths with yours, then include the snippet in your `server {}` block:
 
 ```nginx
 server {
 	# ...
 	include snippets/cert/mydomain.com.conf;
+	include kit/security.conf;
 	include kit/ssl/security.conf;
 	include kit/ssl/hsts.conf;
 	# ...
 }
 ```
 
-### SSL snippets
+## Snippet reference
 
-- `kit/ssl/security.conf`: TLS protocol and session resumption settings.
+- `kit/http/websocket-map.conf`: defines `$connection_upgrade` for websocket proxying. Must be included inside `http {}`.
-- `kit/ssl/hsts.conf`: HSTS header for HTTPS responses.
+- `kit/security.conf`: common security headers and host normalization. Intended for `server {}`.
-- `kit/ssl/force.conf`: Redirect HTTP requests to HTTPS.
+- `kit/ssl/security.conf`: TLS protocol and session resumption settings. Intended for `server {}`.
+- `kit/ssl/hsts.conf`: HSTS header for HTTPS responses. Intended for `server {}`.
+- `kit/ssl/hsts-preload.conf`: HSTS variant with `preload`. Use only if the whole domain tree is preload-safe.
+- `kit/ssl/force.conf`: redirects HTTP requests to HTTPS. Intended for `server {}`.
+- `kit/redirect/to-primary-domain.conf`: redirects aliases to the primary `server_name`. Intended for `server {}`.
+- `kit/proxy_pass/forwarded.conf`: standard reverse proxy headers. Intended for `location {}`.
+- `kit/proxy_pass/websocket.conf`: websocket upgrade headers. Requires `kit/http/websocket-map.conf`.
+- `kit/proxy_pass/timeout-300.conf`: longer proxy timeouts. Intended for `location {}`.
+
+## Validation
+
+Run the Docker-based syntax checks from the repo root:
+
+```powershell
+./scripts/validate-docker.ps1
+```
+
+The script validates:
+
+- [examples/example.com.conf](examples/example.com.conf:1) as a server-level snippet.
+- [examples/reverse-proxy.nginx.conf](examples/reverse-proxy.nginx.conf:1) as a complete nginx config.

scripts/validate-docker.ps1

@@ -0,0 +1,41 @@
+param(
+	[string]$Image = "nginx:alpine"
+)
+
+$ErrorActionPreference = "Stop"
+
+$repoRoot = Split-Path -Parent $PSScriptRoot
+
+$serverSnippetConfig = @(
+	"events {}"
+	""
+	"http {"
+	"	include /etc/nginx/mime.types;"
+	"	default_type application/octet-stream;"
+	""
+	"	include /etc/nginx/kit/http/websocket-map.conf;"
+	""
+	"	include /etc/nginx/kit/examples/example.com.conf;"
+	"}"
+) -join "\n"
+
+$serverSnippetConfigShell = $serverSnippetConfig -replace "\\", "\\\\" -replace "'", "'\"'\"'" -replace "`n", "\\n"
+
+$containerCommand = @(
+	"set -eu"
+	"apk add --no-cache openssl >/dev/null"
+	"mkdir -p /etc/nginx/snippets/cert /etc/ssl/certimate /tmp/nginx-kit/snippets/cert"
+	"openssl req -x509 -nodes -newkey rsa:2048 -keyout /etc/ssl/certimate/example.com.key -out /etc/ssl/certimate/example.com.crt -subj '/CN=example.com' -days 1 >/dev/null 2>&1"
+	"cp /etc/nginx/kit/templates/cert/example.com.conf /etc/nginx/snippets/cert/mydomain.com.conf"
+	"cp /etc/nginx/kit/templates/cert/example.com.conf /tmp/nginx-kit/snippets/cert/mydomain.com.conf"
+	"ln -s /etc/nginx/kit /tmp/nginx-kit/kit"
+	"printf '%b' '$serverSnippetConfigShell' > /tmp/nginx-kit/server-snippet.nginx.conf"
+	"echo 'Validating examples/example.com.conf'"
+	"nginx -t -c /tmp/nginx-kit/server-snippet.nginx.conf"
+	"echo 'Validating examples/reverse-proxy.nginx.conf'"
+	"nginx -t -c /etc/nginx/kit/examples/reverse-proxy.nginx.conf"
+) -join "; "
+
+docker run --rm `
+	-v "${repoRoot}:/etc/nginx/kit:ro" `
+	$Image sh -lc $containerCommand