Configuration Files

Overview

Bench uses several configuration files to manage its environment, sites, and services. Understanding these files helps you customize your bench setup and troubleshoot configuration issues.

Configuration File Hierarchy

frappe-bench/
├── sites/
│   ├── common_site_config.json    # Bench-wide configuration
│   ├── [site-name]/
│   │   └── site_config.json        # Site-specific configuration
│   ├── apps.txt                    # List of installed apps
│   └── currentsite.txt             # Default site for commands
├── config/
│   ├── pids/                       # Process ID files
│   ├── redis_cache.conf            # Redis cache configuration
│   ├── redis_queue.conf            # Redis queue configuration
│   ├── supervisor.conf             # Supervisor configuration (production)
│   └── nginx.conf                  # NGINX configuration (production)
├── Procfile                        # Development process definitions
└── patches.txt                     # Applied patches tracking

common_site_config.json

The main configuration file for the entire bench instance. Located at sites/common_site_config.json.

Structure

{
  "auto_update": false,
  "background_workers": 1,
  "file_watcher_port": 6787,
  "frappe_user": "frappe",
  "gunicorn_workers": 9,
  "live_reload": true,
  "rebase_on_pull": false,
  "redis_cache": "redis://127.0.0.1:13000",
  "redis_queue": "redis://127.0.0.1:11000",
  "redis_socketio": "redis://127.0.0.1:13000",
  "restart_supervisor_on_update": false,
  "restart_systemd_on_update": false,
  "serve_default_site": true,
  "shallow_clone": true,
  "socketio_port": 9000,
  "use_redis_auth": false,
  "webserver_port": 8000
}

Configuration Options

Core Settings

frappe_user

Type: string
Default: Current user
Description: System user that runs bench processes

serve_default_site

Type: boolean
Default: true
Description: Whether to serve a default site on the root domain

shallow_clone

Type: boolean
Default: true
Description: Use shallow git clones to save space (git 1.9+)

Web Server Settings

webserver_port

Type: integer
Default: 8000
Description: Port for the development web server

socketio_port

Type: integer
Default: 9000
Description: Port for Socket.IO server (real-time connections)

file_watcher_port

Type: integer
Default: 6787
Description: Port for file watcher (auto-reload in development)

gunicorn_workers

Type: integer
Default: (CPU cores × 2) + 1
Description: Number of Gunicorn worker processes in production

Redis Configuration

redis_cache

Type: string
Default: redis://127.0.0.1:13000
Description: Redis URL for caching layer
Format: redis://[host]:[port]/[db]

redis_queue

Type: string
Default: redis://127.0.0.1:11000
Description: Redis URL for background job queue

redis_socketio

Type: string
Default: redis://127.0.0.1:13000
Description: Redis URL for Socket.IO pub/sub

use_redis_auth

Type: boolean
Default: false
Description: Enable Redis authentication

Worker Settings

background_workers

Type: integer
Default: 1
Description: Number of background worker processes

workers

Type: object
Description: Detailed worker configuration per queue

Example:

{
  "workers": {
    "short": 2,
    "long": 1,
    "default": 1
  }
}

Update and Deployment

restart_supervisor_on_update

Type: boolean
Default: false
Description: Auto-restart Supervisor processes after bench update

restart_systemd_on_update

Type: boolean
Default: false
Description: Auto-restart systemd services after bench update

auto_update

Type: boolean
Default: false
Description: Enable automatic updates

rebase_on_pull

Type: boolean
Default: false
Description: Use rebase instead of merge when pulling updates

Development Settings

live_reload

Type: boolean
Default: true
Description: Enable live reload during development

developer_mode

Type: boolean
Default: false
Description: Enable developer mode features

Database Settings

db_host

Type: string
Default: 127.0.0.1 (or localhost)
Description: MariaDB/MySQL host

db_port

Type: integer
Default: 3306
Description: MariaDB/MySQL port

db_name

Type: string
Description: Database name (usually in site_config.json)

db_type

Type: string
Default: mariadb
Options: mariadb, postgres

Multi-tenancy

dns_multitenant

Type: boolean
Default: false
Description: Enable DNS-based multi-tenancy

wildcard_ssl_certificate

Type: string
Description: Path to wildcard SSL certificate

wildcard_ssl_key

Type: string
Description: Path to wildcard SSL certificate key

Example Configurations

Development:

