Community site: login faq

I want to start a script and make sure it keeps running continuously. I've heard that supervisor is good for this. How do I get started with it?

asked 08 Apr '15, 21:41

ddbeck's gravatar image

accept rate: 100%

This answer is a bit long, but it will guide you through:

  • Installing and configuring supervisor itself
  • Checking to make sure the supervisord daemon is running properly
  • Running a program with supervisord and controlling it with supervisorctl
  • An example configuration with a Django app
  • Making sure supervisord itself runs

I'm going to make some assumptions about how you want to use supervisor (for example, I assume you want use its web interface). There are many other ways to set up supervisor (e.g., with a domain socket instead of a TCP port), so be sure to look over the documentation to make sure you're setting it up appropriately for your particular use case.

With that out of the way, let's get started!

Install and configure supervisor

First, configure and install supervisor.

  1. In the control panel, create a Custom app (listening on port). Make a note of the port number assigned to your application.

  2. Log in to your account with SSH.

  3. Install supervisord. Enter pip install supervisor (note the lack of d) and press Enter.

    If you get a pip: command not found error, see Installing Packages with Pip for directions to set up pip.

  4. Make sure supervisor installed correctly. Enter echo_supervisord_conf and press Enter. If it installed properly then it outputs a default configuration file.

  5. Create your configuration file. Enter echo_supervisord_conf > $HOME/webapps/<SUPERVISOR_APP>/supervisord.conf, where <SUPERVISOR_APP> is the name of the application you created in the first step, and press Enter. The configuration file is created in your application directory.

  6. Open the ~/webapps/<SUPERVISOR_APP>/supervisord.conf file in a text editor. The file is a Windows INI-style configuration file. It contains many settings, some of which are optional. Lines containing text in brackets ([like_this]) are section headings; following lines are members of that section, until another section heading appears. Lines that are prefixed with a semicolon (;) are comments that do nothing.

  7. Comment out the entire [unix_http_server] section by prefixing each line with a semicolon.

  8. Uncomment the entire [inet_http_server] section by removing the preceding semicolons.

  9. In the [inet_http_server] section, change the following settings:

  10. Set port to, where XXXX is the port number assigned to your application in the control panel.
  11. Set username to the username of your choice.
  12. Set password to a strong password.

  13. In the [supervisord] section, change the following settings:

    • Set logfile to /home/<USERNAME>/logs/user/<SUPERVISOR_APP>.log, where <USERNAME> is your WebFaction username and <SUPERVISOR_APP> is the name of your application as it appears on the control panel.
    • Set pidfile to /home/<USERNAME>/webapps/<SUPERVISOR_APP>/supervisord.pid.
  14. In the [supervisorctl] section, change the following settings:

    • Set serverurl to, where XXXX is the port number assigned to your application in the control panel.
    • Uncomment and set username to the username of you chose previously.
    • Uncomment and set password to the password you chose previously.
  15. Save and close the file.

  16. With the WebFaction control panel, add your supervisord application to a website.

Test it out

Now that supervisord is installed and configured, let's make sure it's working.

  1. Start the supervisord daemon. Enter /home/<USERNAME>/bin/supervisord --configuration=/home/<USERNAME>/webapps/<SUPERVISOR_APP>/supervisord.conf and press Enter. Assuming there are no fatal problems, supervisord starts in the background and returns you to the command prompt.

  2. Check supervisord's status. Enter /home/<USERNAME>/bin/supervisorctl --configuration=/home/<USERNAME>/webapps/<SUPERVISOR_APP>/supervisord.conf and press Enter. If everything's working properly, the supervisor> prompt appears.

    Tip: Check out the available commands. Enter help and press Enter. To learn about specific commands, enter help <command> where <command> is the command you want to learn more about. Some important commands include: start, restart, and stop to control programs reload and shutdown to restart or stop the supervisord daemon itself * reread and update to respond to configuration file changes

  3. Exit supervisorctl. Enter exit and press Enter.

  4. Check out the web interface. Open the domain and URL path for your supervisord application and log in using the username and password you chose earlier.

Create a program

It's nice that we've got supervisord running, but it's not so useful without giving it a job to do. So let's add a basic program to get used to working with supervisord. Once you have the hang of it you can add more interesting programs.

  1. Reopen the supervisord.conf file.

  2. At the end of the file create a new [program:<NAME>] section, where <NAME> is a short, recognizable identifier for your program.

    I'm going to call mine catdemo, so I'll insert [program:catdemo].

  3. In the program section, add the configuration values for our program. There are many settings to choose from, including log file paths, environment variables, and more, but there is only one setting that's required: command. Set command to the command to start the program.

    For my catdemo program, I'll insert command=/bin/cat. So I have a section that looks like this:

    [program:catdemo] command=/bin/cat

    Tip: Use absolute paths where possible. Like cron jobs, supervisord programs typically run in a sparse environment that doesn't have your usual $PATH or other environment variables.

  4. Save and close the file.

  5. Force supervisord to reload your configuration file. Enter /home/<USERNAME>/bin/supervisorctl --configuration=/home/<USERNAME>/webapps/<SUPERVISOR_APP>/supervisord.conf update and press Enter.

Now your application will appear in supervisorctl's status list or in the web interface. You can also tell supervisord to start, restart, or stop your program.

Example: Keeping a Django app running

