Skip to main content
The bench setup production command performs a complete production setup, configuring NGINX as a web server and Supervisor or systemd for process management.
This command requires sudo privileges and will make system-wide changes. Only use on production servers, not on development machines.

​
Usage

sudo bench setup production [USER] [OPTIONS]

​
Arguments

​
USER
string
required
System user that will own and run the bench processes.Typically frappe or your server username.

​
Options

​
--yes
flag
Skip confirmation prompts and automatically regenerate configuration files.

​
Examples

​
Basic Production Setup

Set up production environment for user frappe: 
sudo bench setup production frappe

​
Skip Confirmations

Automatically overwrite existing configuration: 
sudo bench setup production frappe --yes

​
What It Does

1

Install Prerequisites

Installs required system packages:
  • Ansible (for automation)
  • fail2ban (intrusion prevention)
  • NGINX (web server)
  • Supervisor (process manager)
2

Detect Process Manager

Checks common_site_config.json for:
  • restart_supervisor_on_update: Use Supervisor
  • restart_systemd_on_update: Use systemd
Defaults to Supervisor if neither is set.
3

Configure Process Manager

Generates and installs configuration for either:
  • Supervisor configuration in /etc/supervisor/conf.d/
  • systemd service files in /etc/systemd/system/
4

Configure NGINX

Generates NGINX configuration and creates symlink in /etc/nginx/conf.d/.
5

Fix Permissions

Sets proper file ownership and permissions for the bench directory.
6

Remove Default Configs

Removes default NGINX configurations that might conflict:
  • /etc/nginx/conf.d/default.conf
  • /etc/nginx/sites-enabled/default
7

Reload Services

Reloads Supervisor/systemd and NGINX to apply changes.

​
Configuration Files Created

​
Supervisor Mode

/etc/supervisor/conf.d/frappe-bench.conf
  ↓ symlink
~/frappe-bench/config/supervisor.conf

​
systemd Mode

/etc/systemd/system/frappe-bench-*.service
  ↓ generated from
~/frappe-bench/config/systemd/

​
NGINX

/etc/nginx/conf.d/frappe-bench.conf
  ↓ symlink
~/frappe-bench/config/nginx.conf

​
Process Management

​
Supervisor (Default)

Manage bench processes with supervisorctl: 
# Check status
sudo supervisorctl status

# Restart all processes
sudo supervisorctl restart all

# Restart specific process
sudo supervisorctl restart frappe-bench-web:

# View logs
sudo supervisorctl tail frappe-bench-web stdout

​
systemd

To use systemd instead of Supervisor, set in common_site_config.json: 
{
  "restart_systemd_on_update": true,
  "restart_supervisor_on_update": false
}
Then manage with systemctl: 
# Check status
sudo systemctl status frappe-bench-*

# Restart all services
sudo systemctl restart frappe-bench-*

# Enable on boot
sudo systemctl enable frappe-bench-*

​
Prerequisites

​
System Requirements

  • Ubuntu 20.04+ or Debian 10+
  • Sudo access
  • Python 3 with pip
  • At least 2GB RAM (4GB recommended)

​
Bench Requirements

  • Fully initialized bench with at least one site
  • All apps installed and working
  • DNS configured (for multi-tenant setups)

​
DNS Configuration

​
Single Site

For a single site on a dedicated server: 
// sites/common_site_config.json
{
  "dns_multitenant": false
}
NGINX will use port-based configuration (default: port 80).

​
Multi-Tenant

For multiple sites with different domains: 
// sites/common_site_config.json
{
  "dns_multitenant": true
}
NGINX will use name-based virtual hosts.

​
Post-Setup Steps

1

Verify Services

Check that all services are running:
sudo supervisorctl status
sudo systemctl status nginx
2

Test Web Access

Visit your site in a browser:
http://your-server-ip
Or with domain:
http://your-domain.com
3

Set Up SSL

Secure your site with HTTPS:
sudo bench setup lets-encrypt site1.local
4

Configure Backups

Set up automated backups:
bench setup backups

​
Troubleshooting

​
Permission Errors

If you see permission denied errors: 
# Fix bench directory permissions
sudo chown -R frappe:frappe ~/frappe-bench

# Re-run setup
sudo bench setup production frappe --yes

​
NGINX Test Failed

If NGINX configuration test fails: 
# Test NGINX configuration
sudo nginx -t

# Check configuration file
cat config/nginx.conf

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

​
Services Not Starting

For Supervisor: 
# Check logs
sudo supervisorctl tail frappe-bench-web stderr

# Reload configuration
sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl restart all
For systemd: 
# Check service status
sudo systemctl status frappe-bench-web

# View logs
sudo journalctl -u frappe-bench-web -n 50

# Reload and restart
sudo systemctl daemon-reload
sudo systemctl restart frappe-bench-*

​
Port Already in Use

If port 80 or other ports are in use: 
# Check what's using port 80
sudo lsof -i :80

# For non-DNS multitenant, change webserver port
bench config http_timeout 120
bench config webserver_port 8000

# Regenerate configuration
sudo bench setup production frappe --yes

​
Security Considerations

​
File Permissions

Production setup ensures:
  • Bench files owned by specified user
  • Proper read/write/execute permissions
  • Web-facing directories not world-writable

​
fail2ban

The setup installs fail2ban for intrusion prevention. Configure additional jails: 
bench setup fail2ban --maxretry 5 --bantime 600

​
Firewall

Set up a firewall to allow only necessary ports: 
bench setup firewall --ssh_port 22
This blocks all ports except 80, 443, and your SSH port.

​
Source Code

Implementation: bench/config/production_setup.py:35 Command definition: bench/commands/setup.py:103

Build docs developers (and LLMs) love

Get started for freeTalk to us