{
  "background_workers": 1,
  "developer_mode": true,
  "live_reload": true,
  "webserver_port": 8000,
  "redis_cache": "redis://127.0.0.1:13000",
  "redis_queue": "redis://127.0.0.1:11000"
}

Production:

{
  "background_workers": 4,
  "gunicorn_workers": 17,
  "live_reload": false,
  "restart_supervisor_on_update": true,
  "redis_cache": "redis://127.0.0.1:13000",
  "redis_queue": "redis://127.0.0.1:11000",
  "serve_default_site": true,
  "use_redis_auth": true
}

Location: bench/config/common_site_config.py:6

site_config.json

Site-specific configuration file. Located at sites/[site-name]/site_config.json.

Structure

{
  "db_name": "site1_db",
  "db_password": "secret_password",
  "db_type": "mariadb",
  "encryption_key": "random_encryption_key",
  "host_name": "https://site1.example.com",
  "developer_mode": 0,
  "maintenance_mode": 0,
  "limits": {
    "space_usage": {
      "database_size": 500,
      "files_size": 1000,
      "backup_size": 500
    }
  }
}

Configuration Options

Database Configuration

db_name

Type: string
Description: Database name for this site
Example: site1_db

db_password

Type: string
Description: Database password
Security: Keep this secure, don’t commit to version control

db_type

Type: string
Default: mariadb
Options: mariadb, postgres

Site Identity

host_name

Type: string
Description: Primary URL for the site
Example: https://example.com

site_name

Type: string
Description: Site name (usually matches folder name)

Security

encryption_key

Type: string
Description: Key for encrypting sensitive data
Security: Randomly generated, keep secure

admin_password

Type: string
Description: Administrator password hash (set during creation)

Site Settings

developer_mode

Type: integer (0 or 1)
Default: 0
Description: Enable developer mode for this site

maintenance_mode

Type: integer (0 or 1)
Default: 0
Description: Enable maintenance mode (site inaccessible)

disable_website_cache

Type: boolean
Default: false
Description: Disable website caching

Limits and Quotas

limits

Type: object
Description: Resource limits for the site

Example:

{
  "limits": {
    "space_usage": {
      "database_size": 500,
      "files_size": 1000,
      "backup_size": 500
    }
  }
}

Site-Specific Overrides

Settings in site_config.json override those in common_site_config.json for that specific site. Example:

{
  "db_name": "mysite_db",
  "db_password": "secure_password",
  "developer_mode": 1,
  "redis_cache": "redis://127.0.0.1:6379/2"
}

Never commit site_config.json files to version control as they contain sensitive information like database passwords and encryption keys.

Procfile

Defines processes for development mode. Located at Procfile in bench root.

Structure

redis_cache: redis-server config/redis_cache.conf
redis_queue: redis-server config/redis_queue.conf
web: bench serve --port 8000
socketio: /usr/bin/node apps/frappe/socketio.js
watch: bench watch
schedule: bench schedule
worker_short: bench worker --queue short
worker_long: bench worker --queue long
worker_default: bench worker --queue default

Process Types

Essential
Workers
Utilities

redis_cache

Starts Redis instance for caching
Config: config/redis_cache.conf

redis_queue

Starts Redis instance for job queue
Config: config/redis_queue.conf

web

Starts development web server (Werkzeug)
Default port: 8000

socketio

Starts Socket.IO server for real-time features
Uses Node.js

worker_short

Processes short-running background jobs
Queue: short

worker_long

Processes long-running background jobs
Queue: long

worker_default

Processes default priority jobs
Queue: default

Customization

You can customize the Procfile by regenerating it:

bench setup procfile

Or edit it directly for custom configurations. Location: bench/config/procfile.py:11

supervisor.conf

Configuration for Supervisor process manager (production). Located at config/supervisor.conf.

Structure

[group:frappe-bench-web]
programs=frappe-bench-web

[program:frappe-bench-web]
command=/home/frappe/frappe-bench/env/bin/gunicorn -b 127.0.0.1:8000 -w 9 --max-requests 5000 --max-requests-jitter 500 -t 120 frappe.app:application --preload
priority=4
autostart=true
autorestart=true
stdout_logfile=/home/frappe/frappe-bench/logs/web.log
stderr_logfile=/home/frappe/frappe-bench/logs/web.error.log
user=frappe
directory=/home/frappe/frappe-bench/sites

