Monitoring

Note

Make sure that when using either of these service monitors you do not enable the Gunicorn’s daemon mode. These monitors expect that the process they launch will be the process they need to monitor. Daemonizing will fork-exec which creates an unmonitored process and generally just confuses the monitor services.

Gaffer

Using Gafferd and gaffer

Gaffer can be used to monitor Gunicorn. A simple configuration is:

  1. [process:gunicorn]
  2. cmd = gunicorn -w 3 test:app
  3. cwd = /path/to/project

Then you can easily manage Gunicorn using Gaffer.

Using a Procfile

Create a Procfile in your project:

  1. gunicorn = gunicorn -w 3 test:app

You can launch any other applications that should be launched at the same time.

Then you can start your Gunicorn application using Gaffer:

  1. gaffer start

If gafferd is launched you can also load your Procfile in it directly:

  1. gaffer load

All your applications will be then supervised by gafferd.

Runit

A popular method for deploying Gunicorn is to have it monitored by runit. Here is an example service definition:

  1. #!/bin/sh
  2. GUNICORN=/usr/local/bin/gunicorn
  3. ROOT=/path/to/project
  4. PID=/var/run/gunicorn.pid
  5. APP=main:application
  6. if [ -f $PID ]; then rm $PID; fi
  7. cd $ROOT
  8. exec $GUNICORN -c $ROOT/gunicorn.conf.py --pid=$PID $APP

Save this as /etc/sv/[app_name]/run, and make it executable (chmod u+x /etc/sv/[app_name]/run). Then run ln -s /etc/sv/[app_name] /etc/service/[app_name]. If runit is installed, Gunicorn should start running automatically as soon as you create the symlink.

If it doesn’t start automatically, run the script directly to troubleshoot.

Supervisor

Another useful tool to monitor and control Gunicorn is Supervisor. A simple configuration is:

  1. [program:gunicorn]
  2. command=/path/to/gunicorn main:application -c /path/to/gunicorn.conf.py
  3. directory=/path/to/project
  4. user=nobody
  5. autostart=true
  6. autorestart=true
  7. redirect_stderr=true

Upstart

Using Gunicorn with upstart is simple. In this example we will run the app “myapp” from a virtualenv. All errors will go to /var/log/upstart/myapp.log.

/etc/init/myapp.conf:

  1. description "myapp"
  2. start on (filesystem)
  3. stop on runlevel [016]
  4. respawn
  5. setuid nobody
  6. setgid nogroup
  7. chdir /path/to/app/directory
  8. exec /path/to/virtualenv/bin/gunicorn myapp:app

Systemd

A tool that is starting to be common on linux systems is Systemd. Below are configurations files and instructions for using systemd to create a unix socket for incoming Gunicorn requests. Systemd will listen on this socket and start gunicorn automatically in response to traffic. Later in this section are instructions for configuring Nginx to forward web traffic to the newly created unix socket:

/etc/systemd/system/gunicorn.service:

  1. [Unit]
  2. Description=gunicorn daemon
  3. Requires=gunicorn.socket
  4. After=network.target
  5. [Service]
  6. PIDFile=/run/gunicorn/pid
  7. User=someuser
  8. Group=someuser
  9. RuntimeDirectory=gunicorn
  10. WorkingDirectory=/home/someuser/applicationroot
  11. ExecStart=/usr/bin/gunicorn --pid /run/gunicorn/pid \
  12. --bind unix:/run/gunicorn/socket applicationname.wsgi
  13. ExecReload=/bin/kill -s HUP $MAINPID
  14. ExecStop=/bin/kill -s TERM $MAINPID
  15. PrivateTmp=true
  16. [Install]
  17. WantedBy=multi-user.target

/etc/systemd/system/gunicorn.socket:

  1. [Unit]
  2. Description=gunicorn socket
  3. [Socket]
  4. ListenStream=/run/gunicorn/socket
  5. [Install]
  6. WantedBy=sockets.target

/etc/tmpfiles.d/gunicorn.conf:

  1. d /run/gunicorn 0755 someuser somegroup -

Next enable the socket so it autostarts at boot:

  1. systemctl enable gunicorn.socket

Either reboot, or start the services manually:

  1. systemctl start gunicorn.socket

After running curl --unix-socket /run/gunicorn/socket http, Gunicorn should start and you should see some HTML from your server in the terminal.

You must now configure your web proxy to send traffic to the new Gunicorn socket. Edit your nginx.conf to include the following:

/etc/nginx/nginx.conf:

  1. ...
  2. http {
  3. server {
  4. listen 8000;
  5. server_name 127.0.0.1;
  6. location / {
  7. proxy_pass http://unix:/run/gunicorn/socket;
  8. }
  9. }
  10. }
  11. ...

Note

The listen and server_name used here are configured for a local machine. In a production server you will most likely listen on port 80, and use your URL as the server_name.

Now make sure you enable the nginx service so it automatically starts at boot:

  1. systemctl enable nginx.service

Either reboot, or start Nginx with the following command:

  1. systemctl start nginx

Now you should be able to test Nginx with Gunicorn by visiting http://127.0.0.1:8000/ in any web browser. Systemd is now set up.