nginx-gen

Generate nginx reverse proxy site configs and nginx.conf from the command line.

nginx-gen --name app.example.com --proxy 127.0.0.1:3000

Outputs a ready-to-use nginx server {} block with SSL, proxy headers, and optional extras (WebSocket, HTTP→HTTPS redirect, IPv6, HSTS, Cloudflare log format, per-site logging, block-exploits snippet).

Install

npm install -g @minus30db/nginx-gen

Requires Node.js ≥ 18. The server running nginx needs Let's Encrypt certificates at the standard certbot paths (/etc/letsencrypt/live/<domain>/).

Quick start

Generate a site config

# Basic HTTPS reverse proxy → stdout
nginx-gen --name app.example.com --proxy 127.0.0.1:3000

# Write directly to sites-available
nginx-gen --name app.example.com --proxy 127.0.0.1:3000 \
  | sudo tee /etc/nginx/sites-available/app.example.com > /dev/null

# With WebSocket endpoint and HTTP→HTTPS redirect
nginx-gen --name app.example.com \
  --proxy 127.0.0.1:3000 \
  --ws-location /ws=127.0.0.1:3001 \
  --http-listen --force-ssl \
  | sudo tee /etc/nginx/sites-available/app.example.com > /dev/null

Generate nginx.conf

nginx-gen nginx-conf | sudo tee /etc/nginx/nginx.conf > /dev/null

Scaffold shared snippet files

nginx-gen init          # writes templates/, conf.d/include/, nginx-gen.config.json

Then copy conf.d/include/ to /etc/nginx/conf.d/include/ — these are referenced by every generated site config.

Site config flags

| Flag | Short | Description | |------|-------|-------------| | --name <domain> | -n | Server name / domain (required) | | --proxy <host:port> | -p | Primary upstream for / (required) | | --location <path=host:port> | -l | Extra location block (repeatable) | | --ws-location <path=host:port> | -w | WebSocket location block (repeatable) | | --scheme <http\|https> | | Upstream scheme (default: http) | | --http-listen | -h | Also listen on port 80 | | --ipv6 | | Add IPv6 listen directives | | --force-ssl | -f | Redirect port 80 → 443 (requires --http-listen) | | --no-block-exploits | | Omit block-exploits snippet | | --hsts / --no-hsts | | HSTS header max-age=31536000 (default: on) | | --cf-logs / --no-cf-logs | | Cloudflare log format: logs $remote_addr (CF edge IP) + $http_cf_connecting_ip (real visitor IP); requires log_format cloudflare in nginx.conf (default: off) | | --site-logs | | Per-site logs at /var/log/nginx/sites/<domain>/ | | --access-log <path> | | Custom access log path (implies --site-logs) | | --error-log <path> | | Custom error log path (implies --site-logs) | | --output-file <path> | -o | Write to file instead of stdout | | --interactive | -i | Use interactive wizard |

Multiple locations

nginx-gen --name app.example.com \
  --proxy 127.0.0.1:3000 \
  --location /api=127.0.0.1:3001 \
  --location /admin=127.0.0.1:3002 \
  --ws-location /ws=127.0.0.1:3003

nginx-conf flags

nginx-gen nginx-conf [options]

| Flag | Description | Default | |------|-------------|---------| | --worker-connections <n> | worker_connections value | 768 | | --client-max-body-size <size> | client_max_body_size value | 500m | | --no-gzip | Disable gzip | — | | --cf-logs / --no-cf-logs | Add log_format cloudflare block (default: off) | — | | --output-file <path> | Write to file | stdout | | --interactive | Use interactive wizard | — |

Shell completion

# bash — add to ~/.bashrc
eval "$(nginx-gen completion bash)"

# zsh — add to ~/.zshrc
eval "$(nginx-gen completion zsh)"

# fish — add to ~/.config/fish/config.fish
nginx-gen completion fish | source

Or write to a file for faster shell startup:

nginx-gen completion bash > ~/.bash_completion.d/nginx-gen

Configuration

Running nginx-gen init scaffolds a nginx-gen.config.json in the current directory. CLI flags always override config file values.

{
  "templatesDir": "./templates",
  "includesDir": "conf.d/include",
  "scheme": "http",
  "blockExploits": true,
  "hsts": true,
  "cfLogs": false
}

nginx-gen looks for nginx-gen.config.json in process.cwd() — useful when managing configs for multiple servers from a single directory.

Server deployment

See DEPLOYMENT.md for a full walkthrough: server directory layout, one-time setup, adding/updating/removing sites, certbot, and remote deployment over SSH.

License

MIT