Nginx Kit

Start

git clone https://git.forge.st/ops/nginx-kit.git /opt/nginx-kit
ln -s /opt/nginx-kit /etc/nginx/kit

Update

cd /opt/nginx-kit
git pull
nginx -t
systemctl reload nginx

Contexts

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:

server {
	# ...
	include snippets/cert/mydomain.com.conf;
	include kit/security.conf;
	include kit/ssl/security.conf;
	include kit/ssl/hsts.conf;
	include kit/ssl/force.conf;
	# ...
}

See examples/example.com.conf for the full server-level example.

Reverse proxy with websocket support

Websocket proxying needs one http {}-level map plus location {}-level proxy snippets:

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 for a complete standalone config.

Templates

SSL certs

cd /etc/nginx
mkdir -p snippets/cert
cp kit/templates/cert/example.com.conf snippets/cert/mydomain.com.conf
vi snippets/cert/mydomain.com.conf

Replace the certificate paths with yours, then include the snippet in your server {} block:

server {
	# ...
	include snippets/cert/mydomain.com.conf;
	include kit/security.conf;
	include kit/ssl/security.conf;
	include kit/ssl/hsts.conf;
	# ...
}

Snippet reference

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:

./scripts/validate-docker.ps1

The script validates:

examples/example.com.conf as a server-level snippet.
examples/reverse-proxy.nginx.conf as a complete nginx config.

3.4 KiB Raw Blame History