From cb97070442c85ab8c70555eb7c68cd6f65bb6d6c Mon Sep 17 00:00:00 2001 From: dallaslu Date: Fri, 5 Jun 2026 13:01:07 +0800 Subject: [PATCH] update --- README.md | 91 +++++++++++++++++++++++++++++++------ scripts/validate-docker.ps1 | 41 +++++++++++++++++ 2 files changed, 119 insertions(+), 13 deletions(-) create mode 100644 scripts/validate-docker.ps1 diff --git a/README.md b/README.md index 3573bce..5c7d3fb 100644 --- a/README.md +++ b/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. diff --git a/scripts/validate-docker.ps1 b/scripts/validate-docker.ps1 new file mode 100644 index 0000000..bfff763 --- /dev/null +++ b/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