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.