[group:frappe-bench-workers]
programs=frappe-bench-worker-short,frappe-bench-worker-long,frappe-bench-worker-default

[program:frappe-bench-worker-short]
command=/home/frappe/frappe-bench/env/bin/bench worker --queue short
priority=4
autostart=true
autorestart=true
stdout_logfile=/home/frappe/frappe-bench/logs/worker-short.log
stderr_logfile=/home/frappe/frappe-bench/logs/worker-short.error.log
user=frappe
directory=/home/frappe/frappe-bench/sites

# ... similar entries for other workers and processes

Process Groups

Web Workers

frappe-bench-web

Gunicorn web workers
Handles HTTP requests
Number of workers: (CPU cores × 2) + 1

Background Workers

frappe-bench-workers

Short, long, and default queue workers
Process background jobs
Each queue has separate workers

Services

frappe-bench-redis

Redis instances for cache, queue, and socketio

frappe-bench-schedule

Scheduler for periodic tasks

Generated Configuration

This file is auto-generated by:

bench setup supervisor

Options:

--user - User to run processes as
--yes - Skip confirmation
--skip-redis - Skip Redis configuration

Don’t edit this file manually. Regenerate it using bench setup supervisor to ensure consistency.

Location: bench/config/supervisor.py

nginx.conf

NGINX configuration for production web server. Located at config/nginx.conf.

Structure

upstream frappe-bench-frappe {
    server 127.0.0.1:8000 fail_timeout=0;
}

server {
    listen 80;
    server_name site1.local site2.local;
    
    root /home/frappe/frappe-bench/sites;
    
    location /assets {
        try_files $uri =404;
    }
    
    location ~ ^/protected/(.*) {
        internal;
        try_files /site1.local/$1 =404;
    }
    
    location /socket.io {
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header X-Frappe-Site-Name site1.local;
        proxy_set_header Origin $scheme://$http_host;
        proxy_set_header Host $host;
        proxy_pass http://127.0.0.1:9000;
    }
    
    location / {
        try_files /site1.local/public/$uri @webserver;
    }
    
    location @webserver {
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Frappe-Site-Name site1.local;
        proxy_set_header Host $host;
        proxy_set_header X-Use-X-Accel-Redirect True;
        proxy_read_timeout 120;
        proxy_redirect off;
        
        proxy_pass http://frappe-bench-frappe;
    }
}

Key Sections

Upstream Definition

Defines backend Gunicorn server:

upstream frappe-bench-frappe {
    server 127.0.0.1:8000 fail_timeout=0;
}

Static Assets

Serves compiled static files directly:

location /assets {
    try_files $uri =404;
}

Protected Files

Handles X-Accel-Redirect for file downloads:

location ~ ^/protected/(.*) {
    internal;
    try_files /$frappe_site_name/$1 =404;
}

Socket.IO Proxy

Proxies WebSocket connections:

location /socket.io {
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_pass http://127.0.0.1:9000;
}

Application Proxy

Proxies requests to Gunicorn:

location @webserver {
    proxy_pass http://frappe-bench-frappe;
}

SSL Configuration

With SSL enabled:

server {
    listen 443 ssl http2;
    server_name site1.local;
    
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    ssl_session_timeout 5m;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;
    ssl_prefer_server_ciphers on;
    
    # ... rest of configuration
}

server {
    listen 80;
    server_name site1.local;
    return 301 https://$host$request_uri;
}

Generated Configuration

Generate NGINX config:

bench setup nginx

Options:

--yes - Skip confirmation
--logging - Logging type: none, site, or combined

Location: bench/config/nginx.py

Redis Configuration Files

redis_cache.conf

Redis configuration for caching. Located at config/redis_cache.conf.

port 13000
dir /home/frappe/frappe-bench/config/pids
dbfilename redis_cache.rdb
save ""
appendonly no

redis_queue.conf

Redis configuration for job queue. Located at config/redis_queue.conf.

port 11000
dir /home/frappe/frappe-bench/config/pids
dbfilename redis_queue.rdb
save ""
appendonly yes
appendfilename "redis_queue.aof"

Key Differences

Setting	redis_cache	redis_queue
Port	13000	11000
Persistence	None (`save ""`)	AOF enabled
Purpose	Volatile cache	Durable queue

Generate Redis configs:

bench setup redis

Location: bench/config/redis.py

