Skip to main content
The bench setup nginx command generates an NGINX configuration file for serving your Frappe sites.

​
Usage

bench setup nginx [OPTIONS]

​
Options

​
--logging
choice
default:"combined"
NGINX access log configuration.Choices:
  • none: Disable access logging
  • site: Separate log file per site
  • combined: Single combined log file for all sites
​
--log_format
string
default:"main"
Specify the log format for NGINX access logs.Use none or empty string to not set a value.Only applies when --logging is not none.
​
--yes
flag
Automatically overwrite existing nginx.conf without confirmation.

​
Examples

​
Basic Configuration

Generate NGINX configuration with defaults: 
bench setup nginx

​
Disable Logging

Generate configuration without access logs: 
bench setup nginx --logging none

​
Per-Site Logging

Create separate log files for each site: 
bench setup nginx --logging site

​
Custom Log Format

Use a custom NGINX log format: 
bench setup nginx --logging combined --log_format custom_format

​
Skip Confirmation

Overwrite existing configuration without prompting: 
bench setup nginx --yes

​
Generated Configuration

​
File Location

frappe-bench/config/nginx.conf

​
Configuration Structure

The generated NGINX configuration includes:
  • Upstream blocks: For Frappe web and socketio servers
  • Server blocks: For each site
  • Rate limiting: If enabled in bench config
  • SSL configuration: If SSL certificates are configured
  • Static file serving: For assets
  • Proxy settings: For dynamic requests

​
Configuration Types

​
Port-Based (Default)

When dns_multitenant is false, each site gets its own port: 
server {
    listen 80;
    server_name site1.local;
    # ...
}

server {
    listen 8001;
    server_name site2.local;
    # ...
}

​
DNS-Based (Multi-Tenant)

When dns_multitenant is true, all sites use port 80/443: 
server {
    listen 80;
    server_name site1.com;
    # ...
}

server {
    listen 80;
    server_name site2.com;
    # ...
}

​
Production Setup

After generating the NGINX configuration, you need to create a symlink in the NGINX configuration directory and reload NGINX.
sudo ln -s ~/frappe-bench/config/nginx.conf /etc/nginx/conf.d/frappe-bench.conf

​
Test Configuration

Always test before reloading: 
sudo nginx -t

​
Reload NGINX

Apply the new configuration: 
sudo systemctl reload nginx
Or use the bench command: 
bench setup reload-nginx

​
Rate Limiting

Enable rate limiting in common_site_config.json: 
{
  "allow_rate_limiting": true
}
This adds NGINX rate limiting directives to prevent abuse.

​
SSL Configuration

The NGINX configuration automatically includes SSL settings if certificates are configured: 
// sites/site1.local/site_config.json
{
  "ssl_certificate": "/path/to/cert.pem",
  "ssl_certificate_key": "/path/to/key.pem"
}
Or use Let’s Encrypt: 
sudo bench setup lets-encrypt site1.local

​
Logging

​
Log Locations

Combined logging (default): 
/var/log/nginx/frappe-bench.access.log
/var/log/nginx/frappe-bench.error.log
Per-site logging: 
/var/log/nginx/site1.local.access.log
/var/log/nginx/site1.local.error.log

​
View Logs

# Access log
tail -f /var/log/nginx/frappe-bench.access.log

# Error log
tail -f /var/log/nginx/frappe-bench.error.log

​
Advanced Configuration

​
Custom Timeout

Set HTTP timeout in common_site_config.json: 
{
  "http_timeout": 300
}
Then regenerate: 
bench setup nginx --yes

​
Custom Ports

Change webserver and socketio ports: 
{
  "webserver_port": 8000,
  "socketio_port": 9000
}

​
Wildcard SSL

For wildcard SSL certificates: 
{
  "wildcard": {
    "domain": "*.example.com",
    "ssl_certificate": "/path/to/wildcard-cert.pem",
    "ssl_certificate_key": "/path/to/wildcard-key.pem"
  }
}

​
Troubleshooting

​
Port Conflicts

If you see “Port already in use” errors: 
# Check what's using the port
sudo lsof -i :80

# Change port in config
nano sites/common_site_config.json

# Regenerate NGINX config
bench setup nginx --yes

​
Configuration Test Failed

If nginx -t fails: 
# Check for syntax errors
sudo nginx -t

# Review generated config
cat config/nginx.conf

# Check site configs
ls sites/*/site_config.json

# Regenerate
bench setup nginx --yes
sudo nginx -t

​
Sites Not Accessible

  1. Verify NGINX is running: 
    sudo systemctl status nginx
  2. Check bench processes: 
    bench start  # or
sudo supervisorctl status
  3. Test upstream connection: 
    curl http://localhost:8000
  4. Check firewall: 
    sudo ufw status

​
When to Regenerate

Regenerate NGINX configuration after:
  • Adding or removing sites
  • Changing site domains
  • Adding SSL certificates
  • Modifying timeout settings
  • Changing ports
  • Enabling/disabling rate limiting

​
Source Code

Implementation: bench/config/nginx.py:17 Command definition: bench/commands/setup.py:28

Build docs developers (and LLMs) love

Get started for freeTalk to us