# Nginx Kit

## Start

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

### Update

```bash
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 {}`.
- `fastcgi/`: FastCGI-specific snippets for `location {}` or `server {}` blocks.
- `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/security.conf;
	include kit/ssl/security.conf;
	include kit/ssl/hsts.conf;
	include kit/ssl/force.conf;
	# ...
}
```

See [examples/example.com.conf](examples/example.com.conf:1) for the full server-level example.

### Optional `http {}` features

These snippets are independent `http {}`-level features:

```nginx
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.

```nginx
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:

```nginx
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:

```nginx
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](examples/reverse-proxy.nginx.conf:1) for a complete standalone config.

## Templates

### SSL certs

```bash
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:

```nginx
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 low-risk security headers and host normalization. Intended for `server {}`.
- `kit/security-legacy.conf`: optional legacy compatibility headers such as `X-Download-Options` and `X-Permitted-Cross-Domain-Policies`.
- `kit/fastcgi/hide-powered-by.conf`: hides `X-Powered-By` from FastCGI upstream responses.
- `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/hide-powered-by.conf`: hides `X-Powered-By` from proxied upstream responses.
- `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.

## 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.
- `kit/security.conf` intentionally does not set `X-Robots-Tag: none` or `X-XSS-Protection: 1; mode=block`; those are too risky or too obsolete for a default site-wide baseline.