diff --git a/contrib/gunicorn.conf b/contrib/gunicorn.conf new file mode 100644 index 000000000..929a8b9d9 --- /dev/null +++ b/contrib/gunicorn.conf @@ -0,0 +1,22 @@ +# 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 between gunicorn receiving a request and returning a response (or failing with a 500 error) +# +timeout=120 + +# ErrorLog +# ErrorLog is the logfile for the ErrorLog +# +errorlog='/usr/local/netbox/netbox.log' \ No newline at end of file diff --git a/contrib/netbox-rq.service b/contrib/netbox-rq.service index 7301e5571..4b364d6bc 100644 --- a/contrib/netbox-rq.service +++ b/contrib/netbox-rq.service @@ -12,9 +12,9 @@ EnvironmentFile=/etc/sysconfig/netbox.env User=www-data Group=www-data -WorkingDirectory=$WorkingDirectory +WorkingDirectory=${WorkingDirectory} -ExecStart=/usr/bin/python3 $WorkingDirectory/netbox/manage.py rqworker +ExecStart=/usr/bin/python3 ${WorkingDirectory}/netbox/manage.py rqworker Restart=on-failure RestartSec=30 diff --git a/contrib/netbox.env b/contrib/netbox.env index 733004f4f..c42e31a73 100644 --- a/contrib/netbox.env +++ b/contrib/netbox.env @@ -2,9 +2,9 @@ # Name = 'Netbox' -# GUExec is the gunicorn executable path +# ConfigPath is the path to the gunicorn config file. # -GUExec=/bin/gunicorn +ConfigPath=/usr/local/netbox/gunicorn.conf # WorkingDirectory is the Working Directory for Netbox. # @@ -12,32 +12,4 @@ 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 +PidPath=/usr/local/netbox/netbox.pid \ No newline at end of file diff --git a/contrib/netbox.service b/contrib/netbox.service index 2e46a34c9..76fb0e8ac 100644 --- a/contrib/netbox.service +++ b/contrib/netbox.service @@ -14,7 +14,7 @@ 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 +ExecStart=/usr/local/bin/gunicorn --pid ${PidPath} --pythonpath ${WorkingDirectory}/netbox --config ${ConfigPath} netbox.wsgi Restart=on-failure RestartSec=30 diff --git a/contrib/netbox@.service b/contrib/netbox@.service index 15a5d1886..d1ea96f57 100644 --- a/contrib/netbox@.service +++ b/contrib/netbox@.service @@ -14,7 +14,7 @@ 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 +ExecStart=/usr/local/bin/gunicorn --config ${ConfigPath} --pythonpath ${WorkingDirectory}/netbox netbox.wsgi Restart=on-failure RestartSec=30 diff --git a/docs/installation/3-http-daemon.md b/docs/installation/3-http-daemon.md index 1279aa77b..d9b3859c6 100644 --- a/docs/installation/3-http-daemon.md +++ b/docs/installation/3-http-daemon.md @@ -1,4 +1,4 @@ -We'll set up a simple WSGI front end using [gunicorn](http://gunicorn.org/) for the purposes of this guide. For web servers, we provide example configurations for both [nginx](https://www.nginx.com/resources/wiki/) and [Apache](http://httpd.apache.org/docs/2.4). (You are of course free to use whichever combination of HTTP and WSGI services you'd like.) We'll also use [supervisord](http://supervisord.org/) to enable service persistence. +We'll set up a simple WSGI front end using [gunicorn](http://gunicorn.org/) for the purposes of this guide. For web servers, we provide example configurations for both [nginx](https://www.nginx.com/resources/wiki/) and [Apache](http://httpd.apache.org/docs/2.4). (You are of course free to use whichever combination of HTTP and WSGI services you'd like.) We'll use systemd to enable service persistence. !!! info For the sake of brevity, only Ubuntu 18.04 instructions are provided here, but this sort of web server and WSGI configuration is not unique to NetBox. Please consult your distribution's documentation for assistance if needed. @@ -113,14 +113,14 @@ Install gunicorn: 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 +# cp -f contrib/netbox.service to /etc/systemd/system/netbox.service +# cp -f 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 +/usr/local/bin/gunicorn --pid ${PidPath} --pythonpath ${WorkingDirectory}/netbox --config ${ConfigPath} netbox.wsgi ``` ```no-highlight @@ -131,8 +131,7 @@ 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 +# cp -f 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. @@ -142,9 +141,9 @@ Edit /etc/sysconfig/netbox.env and change the settings as required. Update the # Name = 'Netbox' -# GUExec is the gunicorn executable path +# ConfigPath is the path to the gunicorn config file. # -GUExec=/bin/gunicorn +ConfigPath=/usr/local/netbox/gunicorn.conf # WorkingDirectory is the Working Directory for Netbox. # @@ -153,34 +152,40 @@ WorkingDirectory=/usr/local/netbox/ # PidPath is the path to the pid for the netbox WSGI # PidPath=/var/run/netbox.pid +``` +Copy contrib/gunicorn.conf to gunicorn.conf + +```no-highlight +# cp contrib/gunicorn.conf to gunicorn.conf +``` + +Edit gunicorn.conf and change the settings as required. + +``` # Bind is the ip and port that the Netbox WSGI should bind to # -Bind='127.0.0.1:8001' +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 +workers=3 # Threads # The number of threads for handling requests +# Threads should be: cores * 2 + 1. So if you have 4 cores, it would be 9. # -Threads=3 +threads=3 -# Timeout is the timeout +# Timeout is the timeout between gunicorn receiving a request and returning a response (or failing with a 500 error) # -Timeout=120 +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' +errorlog='/usr/local/netbox/netbox.log' ``` Then, restart the systemd daemon service to detect the netbox service and start the netbox service: @@ -191,7 +196,6 @@ Then, restart the systemd daemon service to detect the netbox service and start # systemctl enable netbox.service ``` - If using webhooks, also start the Redis worker: ```no-highlight diff --git a/docs/installation/migrating-to-systemd.md b/docs/installation/migrating-to-systemd.md index 69f7e198f..5c5020cee 100644 --- a/docs/installation/migrating-to-systemd.md +++ b/docs/installation/migrating-to-systemd.md @@ -1,5 +1,7 @@ # Migration +Migration is not required, as supervisord will still continue to function. + ## Ubuntu ### Remove supervisord: @@ -13,14 +15,14 @@ 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 +# cp -f contrib/netbox.service to /etc/systemd/system/netbox.service +# cp -f 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 +/usr/local/bin/gunicorn --pid ${PidPath} --pythonpath ${WorkingDirectory}/netbox --config ${ConfigPath} netbox.wsgi ``` ```no-highlight @@ -31,8 +33,7 @@ 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 +# cp -f 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. @@ -42,9 +43,9 @@ Edit /etc/sysconfig/netbox.env and change the settings as required. Update the # Name = 'Netbox' -# GUExec is the gunicorn executable path +# ConfigPath is the path to the gunicorn config file. # -GUExec=/bin/gunicorn +ConfigPath=/usr/local/netbox/gunicorn.conf # WorkingDirectory is the Working Directory for Netbox. # @@ -53,34 +54,39 @@ WorkingDirectory=/usr/local/netbox/ # PidPath is the path to the pid for the netbox WSGI # PidPath=/var/run/netbox.pid +``` +Copy contrib/gunicorn.conf to gunicorn.conf + +```no-highlight +# cp contrib/gunicorn.conf to gunicorn.conf +``` + +Edit gunicorn.conf and change the settings as required. + +``` # Bind is the ip and port that the Netbox WSGI should bind to # -Bind='127.0.0.1:8001' +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 +workers=3 # Threads # The number of threads for handling requests # -Threads=3 +threads=3 -# Timeout is the timeout +# Timeout is the timeout between gunicorn receiving a request and returning a response (or failing with a 500 error) # -Timeout=120 +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' +errorlog='/usr/local/netbox/netbox.log' ``` Then, restart the systemd daemon service to detect the netbox service and start the netbox service: diff --git a/docs/installation/upgrading.md b/docs/installation/upgrading.md index 85ae9aa02..963dc0cb1 100644 --- a/docs/installation/upgrading.md +++ b/docs/installation/upgrading.md @@ -80,7 +80,7 @@ This script: # Restart the WSGI Service -Finally, restart the WSGI service to run the new code. If you followed this guide for the initial installation, this is done using `supervisorctl`: +Finally, restart the WSGI service to run the new code. If you followed this guide for the initial installation, this is done using `systemctl: ```no-highlight # sudo systemctl restart netbox @@ -91,3 +91,6 @@ If using webhooks, also restart the Redis worker: ```no-highlight # sudo systemctl restart netbox-rqworker ``` + +!!! note + It's possible you are still using supervisord instead of the linux native systemd. If you are still using supervisord you can restart the services by either restarting supervisord or by using supervisorctl to restart netbox. \ No newline at end of file