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 be small shell scripts, Node.js apps, or any large-sized packages.
Conventionally, you may write a init script for each of these programs, but this can quickly become time consuming to manage and isn't always particularly transparent for newer users.
Supervisor is a process manager which makes managing a number of long-running programs a trivial task by providing a consistent interface through which they can be monitored and controlled.
This tutorial assumes that you are familiar with the command line, installing packages, and basic server management.
Installation
Installation of Supervisor on both Ubuntu and Debian is incredibly simple, as prebuilt packages already exist within both distributions' repositories.
As the root user, run the following command to install the Supervisor package:
apt-get install supervisor
Once this has completed, the supervisor daemon should already be started, as the prebuilt packages come with an init script that will also ensure the Supervisor is restarted after a system reboot. You can ensure this is the case by running:
service supervisor restart
Now that we have Supervisor installed, we can look at adding our first programs.
Adding a Program
New programs are given to Supervisor through configuration files, which inform it of the executable to run, any environmental variables, and how output should be handled.
Note: All programs run under Supervisor must be run in a non-daemonising mode (sometimes also called 'foreground mode'). If, by default, the program forks and returns on startup, then you may need to consult the program's manual to find the option to enable this mode, otherwise Supervisor will not be able to properly determine the status of the program.
For the sake of this article, we'll assume we have a shell script we wish to keep persistently running that we have saved at /usr/local/bin/long.sh and looks like the following:
#!/bin/bash while true do # Echo current date to stdout echo `date` # Echo 'error!' to stderr echo 'error!' >&2 sleep 1 done
chmod +x /usr/local/bin/long.sh
In a practical sense, this script is clearly rather pointless, but it will allow us to cover the fundamentals of Supervisor configuration.
The program configuration files for Supervisor programs are found in the /etc/supervisor/conf.d directory, normally with one program per file and a .conf extension. A simple configuration for our script, saved at /etc/supervisor/conf.d/long_script.conf, would look like so:
[program:long_script] command=/usr/local/bin/long.sh autostart=true autorestart=true stderr_logfile=/var/log/long.err.log stdout_logfile=/var/log/long.out.log
We'll look at the significance of each line and some of the tweaks that may be desirable for your program below:
[program:long_script] command=/usr/local/bin/long.sh
The configuration begins by defining a program with the name 'long_script' and the full path to the program:
autostart=true autorestart=true
The next two lines define the basic automatic behaviour 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 command following any system shutdown.
autorestart defines how Supervisor should manage the program in the event it exits and has three options:
- 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).
stderr_logfile=/var/log/long.err.log stdout_logfile=/var/log/long.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 directory specified must exist before we start the program, as Supervisor will not attempt to create any missing directories.
The configuration we have created here is a minimal reasonable template for a Supervisor program. The documentation lists many more optional configuration options that are available to fine tune how the program is executed.
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:
supervisorctl reread
Followed by telling it to enact any changes with:
supervisorctl update
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 and we can check this is the case by looking at the output log file:
$ tail /var/log/long.out.log Sat Jul 20 22:21:22 UTC 2013 Sat Jul 20 22:21:23 UTC 2013 Sat Jul 20 22:21:24 UTC 2013 Sat Jul 20 22:21:25 UTC 2013 Sat Jul 20 22:21:26 UTC 2013 Sat Jul 20 22:21:27 UTC 2013 Sat Jul 20 22:21:28 UTC 2013 Sat Jul 20 22:21:29 UTC 2013 Sat Jul 20 22:21:30 UTC 2013 Sat Jul 20 22:21:31 UTC 2013
Success!
Managing Programs
Once our programs are running, there will undoubtedly be a time when we want to stop, restart, or see their status. The supervisorctl program, which we first used above, also has an interactive mode through which we can issue commands to control our programs.
To enter the interactive mode, start supervisorctl with no arguments:
$ supervisorctl long_script RUNNING pid 12614, uptime 1:49:37 supervisor>
When started, supervisorctl will initially print the status and uptime of all programs, followed by showing a command prompt. Entering help will reveal all of the available commands that we can use:
supervisor> help default commands (type helpTo start in a simple manner, we can start, stop and restart a program with the associated commands followed by the program name:): ===================================== add clear fg open quit remove restart start stop update avail exit maintail pid reload reread shutdown status tail version
supervisor> stop long_script long_script: stopped supervisor> start long_script long_script: started supervisor> restart long_script long_script: stopped long_script: started
Using the tail command, we can view the most recent entries in the stdout and stderr logs for our program:
supervisor> tail long_script Sun Jul 21 00:36:10 UTC 2013 Sun Jul 21 00:36:11 UTC 2013 Sun Jul 21 00:36:12 UTC 2013 Sun Jul 21 00:36:13 UTC 2013 Sun Jul 21 00:36:14 UTC 2013 Sun Jul 21 00:36:15 UTC 2013 Sun Jul 21 00:36:17 UTC 2013 supervisor> tail long_script stderr error! error! error! error! error! error! error!
Using status we can view again the current execution state of each program after making any changes:
supervisor> status long_script STOPPED Jul 21 01:07 AM
Finally, once we are finished, we can exit supervisorctl with Ctrl-C or by entering quit into the prompt:
supervisor> quit
And that's it! You've mastered the basics of managing persistent programs through Supervisor and extending this to your own programs should be a relatively simple task. If you have any questions or further advice, be sure to leave it in the comments section.
