From ae6316839becf8ccc47e09a823096700ac22eb66 Mon Sep 17 00:00:00 2001 From: dansheps Date: Fri, 15 Feb 2019 13:30:49 -0600 Subject: [PATCH] Closes #2902 - Migrate to systemd from supervisord --- CHANGELOG.md | 1 + contrib/netbox-rq.service | 24 ++++++ contrib/netbox.env | 43 ++++++++++ contrib/netbox.service | 24 ++++++ contrib/netbox@.service | 24 ++++++ docs/installation/3-http-daemon.md | 99 +++++++++++++++++------ docs/installation/index.md | 2 + docs/installation/migrating-to-systemd.md | 99 +++++++++++++++++++++++ docs/installation/upgrading.md | 4 +- 9 files changed, 295 insertions(+), 25 deletions(-) create mode 100644 contrib/netbox-rq.service create mode 100644 contrib/netbox.env create mode 100644 contrib/netbox.service create mode 100644 contrib/netbox@.service create mode 100644 docs/installation/migrating-to-systemd.md diff --git a/CHANGELOG.md b/CHANGELOG.md index eceb84f55..cf28a4a6b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,7 @@ v2.5.7 (FUTURE) ## Enhancements +* [#2902](https://github.com/digitalocean/netbox/issues/2902) - Replace supervisord with systemd * [#2357](https://github.com/digitalocean/netbox/issues/2357) - Enable filtering of devices by rack face * [#2903](https://github.com/digitalocean/netbox/issues/2903) - Clarify purpose of tags field on interface edit form diff --git a/contrib/netbox-rq.service b/contrib/netbox-rq.service new file mode 100644 index 000000000..7301e5571 --- /dev/null +++ b/contrib/netbox-rq.service @@ -0,0 +1,24 @@ +[Unit] +Description=Netbox RQ Worker +Documentation=https://netbox.readthedocs.io/en/stable/ +After=network-online.target +Wants=network-online.target + +[Service] +Type=simple + +EnvironmentFile=/etc/sysconfig/netbox.env + +User=www-data +Group=www-data + +WorkingDirectory=$WorkingDirectory + +ExecStart=/usr/bin/python3 $WorkingDirectory/netbox/manage.py rqworker + +Restart=on-failure +RestartSec=30 +PrivateTmp=true + +[Install] +WantedBy=multi-user.target diff --git a/contrib/netbox.env b/contrib/netbox.env new file mode 100644 index 000000000..733004f4f --- /dev/null +++ b/contrib/netbox.env @@ -0,0 +1,43 @@ +# Name is the Process Name +# +Name = 'Netbox' + +# GUExec is the gunicorn executable path +# +GUExec=/bin/gunicorn + +# WorkingDirectory is the Working Directory for Netbox. +# +WorkingDirectory=/usr/local/netbox/ + +# PidPath is the path to the pid for the netbox WSGI +# +PidPath=/var/run/netbox.pid + +# Bind is the ip and port that the Netbox WSGI should bind to +# +Bind='127.0.0.1:8001' + +# Workers is the number of workers that GUnicorn should spawn. +# Workers should be: cores * 2 + 1. So if you have 8 cores, it would be 17. +# +Workers=3 + +# Threads +# The number of threads for handling requests +# +Threads=3 + +# Timeout is the timeout +# +Timeout=120 + +# ErrorLog +# ErrorLog is the logfile for the ErrorLog +# +ErrorLog='/usr/local/netbox/netbox.log' + +# ExtraArgs +# ExtraArgs is a string of extra arguments for Gunicorn +# +ExtraArgs='--capture-output' \ No newline at end of file diff --git a/contrib/netbox.service b/contrib/netbox.service new file mode 100644 index 000000000..2e46a34c9 --- /dev/null +++ b/contrib/netbox.service @@ -0,0 +1,24 @@ +[Unit] +Description=Netbox WSGI +Documentation=https://netbox.readthedocs.io/en/stable/ +After=network-online.target +Wants=network-online.target + +[Service] +Type=simple + +EnvironmentFile=/etc/sysconfig/netbox.env + +User=www-data +Group=www-data +PIDFile=${PidPath} +WorkingDirectory=${WorkingDirectory} + +ExecStart=/usr/bin/gunicorn --pid ${PidPath} --bind ${Bind} --workers ${Workers} --threads ${Threads} --timeout ${Timeout} --error-log ${ErrorLog} --pythonpath ${WorkingDirectory}/netbox ${ExtraArgs} netbox.wsgi + +Restart=on-failure +RestartSec=30 +PrivateTmp=true + +[Install] +WantedBy=multi-user.target \ No newline at end of file diff --git a/contrib/netbox@.service b/contrib/netbox@.service new file mode 100644 index 000000000..15a5d1886 --- /dev/null +++ b/contrib/netbox@.service @@ -0,0 +1,24 @@ +[Unit] +Description=Netbox WSGI +Documentation=https://netbox.readthedocs.io/en/stable/ +After=network-online.target +Wants=network-online.target + +[Service] +Type=simple + +EnvironmentFile=/etc/sysconfig/netbox.%i.env + +User=www-data +Group=www-data +PIDFile=${PidPath} +WorkingDirectory=${WorkingDirectory} + +ExecStart=/usr/bin/gunicorn --pid ${PidPath} --bind ${Bind} --workers ${Workers} --threads ${Threads} --timeout ${Timeout} --error-log ${ErrorLog} --pythonpath ${WorkingDirectory}/netbox ${ExtraArgs} netbox.wsgi + +Restart=on-failure +RestartSec=30 +PrivateTmp=true + +[Install] +WantedBy=multi-user.target \ No newline at end of file diff --git a/docs/installation/3-http-daemon.md b/docs/installation/3-http-daemon.md index dcf16101e..1279aa77b 100644 --- a/docs/installation/3-http-daemon.md +++ b/docs/installation/3-http-daemon.md @@ -108,42 +108,95 @@ Install gunicorn: # pip3 install gunicorn ``` -Save the following configuration in the root netbox installation path as `gunicorn_config.py` (e.g. `/opt/netbox/gunicorn_config.py` per our example installation). Be sure to verify the location of the gunicorn executable on your server (e.g. `which gunicorn`) and to update the `pythonpath` variable if needed. If using CentOS/RHEL, change the username from `www-data` to `nginx` or `apache`. +# systemd configuration + +Copy or link contrib/netbox.service and contrib/netbox-rq.service to /etc/systemd/system/netbox.service and /etc/systemd/system/netbox-rq.service ```no-highlight -command = '/usr/bin/gunicorn' -pythonpath = '/opt/netbox/netbox' -bind = '127.0.0.1:8001' -workers = 3 -user = 'www-data' +# copy contrib/netbox.service to /etc/systemd/system/netbox.service +# copy contrib/netbox-rq.service to /etc/systemd/system/netbox-rq.service ``` -# supervisord Installation - -Install supervisor: +Edit /etc/systemd/system/netbox.service and /etc/systemd/system/netbox-rq.service Be sure to verify the location of the gunicorn executable on your server (e.g. `which gunicorn`). If using CentOS/RHEL. Change the username from `www-data` to `nginx` or `apache`: ```no-highlight -# apt-get install -y supervisor +/usr/bin/gunicorn --pid ${PidPath} --bind ${Bind} --workers ${Workers} --threads ${Threads} --timeout ${Timeout} --error-log ${ErrorLog} --pythonpath ${WorkingDirectory}/netbox ${ExtraArgs} netbox.wsgi ``` -Save the following as `/etc/supervisor/conf.d/netbox.conf`. Update the `command` and `directory` paths as needed. If using CentOS/RHEL, change the username from `www-data` to `nginx` or `apache`. - ```no-highlight -[program:netbox] -command = gunicorn -c /opt/netbox/gunicorn_config.py netbox.wsgi -directory = /opt/netbox/netbox/ -user = www-data - -[program:netbox-rqworker] -command = python3 /opt/netbox/netbox/manage.py rqworker -directory = /opt/netbox/netbox/ -user = www-data +User=www-data +Group=www-data ``` -Then, restart the supervisor service to detect and run the gunicorn service: +Copy contrib/netbox.env to /etc/sysconfig/netbox.env ```no-highlight -# service supervisor restart +# mkdir /etc/sysconfig/netbox.env +# copy contrib/netbox.env to /etc/sysconfig/netbox.env +``` + +Edit /etc/sysconfig/netbox.env and change the settings as required. Update the `WorkingDirectory` variable if needed. + +```no-highlight +# Name is the Process Name +# +Name = 'Netbox' + +# GUExec is the gunicorn executable path +# +GUExec=/bin/gunicorn + +# WorkingDirectory is the Working Directory for Netbox. +# +WorkingDirectory=/usr/local/netbox/ + +# PidPath is the path to the pid for the netbox WSGI +# +PidPath=/var/run/netbox.pid + +# Bind is the ip and port that the Netbox WSGI should bind to +# +Bind='127.0.0.1:8001' + +# Workers is the number of workers that GUnicorn should spawn. +# Workers should be: cores * 2 + 1. So if you have 8 cores, it would be 17. +# +Workers=3 + +# Threads +# The number of threads for handling requests +# +Threads=3 + +# Timeout is the timeout +# +Timeout=120 + +# ErrorLog +# ErrorLog is the logfile for the ErrorLog +# +ErrorLog='/usr/local/netbox/netbox.log' + +# ExtraArgs +# ExtraArgs is a string of extra arguments for Gunicorn +# +ExtraArgs='--capture-output' +``` + +Then, restart the systemd daemon service to detect the netbox service and start the netbox service: + +```no-highlight +# systemctl daemon-reload +# systemctl start netbox.service +# systemctl enable netbox.service +``` + + +If using webhooks, also start the Redis worker: + +```no-highlight +# systemctl start netbox-rq.service +# systemctl enable netbox-rq.service ``` At this point, you should be able to connect to the nginx HTTP service at the server name or IP address you provided. If you are unable to connect, check that the nginx service is running and properly configured. If you receive a 502 (bad gateway) error, this indicates that gunicorn is misconfigured or not running. diff --git a/docs/installation/index.md b/docs/installation/index.md index 54daa62e3..9b780391a 100644 --- a/docs/installation/index.md +++ b/docs/installation/index.md @@ -12,3 +12,5 @@ The following sections detail how to set up a new instance of NetBox: If you are upgrading from an existing installation, please consult the [upgrading guide](upgrading.md). NetBox v2.5 and later requires Python 3.5 or higher. Please see the instructions for [migrating to Python 3](migrating-to-python3.md) if you are still using Python 2. + +Netbox v2.5.7 and later moved to using systemd instead of supervisord. Please see the instructions for [migrating to systemd](migrating-to-systemd.md) if you are still using supervisord. diff --git a/docs/installation/migrating-to-systemd.md b/docs/installation/migrating-to-systemd.md new file mode 100644 index 000000000..69f7e198f --- /dev/null +++ b/docs/installation/migrating-to-systemd.md @@ -0,0 +1,99 @@ +# Migration + +## Ubuntu + +### Remove supervisord: + +```no-highlight +# apt-get remove -y supervisord +``` + +### systemd configuration: + +Copy or link contrib/netbox.service and contrib/netbox-rq.service to /etc/systemd/system/netbox.service and /etc/systemd/system/netbox-rq.service + +```no-highlight +# copy contrib/netbox.service to /etc/systemd/system/netbox.service +# copy contrib/netbox-rq.service to /etc/systemd/system/netbox-rq.service +``` + +Edit /etc/systemd/system/netbox.service and /etc/systemd/system/netbox-rq.service. Be sure to verify the location of the gunicorn executable on your server (e.g. `which gunicorn`). If using CentOS/RHEL. Change the username from `www-data` to `nginx` or `apache`: + +```no-highlight +/usr/bin/gunicorn --pid ${PidPath} --bind ${Bind} --workers ${Workers} --threads ${Threads} --timeout ${Timeout} --error-log ${ErrorLog} --pythonpath ${WorkingDirectory}/netbox ${ExtraArgs} netbox.wsgi +``` + +```no-highlight +User=www-data +Group=www-data +``` + +Copy contrib/netbox.env to /etc/sysconfig/netbox.env + +```no-highlight +# mkdir /etc/sysconfig/netbox.env +# copy contrib/netbox.env to /etc/sysconfig/netbox.env +``` + +Edit /etc/sysconfig/netbox.env and change the settings as required. Update the `WorkingDirectory` variable if needed. + +```no-highlight +# Name is the Process Name +# +Name = 'Netbox' + +# GUExec is the gunicorn executable path +# +GUExec=/bin/gunicorn + +# WorkingDirectory is the Working Directory for Netbox. +# +WorkingDirectory=/usr/local/netbox/ + +# PidPath is the path to the pid for the netbox WSGI +# +PidPath=/var/run/netbox.pid + +# Bind is the ip and port that the Netbox WSGI should bind to +# +Bind='127.0.0.1:8001' + +# Workers is the number of workers that GUnicorn should spawn. +# Workers should be: cores * 2 + 1. So if you have 8 cores, it would be 17. +# +Workers=3 + +# Threads +# The number of threads for handling requests +# +Threads=3 + +# Timeout is the timeout +# +Timeout=120 + +# ErrorLog +# ErrorLog is the logfile for the ErrorLog +# +ErrorLog='/usr/local/netbox/netbox.log' + +# ExtraArgs +# ExtraArgs is a string of extra arguments for Gunicorn +# +ExtraArgs='--capture-output' +``` + +Then, restart the systemd daemon service to detect the netbox service and start the netbox service: + +```no-highlight +# systemctl daemon-reload +# systemctl start netbox.service +# systemctl enable netbox.service +``` + +If using webhooks, also start the Redis worker: + +```no-highlight +# systemctl start netbox-rq.service +# systemctl enable netbox-rq.service +``` \ No newline at end of file diff --git a/docs/installation/upgrading.md b/docs/installation/upgrading.md index 6dc8a3c7a..85ae9aa02 100644 --- a/docs/installation/upgrading.md +++ b/docs/installation/upgrading.md @@ -83,11 +83,11 @@ This script: Finally, restart the WSGI service to run the new code. If you followed this guide for the initial installation, this is done using `supervisorctl`: ```no-highlight -# sudo supervisorctl restart netbox +# sudo systemctl restart netbox ``` If using webhooks, also restart the Redis worker: ```no-highlight -# sudo supervisorctl restart netbox-rqworker +# sudo systemctl restart netbox-rqworker ```