Supporting Files

apps.txt

List of installed apps in order. Located at sites/apps.txt.

frappe
erpnext
custom_app

Order matters: Apps are loaded in the order listed.

currentsite.txt

Default site for CLI commands. Located at sites/currentsite.txt.

site1.local

Commands like bench console use this site if --site is not specified.

patches.txt

Tracks applied patches. Located at patches.txt in bench root.

frappe.patches.v13_0.update_encrypted_fields
erpnext.patches.v13_0.setup_fields_for_80g_certificate
custom_app.patches.v1_0.initial_setup

This file is managed by Frappe’s migration system. Don’t edit it manually.

Configuration Management

Viewing Configuration

# View common site config
cat sites/common_site_config.json

# View site config
cat sites/site1.local/site_config.json

# View with bench
bench config set-common-config

Updating Configuration

Via bench commands:

bench config set-common-config -c key value
bench set-redis-cache-host localhost:6379/1
bench set-mariadb-host localhost

Manually:

# Edit common config
nano sites/common_site_config.json

# Edit site config
nano sites/site1.local/site_config.json

Regenerating Configs

# Regenerate all production configs
bench setup production

# Individual configs
bench setup nginx
bench setup supervisor
bench setup redis
bench setup procfile

Configuration Best Practices

Version Control

Do commit:

common_site_config.json (with sensitive values removed)
Procfile
Custom configuration templates

Never commit:

site_config.json (contains passwords)
Generated nginx.conf, supervisor.conf
Redis dump files

Security

Use strong, random encryption keys
Enable Redis authentication in production
Use HTTPS in production
Restrict file permissions:
```
chmod 600 sites/*/site_config.json
```

Performance

Adjust gunicorn_workers based on traffic
Configure appropriate background_workers
Use Redis auth only if needed (slight overhead)
Enable live_reload only in development

Maintenance

Document custom configuration changes
Regenerate configs after bench updates
Backup configuration files before changes
Test configuration changes in staging first

Troubleshooting

Configuration Not Applied

Verify file syntax (valid JSON/INI/NGINX)

Restart services:

bench restart
# or
sudo supervisorctl reload

Check file permissions
Review logs for errors

Config File Conflicts

Site config overrides bench config. Check both:

cat sites/common_site_config.json
cat sites/site1.local/site_config.json

Regeneration Issues

If regenerating configs fails:

# Backup current configs
cp config/nginx.conf config/nginx.conf.bak

# Regenerate with --yes flag
bench setup nginx --yes
bench setup supervisor --yes

Environment Variables

Environment variables used by bench

Architecture

How bench components work together

Production Setup

Setting up production environment

All Commands

Complete command reference

Command Reference

​Overview

​Configuration File Hierarchy

​common_site_config.json

​Structure

​Configuration Options

​Example Configurations

​site_config.json

​Structure

​Configuration Options

​Site-Specific Overrides

​Procfile

​Structure

​Process Types

​Customization

​supervisor.conf

​Structure

​Process Groups

​Generated Configuration

​nginx.conf

​Structure

​Key Sections

​SSL Configuration

​Generated Configuration

​Redis Configuration Files

​redis_cache.conf

​redis_queue.conf

​Key Differences

​Supporting Files

​apps.txt

​currentsite.txt

​patches.txt

​Configuration Management

​Viewing Configuration

​Updating Configuration

​Regenerating Configs

​Configuration Best Practices

​Troubleshooting

​Configuration Not Applied

​Config File Conflicts

​Regeneration Issues

​Related Resources

Environment Variables

Architecture

Production Setup

All Commands

Build docs developers (and LLMs) love

Overview

Configuration File Hierarchy

common_site_config.json

Structure

Configuration Options

Example Configurations

site_config.json

Structure

Configuration Options

Site-Specific Overrides

Procfile

Structure

Process Types

Customization

supervisor.conf

Structure

Process Groups

Generated Configuration

nginx.conf

Structure

Key Sections

SSL Configuration

Generated Configuration

Redis Configuration Files

redis_cache.conf

redis_queue.conf

Key Differences

Supporting Files

apps.txt

currentsite.txt

patches.txt

Configuration Management

Viewing Configuration

Updating Configuration

Regenerating Configs

Configuration Best Practices

Troubleshooting

Configuration Not Applied

Config File Conflicts

Regeneration Issues

Related Resources