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:
[process:gunicorn]
cmd = gunicorn -w 3 test:app
cwd = /path/to/project
Then you can easily manage Gunicorn using Gaffer.
Using a Procfile
Create a Procfile
in your project:
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:
gaffer start
If gafferd is launched you can also load your Procfile in it directly:
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:
#!/bin/sh
GUNICORN=/usr/local/bin/gunicorn
ROOT=/path/to/project
PID=/var/run/gunicorn.pid
APP=main:application
if [ -f $PID ]; then rm $PID; fi
cd $ROOT
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:
[program:gunicorn]
command=/path/to/gunicorn main:application -c /path/to/gunicorn.conf.py
directory=/path/to/project
user=nobody
autostart=true
autorestart=true
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:
description "myapp"
start on (filesystem)
stop on runlevel [016]
respawn
setuid nobody
setgid nogroup
chdir /path/to/app/directory
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:
[Unit]
Description=gunicorn daemon
Requires=gunicorn.socket
After=network.target
[Service]
PIDFile=/run/gunicorn/pid
User=someuser
Group=someuser
RuntimeDirectory=gunicorn
WorkingDirectory=/home/someuser/applicationroot
ExecStart=/usr/bin/gunicorn --pid /run/gunicorn/pid \
--bind unix:/run/gunicorn/socket applicationname.wsgi
ExecReload=/bin/kill -s HUP $MAINPID
ExecStop=/bin/kill -s TERM $MAINPID
PrivateTmp=true
[Install]
WantedBy=multi-user.target
/etc/systemd/system/gunicorn.socket:
[Unit]
Description=gunicorn socket
[Socket]
ListenStream=/run/gunicorn/socket
[Install]
WantedBy=sockets.target
/etc/tmpfiles.d/gunicorn.conf:
d /run/gunicorn 0755 someuser somegroup -
Next enable the socket so it autostarts at boot:
systemctl enable gunicorn.socket
Either reboot, or start the services manually:
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:
...
http {
server {
listen 8000;
server_name 127.0.0.1;
location / {
proxy_pass http://unix:/run/gunicorn/socket;
}
}
}
...
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:
systemctl enable nginx.service
Either reboot, or start Nginx with the following command:
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.