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/ssl/hsts.conf;
-	include	kit/ssl/force.conf;
+	include kit/security.conf;
+	include kit/ssl/security.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/ssl/hsts.conf`: HSTS header for HTTPS responses.
-- `kit/ssl/force.conf`: Redirect HTTP requests to HTTPS.
+- `kit/http/websocket-map.conf`: defines `$connection_upgrade` for websocket proxying. Must be included inside `http {}`.
+- `kit/security.conf`: common security headers and host normalization. Intended for `server {}`.
+- `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.