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:
- SSH to your app server.
- Set up your source code connection (e.g. github credentials).
- Create the directory for your app app:
mkdir -p /cryptdata/var/deploy/app
- Check out your code into a directory called
git clone email@example.com:MyCompany/myrepo.git current
app/currentallows you to create a version-directory system in the future if desired.)
- You should now have your source code in the directory
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.
- Create a script that sets up the path and runs your app (do not daemonize).
- Save the script in the root of your source code repository (e.g.
- Check the script into your source code repository.
Example: shell script to run Rails
Call this script
#!/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.
- Create a directory called
configin the root of your source code repository:
- Create a supervisor config file called
- 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
commandis the shell script that supervisor will run to start the app.
directoryis the path to the root of the app.
autorestartare 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.
- Read a supervisor config file or updated config file:
- Apply the updated configuration to all running apps:
supervisorctl updateand 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.