// Tutorial //

How To Install and Manage Supervisor

Published on July 23, 2013 · Updated on January 4, 2022
Default avatar
By Alex Garnett
Senior DevOps Technical Writer
How To Install and Manage Supervisor

Introduction

In many VPS environments, it is often the case that you will have a number of small programs that you want to run persistently, whether these are small shell scripts, Node.js apps, or any large-sized packages.

Usually, external packages are supplied with a unit file that allows them to be managed by an init system such as systemd, or packaged as docker images which can be managed by a container engine. However, for software that isn’t well-packaged, or for users who would prefer not to interact with a low-level init system on their server, it is helpful to have a lightweight alternative.

Supervisor is a process manager which provides a singular interface for managing and monitoring a number of long-running programs. In this tutorial, you will install Supervisor on a Linux server and learn how to manage Supervisor configurations for multiple applications.

Prerequisites

To complete this guide, you will need:

Alternatively, you can use an interactive terminal embedded on this page to experiment with the sample commands in this tutorial. Click the following Launch an Interactive Terminal! button to open a terminal window and begin working with a Linux (Ubuntu) environment.

Step 1 - Installation

Begin by updating your package sources and installing Supervisor:

  1. sudo apt update && sudo apt install supervisor

The supervisor service runs automatically after installation. You can check its status:

  1. sudo systemctl status supervisor

You should receive the following output:

Output
● supervisor.service - Supervisor process control system for UNIX Loaded: loaded (/lib/systemd/system/supervisor.service; enabled; vendor preset: enabled) Active: active (running) since Wed 2021-11-17 22:56:48 UTC; 5min ago

Now that we have Supervisor installed, we can look at adding our first programs.

Step 2 - Adding a Program

A best practice for working with Supervisor is to write a configuration file for every program it will handle.

All programs run under Supervisor must be run in a non-daemonising mode (sometimes also called ‘foreground mode’). If, by default, your program automatically returns to the shell after running, then you may need to consult the program’s manual to find the option to enable this mode, or Supervisor will not be able to properly determine the status of the program.

In order to demonstrate Supervisor’s functionality, we’ll create a shell script that does nothing other than produce some predictable output once a second, but will run continuously in the background until it is manually stopped. Using nano or your favorite text editor, open a file called idle.sh in your home directory:

  1. nano ~/idle.sh

Add the following contents:

~/idle.sh
#!/bin/bash
while true
do 
	# Echo current date to stdout
	echo `date`
	# Echo 'error!' to stderr
	echo 'error!' >&2
	sleep 1
done

Save and close the file. If you are using nano, press Ctrl+X, then when prompted, Y and Enter.

Next, make your script executable:

  1. chmod +x ~/idle.sh

