How to use supervisor

Supervisord is a process-management tool with the following advantages:

  • It allows you to keep your app running no matter what happens. For example it will restart your app if the VM reboots.
  • Supervisor allows you to manage multiple processes and workers.
  • It integrates well with our git push-to-deploy pipeline.

We will go through the process to set up supervisor and provide examples for running a Rails app. Running other types of apps will be similar.

Tell us where you will be putting your supervisor configuration file

We need to know where your supervisor configuration file is going to be located. A suggested location is /cryptdata/var/deploy/app/current/config/app_supervisor.conf. Provide us with the full path.

Check out your source code repository onto your server

First, we will set up the standard directory structure, and then you will check out your app:

  1. SSH to your app server.
  2. Set up your source code connection (e.g. github credentials).
  3. Create the directory for your app app: mkdir -p /cryptdata/var/deploy/app
  4. cd /cryptdata/var/deploy/app
  5. Check out your code into a directory called current: git clone git@github.com:MyCompany/myrepo.git current
    1. (Using app/current allows you to create a version-directory system in the future if desired.)
  6. You should now have your source code in the directory /cryptdata/var/deploy/app/current/

Create a shell script that runs your app

Due to the way that supervisor handles the environment, it is much easier to reliably run your app from a shell script that configures the correct path and any other useful environment variables.

  1. Create a script that sets up the path and runs your app (do not daemonize).
  2. Save the script in the root of your source code repository (e.g. /cryptdata/var/deploy/app/current/run_my_app.sh
  3. Check the script into your source code repository.

Example: shell script to run Rails

Call this script run_rails.sh:

#!/bin/bash -e

PATH="/cryptdata/var/deploy/.rbenv/shims:/cryptdata/var/deploy/.rbenv/bin:$PATH"
eval "$(rbenv init -)"
RAILS_ENV=staging bin/rails server

Create a supervisord configuration file

The supervisor configuration file defines one or more "programs" which you use to define the processes that you want running.

Note: For detailed documentation: please read the official  Supervisord configuration documentation.

  1. Create a directory called config in the root of your source code repository:
    1. mkdir /cryptdata/var/deploy/app/current/config
  2. Create a supervisor config file called app_supervisor.conf
    1. touch /cryptdata/var/deploy/app/current/config/app_supervisor.conf<br>
  3. Check this file into your source code repository.

Example: app_supervisor.conf for Rails

Here is an simple example  app_supervisor.conf that run a Rails server.

[program:rails]
command=/cryptdata/var/deploy/app/current/run_rails.sh
user=deploy
directory=/cryptdata/var/deploy/app/current
environment=HOME="/cryptdata/var/deploy"
stdout_logfile=/cryptdata/var/deploy/app/current/log/staging.log
stderr_logfile=/cryptdata/var/deploy/app/current/log/staging.log
autostart=true
autorestart=true

What this does:

  • The program is called  program:rails, so it can be controlled using e.g.  supervisorctl restart rails
  •  command is the shell script that supervisor will run to start the app.
  •  directory is the path to the root of the app.
  •  autostart and autorestart are set to true so that the app will start up automatically if the VM is restarted.
  • Log file directories are specified.

Note: You need to create  the paths for the app and the logs before you run supervisor.

Other languages: You can substitute other commands for other app frameworks such as Node.js, Python, Java, etc. and there are many examples available online.

Run supervisorctl

Although supervisor normally requires root to run, we have configured it so that you can safely run it using your deployment user.
Note For detailed documentation: please read the official doc  Running Supervisor.
The standard workflow that you can perform manually or in a deployment script is:
  1. Read a supervisor config file or updated config file: supervisorctl reread
  2. Apply the updated configuration to all running apps: supervisorctl update and then: supervisorctl start all

If you have a deployment script, you can include those three commands at the end of your script and they will update and restart all programs.

Still need help? Contact Us Contact Us