Supervisord guide

What supervisord does

Supervisord is a client/server system that monitors and controls a set of processes on UNIX-like systems. The main daemon reads configuration, spawns child programs, restarts them when they exit unexpectedly, and logs stdout/stderr to files. You interact with it through supervisorctl or an optional web UI.

On modern Linux hosts, systemd typically handles service lifecycle at boot. Supervisord is still common in older stacks, Docker sidecars, and Python-centric deployments (Celery workers, Gunicorn pools) where one supervisord instance manages multiple app processes.

How it works

1. Daemon starts — supervisord reads supervisord.conf (and included files)
2. Programs defined — each [program:name] section describes a managed process
3. Spawn — supervisord runs command= as the configured user, capturing output
4. Supervise — on unexpected exit, autorestart= policy decides whether to restart
5. Control — supervisorctl sends RPC commands (start, stop, status) to the unix socket or inet port

Configuration layout

• /etc/supervisor/supervisord.conf — main config (Debian/Ubuntu default)
• /etc/supervisor/conf.d/*.conf — drop-in program definitions
• [supervisord] — global daemon settings, log file, pid file
• [program:myapp] — command, user, autostart, autorestart, logs
• [group:mygroup] — manage related programs as a unit
• [include] — pull in additional config files

Key program options

• command= — full path to the process to run (required)
• directory= — working directory before spawn
• user= — drop privileges to this user
• autostart=true — start when supervisord starts
• autorestart=unexpected — restart on crash but not on clean exit
• stdout_logfile= — where stdout is written
• environment= — key=value pairs for the subprocess

supervisord vs systemd

systemd integrates with the OS boot process, dependency ordering, cgroups, and journald. Supervisord is a lighter, application-focused supervisor — often run as a single service itself (sometimes under systemd). For greenfield Linux servers, prefer systemd service units; learn supervisord for legacy maintenance.

Learning resources

• Supervisor documentation — supervisord.org/introduction (official docs)
• Configuration file — supervisord.org/configuration (all directives)
• Subprocesses — supervisord.org/subprocess ([program:x] section reference)
• Running supervisor — supervisord.org/running (startup and signals)