I admit that running cat continuously isn't useful. Let's repurpose our supervisor installation to keep a Django application up and running.

  1. Open supervisord.conf.
  2. Create a new program section that looks like this:

    [program:django] command=/home/<USERNAME>/webapps/<DJANGO_APP>/apache2/bin/httpd.worker -f /home/<USERNAME>/webapps/<DJANGO_APP>/apache2/conf/httpd.conf -DFOREGROUND environment=LD_LIBRARY_PATH="/home/<USERNAME>/webapps/<DJANGO_APP>/apache2/lib/"

    where <USERNAME> is your username and <DJANGO_APP> is the name of your Django application as it appears on the control panel.

    This configures supervisord to run httpd (the Apache web server) in the foreground (because supervisor expects foreground programs, not daemons). It's a bit like the start script you can find in your Django application's apache2/bin directory, but modified to work in the foreground and the way supervisor handles environment variables.

  3. Save and close the file.

Now supervisor is configured to run Django. But before we actually have supervisor start the application, let's make sure supervisor is going to be running the only instance of Django by removing Django from the crontab and stopping the existing Django instance.

  1. Edit your crontab. Enter crontab -e and press Enter.
  2. Delete the line containing ~/webapps/<DJANGO_APP>/apache2/bin/start.
  3. Save and close the file.
  4. Stop Django. Enter $HOME/webapps/<DJANGO_APP>/apache2/bin/stop and press Enter.

Now that Django's no longer running, let's have supervisor take over. Force supervisord to reload your configuration file. Enter /home/<USERNAME>/bin/supervisorctl --configuration=/home/<USERNAME>/webapps/<SUPERVISOR_APP>/supervisord.conf update and press Enter.

Finishing touches and additional resources

Once you're satisfied with the way supervisord is working, there's one last thing to do: make sure supervisord itself keeps running. Unfortunately, supervisord can't monitor itself, so if your machine reboots or supervisord crashes, you'll need to restart it. One way to do that is to create a cron job that will automatically start the supervisord daemon. Here's how to create a simple cron job that will restart supervisord every 30 minutes, if it's not already running:

  1. Enter crontab -e and press Enter.
  2. Append a new line containing */30 * * * * /home/<USERNAME>/bin/supervisord --configuration=/home/<USERNAME>/webapps/<SUPERVISOR_APP>/supervisord.conf > /dev/null 2>&1.
  3. Append another new line containing @reboot /home/<USERNAME>/bin/supervisord --configuration=/home/<USERNAME>/webapps/<SUPERVISOR_APP>/supervisord.conf > /dev/null 2>&1.
  4. Save and close the file.

For more information on using supervisor, please read its documentation. It contains more information about available commands, configuration options, and third-party add-ons. You may also be interested in "Using Supervisor for Fun and Profit", an introductory presentation about supervisor by its original author.

permanent link

answered 08 Apr '15, 21:42

ddbeck's gravatar image

accept rate: 100%

edited 20 Feb, 18:17

seanf's gravatar image

seanf ♦♦


Great, Great, Great! I hit a wall trying to get supervisor running after getting redis and celery up. Perfect walk through. Glad you included the web interface because a lot of other tutorials neglect it. Thanks!

(11 Feb '16, 01:33) ModernMarc ModernMarc's gravatar image

For cron, I needed to enter */30 * * * * instead of /30 * * * *. If it's a mistake correct it.

(29 Nov '16, 15:20) debiprasad debiprasad's gravatar image

In the section Example: Keeping a Django app running shouldn't LID_LIBRARY_PATH=... be LD_LIBRARY_PATH=...???

(17 Jan, 12:21) nik nik's gravatar image

In the section Example: Keeping a Django app running shouldn't LID_LIBRARY_PATH=... be LD_LIBRARY_PATH=...???

Yes, corrected.

(18 Jan, 21:51) seanf ♦♦ seanf's gravatar image

Last note. Shouldn't we add more line to crontab to restart supervisord on reboot like this: @reboot /home/<USERNAME>/bin/supervisord --configuration=...?

(20 Feb, 12:04) nik nik's gravatar image

Sure, done.

(20 Feb, 18:17) seanf ♦♦ seanf's gravatar image
showing 5 of 6 show 1 more comments

If you don't put: [unix_http_server] file=/path/to/supervisord.sock ; HTTP server listening on Unix domain socket ;username=username ;password=password

and you use httpok it will output in tail httpok stderr: xmlrpclib.ProtocolError: <protocolerror for="""" rpc2:="" 401="" unauthorized="">

if you also use crashmail it will send a message: subject: httpok crashed at 2016-12-25 10:20:54,988 Process httpok in group httpok exited unexpectedly (pid 9672) from state RUNNING


So unless someone wants to be a Grinch and write back saying this will blowup the server...

Happy, Merry, Joyous, New

permanent link

answered 25 Dec '16, 10:52

BigBuckBunny's gravatar image

accept rate: 0%

Your answer
toggle preview

Follow this question

By Email:

Once you sign in you will be able to subscribe for any updates here



Answers and Comments

Markdown Basics

  • *italic* or _italic_
  • **bold** or __bold__
  • link:[text](http://url.com/ "title")
  • image?![alt text](/path/img.jpg "title")
  • numbered list: 1. Foo 2. Bar
  • to add a line break simply add two spaces to where you would like the new line to be.
  • basic HTML tags are also supported

Question tags:


question asked: 08 Apr '15, 21:41

question was seen: 3,915 times

last updated: 20 Feb, 18:17