Supervisord

Supervisor is a process-control system for Unix-like hosts. It starts configured programs, captures their output, restarts them when appropriate, and exposes a control interface. It is useful when an application needs a lightweight, explicit process manager, but it is not a substitute for the operating system’s init system or service manager.

Define a Program #

A minimal program definition belongs in Supervisor’s included configuration directory:

[program:worker]
command=/opt/app/bin/worker --queue=default
directory=/opt/app
user=app
autostart=true
autorestart=unexpected
startsecs=5
stopasgroup=true
killasgroup=true
stdout_logfile=/var/log/app/worker.log
stderr_logfile=/var/log/app/worker-error.log

startsecs prevents a process that exits immediately from being reported as successfully started. stopasgroup and killasgroup help ensure that child processes receive termination signals during a restart. Run the service as an unprivileged user and grant only the filesystem access it needs.

Apply and Inspect Configuration #

After changing configuration, reload it deliberately:

supervisorctl reread
supervisorctl update
supervisorctl status
supervisorctl tail -f worker stderr

reread discovers configuration changes; update adds, removes, or restarts affected programs. Use supervisorctl restart worker for an intentional restart, and inspect logs before increasing retry counts.

Containers and Service Managers #

In a single-process container, run the application directly as PID 1 and let the orchestrator handle restarts. Adding Supervisor merely to run one process obscures signals and exit status. For a traditional host, prefer the platform service manager—such as systemd—when its dependency handling, cgroup integration, and logging meet the requirement. Use Supervisor when its simple program model is specifically the right operational boundary.