The per-program configuration files for Supervisor programs are located in the /etc/supervisor/conf.d directory, typically running one program per file and ending in .conf. We’ll create a configuration file for this script, as`/etc/supervisor/conf.d/idle.conf:

  1. sudo nano /etc/supervisor/conf.d/idle.conf

Add these contents:

/etc/supervisor/conf.d/idle.conf
command=/home/ubuntu/idle.sh
autostart=true
autorestart=true
stderr_logfile=/var/log/idle.err.log
stdout_logfile=/var/log/idle.out.log

We’ll review this line by line:

command=/home/ubuntu/idle.sh

The configuration begins by defining a program with the name idle and the full path to the program:

autostart=true
autorestart=true

The next two lines define the automatic behavior of the script under certain conditions.

The autostart option tells Supervisor that this program should be started when the system boots. Setting this to false will require a manual start following any system shutdown.

autorestart defines how Supervisor should manage the program in the event that it exits:

  • false tells Supervisor not to ever restart the program after it exits.
  • true tells Supervisor to always restart the program after it exits.
  • unexpected tells Supervisor to only restart the program if it exits with an unexpected error code (by default anything other than codes 0 or 2). To learn more about error codes, look into the errno command.
stderr_logfile=/var/log/idle.err.log
stdout_logfile=/var/log/idle.out.log

The final two lines define the locations of the two main log files for the program. As suggested by the option names, stdout and stderr will be directed to the stdout_logfile and stderr_logfile locations respectively. The specified directories must already exist, as Supervisor will not attempt to create any missing directories.

The configuration we have created here is a minimal template for a Supervisor program. The Supervisor documentation lists many more optional configuration options that are available to tune how programs are run.

Once our configuration file is created and saved, we can inform Supervisor of our new program through the supervisorctl command. First we tell Supervisor to look for any new or changed program configurations in the /etc/supervisor/conf.d directory with:

  1. sudo supervisorctl reread
Output
idle: available

Followed by telling it to enact any changes with:

  1. sudo supervisorctl update
Output
idle: added process group

Any time you make a change to any program configuration file, running the two previous commands will bring the changes into effect.

At this point our program should now be running. We can check its output by looking at the output log file:

  1. sudo tail /var/log/idle.out.log
Output
Sat Nov 20 22:21:22 UTC 2021 Sat Nov 20 22:21:23 UTC 2021 Sat Nov 20 22:21:24 UTC 2021 Sat Nov 20 22:21:25 UTC 2021 Sat Nov 20 22:21:26 UTC 2021 Sat Nov 20 22:21:27 UTC 2021 Sat Nov 20 22:21:28 UTC 2021 Sat Nov 20 22:21:29 UTC 2021 Sat Nov 20 22:21:30 UTC 2021 Sat Nov 20 22:21:31 UTC 2021

Next, we’ll cover some other usage of Supervisor.

Step 3 - Managing Programs

Beyond running programs, you will want to stop, restart, or see their status. The supervisorctl program, which we used in Step 2, also has an interactive mode which we can use to control our programs.

To enter the interactive mode, run supervisorctl with no arguments:

  1. sudo supervisorctl
Output
idle RUNNING pid 12614, uptime 1:49:37 supervisor>

supervisorctl will initially print the status and uptime of all configured programs, followed by its command prompt. Entering help will reveal all of its available commands:

  1. supervisor> help
Output
default commands (type help <topic>): ===================================== add clear fg open quit remove restart start stop update avail exit maintail pid reload reread shutdown status tail version

You can start or stop a program with the associated commands followed by the program name:

  1. supervisor> stop idle
Output
idle: stopped
  1. supervisor> start idle
Output
idle: started

Using the tail command, you can view the most recent entries in the stdout and stderr logs for your program:

  1. supervisor> tail idle
Output
Sun Nov 21 00:36:10 UTC 2021 Sun Nov 21 00:36:11 UTC 2021 Sun Nov 21 00:36:12 UTC 2021 Sun Nov 21 00:36:13 UTC 2021 Sun Nov 21 00:36:14 UTC 2021 Sun Nov 21 00:36:15 UTC 2021 Sun Nov 21 00:36:17 UTC 2021
  1. supervisor> tail idle stderr
Output
error! error! error! error! error! error! error!

Using status you can view again the current execution state of each program after making any changes:

  1. supervisor> status
Output
idle STOPPED Nov 21 01:07 AM

Finally, you can exit supervisorctl with Ctrl+C or by entering quit into the prompt:

  1. supervisor> quit

Conclusion

In this tutorial, you learned how to install and manage Supervisor. As mentioned, Supervisor is very lightweight by modern standards, but it continues to be well-maintained, and it can be a useful tool for smaller deployments. It is also a low-maintenance and self-contained way of generating logs as a component part of a larger deployment.

If you’re running multiple small apps that need to be web accessible, you may also want to read about configuring Nginx as a reverse proxy, which is another fundamental component of small, reusable deployments.


Want to learn more? Join the DigitalOcean Community!

Join our DigitalOcean community of over a million developers for free! Get help and share knowledge in our Questions & Answers section, find tutorials and tools that will help you grow as a developer and scale your project or business, and subscribe to topics of interest.

Sign up
About the authors
Default avatar
Senior DevOps Technical Writer

Still looking for an answer?

Was this helpful?
10 Comments

Hi there, I was trying to run this tutorial in a docker context and was running into errors:

https://stackoverflow.com/questions/22450171/attempting-to-recreate-supervisor-tutorial-in-docker-running-into-error-permis

Any thoughts on why?

Great tutorial! One more thing to add would be “directory=[some directory]”, which causes a change directory to occur before running your command. In my case this helped resolve relative paths in my application.

Thanks!

This is awesome! So much nicer than having to fiddle with init.d files

Is there an easy way to take control of a process that supervisor started? Like for example when running a game server that might require occasional console input.

Had error:

ERROR: CANT_REREAD: File contains no section headers.
file: '/etc/supervisor/conf.d/idle.conf', line: 1
'command=/home/admin/idle.sh\n'

When running:

 sudo supervisorctl reread

had to add:

[program:idle]

on top of /etc/supervisor/conf.d/idle.conf

This comment has been deleted

Do I have to do something special in the config file to stop it from trying to restart an already running service?

for example tail stdout.log shows this over and over:

“Service admin is already running Service admin is already running Service admin is already running Service admin is already running”

Thanks for the great tutorial. The supervisord ppa that ships with ubuntu 14.04 LTS is an old 3.0b version. The current latest stable version is 3.3.3 and it fixes some useful things (works better with ansible for example). Could you provide suggestions on a neat way of updating the ppa? Thanks!

Thank you, good explanation.

Having setup my conf file, and launch sudo supervisorctl reload and sudo supervisorctl start all, I got the following errors:

leanote: ERROR (no such file)
mongodb: ERROR (no such file)
nginx: ERROR (abnormal termination)
leanote: ERROR (no such file)
mongodb: ERROR (no such file)

Here is my /etc/supervisor/leanote.conf:

[program:mongodb]
command=mongod --dbpath /home/username/leanotedata --auth
directory=/home/username/mongodb/bin
user=username
autorestart=true
redirect_stderr=true

[program:nginx]
command=nginx
user=username
autorestart=true
redirect_stderr=true

[program:leanote]
command=revel run github.com/leanote/leanote
directory=/home/username
user=username
autorestart=true
redirect_stderr=true

Please help.

This is much easier than monit or upstart or something else similar. I’m using supervisor in my Docker compose scripts to launch multiple daemons within container and easily group them with ability to easily send TERM signal to every daemon when container stops. This is REALLY simplifies the hassle with multiple daemons per container.