Supervisor — Process Control System for Unix

Introduction

Supervisor is a process manager for Unix that starts, monitors, and restarts long-running processes such as web servers, workers, and background daemons. It predates systemd and remains widely used in Docker containers, virtualenvs, and environments where systemd is unavailable or impractical.

What Supervisor Does

• Starts processes at boot and keeps them running by automatically restarting on crash or exit
• Groups related processes so they can be started, stopped, and monitored together
• Provides a CLI (supervisorctl) and optional web UI for real-time process management
• Captures stdout and stderr into rotated log files for each managed process
• Supports event listeners that trigger custom actions on process state changes

Architecture Overview

Supervisor runs as a daemon (supervisord) that reads an INI-style configuration file defining programs and their parameters. It forks child processes, monitors their PIDs, and restarts them according to the configured policy (always, on crash, or never). The supervisorctl CLI communicates with supervisord over a Unix socket or TCP port using an XML-RPC protocol. An optional web interface uses the same RPC backend.

Self-Hosting & Configuration

• Install via pip, apt, or yum; runs on Python 3.4+
• Define each managed process as a [program:name] section in supervisord.conf
• Set autostart=true and autorestart=true for services that should always be running
• Configure numprocs to run multiple instances of the same program with dynamic naming
• Enable the [inet_http_server] section for the built-in web dashboard on a chosen port

Key Features

• Simple INI-style configuration for defining processes with no code required
• Automatic restart with configurable backoff and retry limits on process failure
• Process groups let you manage related services (e.g., web + worker + scheduler) as a unit
• Built-in log capture and rotation for stdout and stderr per process
• XML-RPC API enables programmatic control from scripts and monitoring tools

Comparison with Similar Tools

• systemd — the modern Linux init system; more powerful but not available in containers or virtualenvs
• PM2 — Node.js process manager with clustering and metrics; JavaScript-focused
• runit — lightweight init with a different supervision model; less common in application deployments
• s6 — small and fast process supervisor; lower-level with a steeper learning curve
• Docker Compose — manages containers rather than bare processes; different abstraction level

FAQ

Q: Should I use Supervisor inside Docker containers? A: Yes, when a container needs to run multiple processes (e.g., app + log shipper). For single-process containers, the container runtime handles restarts.

Q: Does Supervisor work on macOS? A: Yes. It runs on any Unix-like system with Python. macOS users can install it via pip or Homebrew.

Q: How does Supervisor compare to systemd for application services? A: systemd is the standard on modern Linux. Supervisor is preferred in containers, virtualenvs, and legacy systems where systemd is not available.

Q: Can I extend Supervisor with custom event handlers? A: Yes. Event listeners are programs that subscribe to process state changes via stdin/stdout and can trigger alerts, log shipping, or custom recovery actions.

Sources

• https://github.com/Supervisor/supervisor
• http://supervisord.org/