Getting Started with Supervisor on Linux with Installation process and Example
Supervisor is a powerful process control system designed specifically for UNIX-like operating systems, including Linux. It is used to monitor and control a number of long-running background processes (commonly known as daemons). Unlike traditional service management tools like systemd or init, Supervisor provides a simpler and more flexible solution, especially suited for managing custom applications, scripts, or workers in environments where you don’t want or need full-blown service management frameworks. It is widely adopted in development and production environments to ensure that critical processes remain active, are restarted upon failure, and can be managed from a single interface.
At its core, Supervisor consists of two main components: supervisord and supervisorctl. The supervisord is the main daemon process that reads configuration files, starts and monitors the defined child processes, and manages their state. On the other hand, supervisorctl is a command-line client that interacts with supervisord to control the processes, such as starting, stopping, restarting, and viewing logs. Additionally, Supervisor can be configured to run a lightweight web interface that allows administrators to monitor and manage processes from a browser, which is particularly useful for remote system management.
One of the most important features of Supervisor is its ability to automatically restart programs if they crash or exit unexpectedly. By setting options like autostart=true and autorestart=true, Supervisor ensures that your application remains available even in the face of transient errors. You can also define retry intervals and limits using settings like startretries and startsecs to control how aggressively Supervisor attempts to restart a failing service. Supervisor also consolidates the stdout and stderr output of each process into configurable log files, providing centralized and accessible logging for troubleshooting and auditing purposes.
What is Supervisor?
Supervisor is a process control system that allows you to monitor and control processes on UNIX-like operating systems. It runs as a background daemon called supervisord, usually listening on port 9001.
It’s particularly useful in production where reliability is non-negotiable — like when running background services (aka daemons).
It allows you to:
Automatically start, stop, restart, or monitor processes.
Automatically restart a crashed process.
Handle multiple services in one machine.
Run processes as daemons (background services).
Centralize logs and output from different services.
How Supervisor Works Internally?
1. Supervisor Daemon (supervisord)
The core of Supervisor is the supervisord process, which acts as a background daemon responsible for managing all the services defined in its configuration files. When started, supervisord reads a main configuration file (commonly located at /etc/supervisord.conf or specified manually), parses the defined programs, and starts them as child processes. It ensures these processes remain active and running. If a process stops or crashes, supervisord uses predefined rules to decide whether to restart it or report it as failed.
2. Supervisor Client (supervisorctl)
supervisorctl is a command-line utility that allows administrators or automated scripts to communicate with the supervisord process. Through this tool, users can issue commands to start, stop, restart, and check the status of individual services or groups of services. It connects to supervisord either through a UNIX socket or a TCP/IP address as defined in the configuration. It provides a real-time way to control and inspect service behavior without needing to kill processes manually or restart entire systems.
3. Process Monitoring
A key function of Supervisor is its built-in process monitoring capability. Once a service is started, supervisord watches its status closely. If a process exits unexpectedly or fails during startup, Supervisor can be configured to restart it automatically. This is controlled through settings like autorestart=true and startretries=3, which define how many times to retry starting a service and under what conditions a restart should happen. This feature ensures high availability and resilience of critical services, making Supervisor especially useful for production environments where uptime is essential.
4. Logging and Web Interface
Supervisor also provides detailed logging for each managed service. It captures both standard output and standard error and writes them to log files specified in the configuration. These logs are crucial for debugging errors, analyzing service behavior, and conducting post-mortem reviews when failures occur.
Why Use Supervisor? Real-Life Scenario
Let’s say you’ve deployed a Python Flask app or a Node.js API on an EC2 instance.
You start your app using python app.py or node server.js , running everything smoothly but suddenly:
The app crashes due to a bug. You accidentally close the terminal. The server reboots during a scheduled update.
Result without Supervisor: Your app goes offline. Visitors see a broken site.
Result with Supervisor: Your app restarts automatically. No manual intervention needed.
Installing Supervisor
Here’s how to install Supervisor on popular Linux distributions.
Ubuntu/Debian
sudo apt update
sudo apt install supervisorCentOS/RHEL
sudo yum install epel-release
sudo yum install supervisorStart and enable the Supervisor service
sudo systemctl enable supervisord
sudo systemctl start supervisordIt usually listens on port 9001, unless changed in the configuration.
Real-Life Scenario: Hosting a Web App on Linux
Imagine you’re running a backend application (could be a web app, API service, etc.) on an Ubuntu server. For example:
node server.js # Node.js or
python3 app.py # Python or
java -jar app.jar # Java
But what happens if:
The app crashes due to an uncaught exception?
The server restarts due to maintenance?
You close the terminal session?
Your app stops, and users see a broken site. Bad UX!
With Supervisor:
The app is restarted automatically.
It boots up again after server reboots.
You can manually control it via supervisorctl.
Example: Running a Node.js API with Supervisor
Step 1: Install Supervisor
sudo apt update
sudo apt install supervisorStep 2: Create a Config File
sudo nano /etc/supervisor/conf.d/node-api.conf
[program:node-api]
directory=/home/ubuntu/apps/node-api
command=node server.js
autostart=true
autorestart=true
stdout_logfile=/var/log/node-api.out.log
stderr_logfile=/var/log/node-api.err.log
environment=NODE_ENV="production",PORT="3000"Step 3: Reload and Start
sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start node-api
Managing Multiple Services
Supervisor can manage multiple processes simultaneously. Just add a config for each service inside
/etc/supervisor/conf.d/.
/etc/supervisor/
│
├── supervisord.conf
└── conf.d/
├── node-api.conf
├── email-worker.conf
├── nginx.conf
└── redis.conf
Each file can look like:
[program:email-worker]
directory=/home/ubuntu/apps/email-worker
command=python3 worker.py
autostart=true
autorestart=true
stdout_logfile=/var/log/email-worker.out.log
stderr_logfile=/var/log/email-worker.err.log
Production Tips for Using Supervisor
Use Non-Root Users
Set the user field in your config to avoid running services as root:
user=appuser
Log File Management
Create appropriate log directories:
sudo mkdir -p /var/log/node-api
sudo chown appuser:appuser /var/log/node-apiRotate logs using logrotate or built-in Supervisor options.
Conclusion
Supervisor is a reliable tool for managing background processes on Linux servers. By installing and configuring it correctly, you can easily start, stop, and monitor applications, ensuring they run continuously without manual intervention. This makes server management more efficient and reduces the risk of service downtime.