In this tutorial, we'll learn how to install and use supervisor on Debian 13 server to manage process.
Supervisor (the supervisord daemon + supervisorctl client) is a lightweight process manager. We use it when we want a non-systemd app (scripts, workers, queue consumers, custom binaries) to auto-start, auto-restart, and stay monitored without writing our own service logic.
Prerequisites
Before starting, make sure our new Ubuntu server is ready. The following components should be installed and configured:
- A Debian 13 installed dedicated server or KVM VPS.
- A root user or normal user with administrative privileges.
How to Install and Use Supervisor on Debian 13 with an examples.
Step 1: Update the server
sudo apt update && sudo apt -y upgrade
Keeping the base system updated avoids dependency issues later.
Step 2: Install Supervisor
Install Supervisor using following command:
sudo apt -y install supervisor
Confirm binaries exist:
supervisord --version
supervisorctl --version
Step 3: Start and enable Supervisor (systemd)
sudo systemctl enable --now supervisor
sudo systemctl status supervisor --no-pager
If it fails, check logs:
sudo journalctl -u supervisor -n 200 --no-pager
Step 5: Understand Debian’s config layout
Supervisor’s main config is typically /etc/supervisor/supervisord.conf. Supervisor also supports “include” patterns so we can drop app configs into a directory like /etc/supervisor/conf.d/.
And it loads:
files = /etc/supervisor/conf.d/*.conf
If you see something like files = /etc/supervisor/conf.d/*.conf, we’re good.
Verify:
grep -n "\[include\]" /etc/supervisor/supervisord.conf
sed -n '/\[include\]/,/^$/p' /etc/supervisor/supervisord.conf
Step 6: Example 1 (simple): keep a Python HTTP server alive
This example proves the workflow end-to-end. We’ll run a tiny web server on port 9001 and let Supervisor keep it running.
Create a directory to serve:
sudo mkdir -p /opt/supervisor-demo
echo "Supervisor on Debian is alive." | sudo tee /opt/supervisor-demo/index.html >/dev/null
Create a program config:
sudo tee /etc/supervisor/conf.d/python-http.conf >/dev/null <<'EOF'
[program:python_http]
command=/usr/bin/python3 -m http.server 9001
directory=/opt/supervisor-demo
autostart=true
autorestart=true
startsecs=2
stderr_logfile=/var/log/supervisor/python_http.err.log
stdout_logfile=/var/log/supervisor/python_http.out.log
EOF
Reload Supervisor and start the program:
sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl status
Test locally:
curl -i http://127.0.0.1:9001/
Useful day-to-day commands:
sudo supervisorctl status
sudo supervisorctl restart python_http
sudo supervisorctl stop python_http
sudo supervisorctl tail -f python_http
Step 7: Example 2 (real-world): run a background worker with retries
Many production tasks are workers (queue consumers, crawlers, schedulers). Here’s a safe pattern using multiple processes.
Create a worker script:
sudo tee /opt/supervisor-demo/worker.sh >/dev/null <<'EOF'
#!/usr/bin/env bash
set -euo pipefail
while true; do
echo "$(date -Is) worker alive"
sleep 5
done
EOF
sudo chmod +x /opt/supervisor-demo/worker.sh
Supervisor config with 3 processes:
sudo tee /etc/supervisor/conf.d/demo-worker.conf >/dev/null <<'EOF'
[program:demo_worker]
command=/opt/supervisor-demo/worker.sh
directory=/opt/supervisor-demo
autostart=true
autorestart=true
numprocs=3
process_name=%(program_name)s_%(process_num)02d
stderr_logfile=/var/log/supervisor/demo_worker.err.log
stdout_logfile=/var/log/supervisor/demo_worker.out.log
EOF
Apply changes:
sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl status
If one process dies, Supervisor restarts it automatically.
Step 8: Logging and troubleshooting that actually helps
Supervisor daemon logs are usually in systemd journal:
sudo journalctl -u supervisor -n 200 --no-pager
App logs (from our configs):
sudo ls -l /var/log/supervisor/
sudo tail -n 200 /var/log/supervisor/demo_worker.out.log
Validate config changes safely:
sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl status
If reread shows errors, fix the .conf file before running update.
Step 9: Optional: Supervisor web UI (keep it private)
Supervisor supports an HTTP interface, but we should treat it like an admin console: bind to localhost and protect it.
Edit /etc/supervisor/supervisord.conf and add something like this (exact placement doesn’t matter as long as it’s valid INI):
sudo nano /etc/supervisor/supervisord.conf
Add following parameters:
[inet_http_server]
port=127.0.0.1:9001
username=admin
password=strongpassword
Then restart:
sudo systemctl restart supervisor
Access from the server:
curl -I http://127.0.0.1:9001/
If we need remote access, we typically put it behind SSH tunneling or a reverse proxy with proper auth, not open to the internet.
Step 10: Clean removal (if we stop using it)
sudo systemctl disable --now supervisor
sudo apt -y remove supervisor
Quick recap of the workflow we’ll use in production
- Put each service under /etc/supervisor/conf.d/
- Run: supervisorctl reread && supervisorctl update
- Use: supervisorctl status, restart, and tail -f for operations
- Keep logs in /var/log/supervisor/ and monitor with systemd journal when needed
We have seen how to install and use supervisor on Debian 13 server to manage process. Supervisor isn’t fancy. That’s the point. It just keeps our processes alive while the rest of the world continues falling apart.
