nginx-config-generator

# nginx-config-generator

Generate complete, validated nginx configuration files from a questionnaire or CLI flags.

## When to Use

- Setting up nginx for a new web application
- Adding SSL/TLS to an existing nginx server
- Configuring nginx as a reverse proxy for Node.js, Python, PHP, or Go apps
- Adding rate limiting or caching to protect a backend
- Creating a multi-server virtual host configuration
- Getting a starting point nginx config to customize

## Prerequisites

1. nginx-config-generator installed or running locally
2. (Optional) nginx binary installed for full config validation

## Installation

```bash
npm install -g nginx-config-generator
```

Or run the web UI:

```bash
docker compose up -d
# Web UI at http://localhost:3000
```

## Quick Start

### CLI - Generate with flags

```bash
nginx-conf generate \
  --domain example.com \
  --upstream 127.0.0.1:3000 \
  --ssl \
  --cert /etc/letsencrypt/live/example.com/fullchain.pem \
  --key /etc/letsencrypt/live/example.com/privkey.pem \
  --rate-limit \
  --gzip \
  --output nginx.conf
```

### CLI - Apply a preset template

```bash
nginx-conf templates apply nextjs \
  --domain example.com \
  --upstream 127.0.0.1:3000 \
  --output nginx.conf
```

### CLI - Interactive mode

```bash
nginx-conf generate
# Walks through all 4 steps interactively
```

### CLI - From saved answers

```bash
nginx-conf generate --from answers.json --output nginx.conf
```

## CLI Reference

| Command | Description |
|---|---|
| `nginx-conf generate` | Interactive questionnaire |
| `nginx-conf generate [flags]` | Generate from flags |
| `nginx-conf generate --from <file>` | Load answers from JSON |
| `nginx-conf validate <file>` | Validate an nginx config |
| `nginx-conf templates` | List available templates |
| `nginx-conf templates apply <name>` | Generate from preset |
| `nginx-conf --help` | Show help |
| `nginx-conf --version` | Show version |

## Generate Flags

| Flag | Description | Default |
|---|---|---|
| `--domain <name>` | Server name(s), space-separated | (required) |
| `--upstream <addr>` | Upstream server address | - |
| `--ssl` | Enable SSL | 0 |
| `--cert <path>` | SSL certificate path | - |
| `--key <path>` | SSL key path | - |
| `--redirect-http` | 301 redirect HTTP to HTTPS | 1 (if --ssl) |
| `--hsts` | Strict-Transport-Security header | 0 |
| `--cipher-profile <name>` | modern, intermediate, or custom | intermediate |
| `--rate-limit` | Enable rate limiting | 0 |
| `--rate <n>` | Request rate (e.g. 10r/s) | 10r/s |
| `--burst <n>` | Rate limit burst | 20 |
| `--cache` | Enable proxy cache | 0 |
| `--gzip` | Enable gzip compression | 1 |
| `--max-body <size>` | Max upload size (e.g. 10m) | 10m |
| `--load-balancing <method>` | round-robin, least-conn, ip-hash | round-robin |
| `--websocket` | WebSocket upgrade headers | 0 |
| `--output <file>` | Output file path | nginx.conf |
| `--validate` | Run nginx -t after generation | 0 |
| `--preset <name>` | Start from a template preset | - |

## Environment Variables

| Variable | Description | Default |
|---|---|---|
| `PORT` | Web server port | 3000 |
| `NODE_ENV` | development or production | development |
| `NGINX_BINARY` | Path to nginx binary | nginx (from PATH) |
| `CONFIG_TTL_MINUTES` | How long generated configs are held | 10 |
| `ENABLE_VALIDATION` | Enable nginx -t validation | 1 |
| `MAX_CONFIG_SIZE_KB` | Maximum generated config size | 512 |

## Available Presets

| Preset | Description |
|---|---|
| `wordpress` | WordPress + PHP-FPM with permalink rewriting |
| `nextjs` | Next.js with static asset caching |
| `spa` | React/Vue/Angular SPA with HTML5 history routing |
| `api-gateway` | Rate-limited REST API reverse proxy |
| `static` | Static site with gzip and browser caching |
| `laravel` | Laravel + PHP-FPM |
| `django` | Django + Gunicorn via UNIX socket |
| `go-app` | Go binary upstream with health checks |

## API (when running as a server)

```
POST /api/generate        # Generate config from answers JSON
POST /api/validate        # Validate a config string
GET  /api/templates       # List all presets
GET  /api/templates/:id/generate  # Generate from preset
GET  /api/download/:id    # Download a generated config file
```

## Validation

When nginx is available on PATH, `nginx -t` is used for validation. Otherwise, a structural validator checks:

- Balanced braces
- Required directives (`server`, `listen`, `server_name`)
- No obviously invalid directive names

To validate after generating:

```bash
nginx-conf validate nginx.conf
```

Or validate any existing config:

```bash
nginx-conf validate /etc/nginx/nginx.conf
```

## Troubleshooting

### "nginx not found on PATH"

The CLI uses a structural fallback validator. For full validation, install nginx:

```bash
# Ubuntu/Debian
apt install nginx

# macOS
brew install nginx
```

### "directive X is not allowed in context"

nginx directives are context-sensitive. Some directives only work in the http block, others in server or location. The generated configs use correct contexts. If you edited the config manually, check the nginx documentation for that directive.

### "worker_connections is below recommended"

For production, set `worker_connections` to at least 1024 per worker. For high-traffic sites, 4096 or higher. The default is conservative for compatibility.

### Generated config fails nginx -t

If the generated config fails validation, check:
1. SSL certificate and key paths exist on the server
2. Upstream server addresses are reachable
3. No conflicting server blocks with the same `listen` + `server_name` combination