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.

Optional http {} features

These snippets are independent http {}-level features:

http {
	include kit/http/gzip.conf;
}

Use kit/http/gzip.conf when you want nginx to compress common text-based responses. It is not specific to proxying or websocket traffic.

http {
	include kit/http/websocket-map.conf;
}

Use kit/http/websocket-map.conf only when a location {} will include kit/proxy_pass/websocket.conf.

Reverse proxy

Plain HTTP reverse proxying only needs the location {}-level proxy snippets:

server {
	# ...
	location / {
		include kit/proxy_pass/forwarded.conf;
		include kit/proxy_pass/timeout-300.conf;
		proxy_pass http://app_backend;
	}
}

Websocket reverse proxy

Websocket proxying adds one http {}-level dependency plus the websocket location snippet:

http {
	include kit/http/websocket-map.conf;

	server {
		# ...
		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/gzip.conf: gzip compression for common text-based responses. Must be included inside http {}.
• 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.

Notes

• gzip_proxied does not remove ETag or Last-Modified headers. It only controls when nginx may gzip requests that arrived through another proxy.
• text/html does not need to appear in gzip_types; nginx compresses it automatically.
• Gzip over HTTPS can contribute to BREACH-style risk for responses that reflect attacker-controlled input alongside secrets. Keep that in mind for highly sensitive dynamic pages.