The bench setup supervisor command generates a Supervisor configuration file for managing Frappe bench processes.
Usage
bench setup supervisor [OPTIONS]
Options
System user to run bench processes.Defaults to current user if not specified.
Automatically overwrite existing supervisor.conf without confirmation.
Skip Redis configuration in Supervisor.Use this if you’re running Redis separately.
Skip supervisord system configuration checks.Useful if you don’t have sudo access.
Examples
Basic Configuration
Generate Supervisor configuration:
Specify User
Generate configuration for specific user:
bench setup supervisor --user frappe
Skip Redis
If running Redis externally:
bench setup supervisor --skip-redis
Skip Confirmation
Overwrite existing configuration:
bench setup supervisor --yes
Without Sudo Access
If you don’t have sudo privileges:
bench setup supervisor --skip-supervisord
Prerequisites
Supervisor must be installed on your system before running this command.
Install Supervisor
Ubuntu/Debian:
sudo apt-get install supervisor
sudo yum install supervisor
Generated Configuration
File Location
frappe-bench/config/supervisor.conf
Process Groups
The configuration includes these process groups:
- frappe-bench-web: Gunicorn web workers
- frappe-bench-workers: Background job workers
- frappe-bench-schedule: Scheduler process
- frappe-bench-node-socketio: SocketIO server
- frappe-bench-redis (optional): Redis servers
Example Configuration
[group:frappe-bench-web]
programs=frappe-bench-frappe-web
[program:frappe-bench-frappe-web]
command=/home/frappe/frappe-bench/env/bin/gunicorn
-b 127.0.0.1:8000
-w 4
--max-requests 5000
--max-requests-jitter 500
-t 120
frappe.app:application
user=frappe
directory=/home/frappe/frappe-bench/sites
autostart=true
autorestart=true
stdout_logfile=/home/frappe/frappe-bench/logs/web.log
stderr_logfile=/home/frappe/frappe-bench/logs/web.error.log
Production Setup
After generating the configuration, create a symlink and reload Supervisor.
Create Symlink
Ubuntu/Debian:
sudo ln -s ~/frappe-bench/config/supervisor.conf /etc/supervisor/conf.d/frappe-bench.conf
sudo ln -s ~/frappe-bench/config/supervisor.conf /etc/supervisord.d/frappe-bench.ini
Reload Supervisor
sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start all
Managing Processes
Check Status
sudo supervisorctl status
frappe-bench-web:frappe-bench-frappe-web RUNNING pid 1234, uptime 0:10:00
frappe-bench-workers:frappe-bench-worker-0 RUNNING pid 1235, uptime 0:10:00
frappe-bench-workers:frappe-bench-worker-1 RUNNING pid 1236, uptime 0:10:00
Start/Stop Processes
# Start all processes
sudo supervisorctl start all
# Stop all processes
sudo supervisorctl stop all
# Restart all processes
sudo supervisorctl restart all
Manage Specific Process Group
# Restart only web workers
sudo supervisorctl restart frappe-bench-web:
# Stop background workers
sudo supervisorctl stop frappe-bench-workers:
# Start scheduler
sudo supervisorctl start frappe-bench-schedule:
View Logs
# Tail web worker logs
sudo supervisorctl tail frappe-bench-web stdout
# View error logs
sudo supervisorctl tail frappe-bench-web stderr
# Follow logs (-f flag)
sudo supervisorctl tail -f frappe-bench-workers stdout
Configuration Details
Web Workers
Number of workers is calculated based on CPU cores:
workers = (cpu_count * 2) + 1
common_site_config.json:
{
"gunicorn_workers": 4
}
Background Workers
Default is 1 background worker. Increase for high load:
{
"background_workers": 3
}
Custom Workers
Define custom worker pools for specific queues:
{
"workers": {
"long": 2,
"short": 3
}
}
Max Requests
Gunicorn workers restart after handling a number of requests:
{
"gunicorn_max_requests": 5000
}
Multi-Queue Consumption
For Frappe v14.18.0+, workers can consume from multiple queues simultaneously:
{
"multi_queue_consumption": true
}
Auto-Update Settings
Enable automatic Supervisor reload on bench update:
{
"restart_supervisor_on_update": true
}
Troubleshooting
Supervisor Not Found
If the command fails with “supervisor not installed”:
# Install supervisor
sudo apt-get install supervisor
# Verify installation
which supervisorctl
# Try again
bench setup supervisor
Permission Denied
If you see “Permission denied” when running supervisorctl:
# Check supervisord config ownership
ls -l /var/run/supervisor.sock
# Should show:
# srwxrwx--- 1 frappe frappe 0 ... /var/run/supervisor.sock
sudo nano /etc/supervisor/supervisord.conf
[unix_http_server]
file=/var/run/supervisor.sock
chmod=0760
chown=frappe:frappe
sudo systemctl restart supervisor
Processes Not Starting
-
Check configuration syntax:
cat config/supervisor.conf
-
Verify file paths and permissions:
ls -la env/bin/gunicorn
ls -la sites/
-
Check Supervisor logs:
sudo tail -f /var/log/supervisor/supervisord.log
-
Test process manually:
cd ~/frappe-bench/sites
../env/bin/gunicorn -b 127.0.0.1:8000 frappe.app:application
Update Not Reflected
After modifying configuration:
# Regenerate
bench setup supervisor --yes
# Reload supervisor
sudo supervisorctl reread
sudo supervisorctl update
# Restart processes
sudo supervisorctl restart all
systemd Alternative
You can use systemd instead of Supervisor:
bench setup systemd --user frappe
- Better integration with modern Linux systems
- Enhanced logging with journald
- More robust restart policies
Source Code
Implementation: bench/config/supervisor.py:25
Command definition: bench/commands/setup.py:55 