From 5cbdbc8cd0cc8a17071f0b1c732eab8cbc5bce67 Mon Sep 17 00:00:00 2001 From: Jeremy Stretch Date: Thu, 28 Mar 2024 15:02:46 -0400 Subject: [PATCH] Restructure gunicorn/uWSGI installation docs --- contrib/netbox.service | 4 ++++ contrib/nginx.conf | 4 +++- contrib/{uwsgi => }/uwsgi.ini | 0 contrib/uwsgi/netbox.service | 22 ----------------- .../{4-gunicorn.md => 4a-gunicorn.md} | 7 ++++-- docs/installation/{uwsgi.md => 4b-uwsgi.md} | 24 +++++++++++++------ docs/installation/5-http-server.md | 3 +++ mkdocs.yml | 3 ++- 8 files changed, 34 insertions(+), 33 deletions(-) rename contrib/{uwsgi => }/uwsgi.ini (100%) delete mode 100644 contrib/uwsgi/netbox.service rename docs/installation/{4-gunicorn.md => 4a-gunicorn.md} (83%) rename docs/installation/{uwsgi.md => 4b-uwsgi.md} (66%) diff --git a/contrib/netbox.service b/contrib/netbox.service index 3cd02d988..8c602fa5b 100644 --- a/contrib/netbox.service +++ b/contrib/netbox.service @@ -12,8 +12,12 @@ Group=netbox PIDFile=/var/tmp/netbox.pid WorkingDirectory=/opt/netbox +# Remove the following line if using uWSGI instead of Gunicorn ExecStart=/opt/netbox/venv/bin/gunicorn --pid /var/tmp/netbox.pid --pythonpath /opt/netbox/netbox --config /opt/netbox/gunicorn.py netbox.wsgi +# Uncomment the following line if using uWSGI instead of Gunicorn +#ExecStart=/opt/netbox/venv/bin/uwsgi --ini /opt/netbox/uwsgi.ini + Restart=on-failure RestartSec=30 PrivateTmp=true diff --git a/contrib/nginx.conf b/contrib/nginx.conf index 67db188e3..31d026e0d 100644 --- a/contrib/nginx.conf +++ b/contrib/nginx.conf @@ -14,11 +14,13 @@ server { } location / { + # Remove these lines if using uWSGI instead of Gunicorn proxy_pass http://127.0.0.1:8001; proxy_set_header X-Forwarded-Host $http_host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-Proto $scheme; - # comment the lines above and uncomment the lines below if using uWSGI + + # Uncomment these lines if using uWSGI instead of Gunicorn # include uwsgi_params; # uwsgi_pass 127.0.0.1:8001; # uwsgi_param Host $host; diff --git a/contrib/uwsgi/uwsgi.ini b/contrib/uwsgi.ini similarity index 100% rename from contrib/uwsgi/uwsgi.ini rename to contrib/uwsgi.ini diff --git a/contrib/uwsgi/netbox.service b/contrib/uwsgi/netbox.service deleted file mode 100644 index 161a97e1b..000000000 --- a/contrib/uwsgi/netbox.service +++ /dev/null @@ -1,22 +0,0 @@ -[Unit] -Description=NetBox WSGI Service -Documentation=https://docs.netbox.dev/ -After=network-online.target -Wants=network-online.target - -[Service] -Type=simple - -User=netbox -Group=netbox -PIDFile=/var/tmp/netbox.pid -WorkingDirectory=/opt/netbox - -ExecStart=/opt/netbox/venv/bin/uwsgi --ini /opt/netbox/uwsgi.ini - -Restart=on-failure -RestartSec=30 -PrivateTmp=true - -[Install] -WantedBy=multi-user.target diff --git a/docs/installation/4-gunicorn.md b/docs/installation/4a-gunicorn.md similarity index 83% rename from docs/installation/4-gunicorn.md rename to docs/installation/4a-gunicorn.md index 2d9b3026b..3aca4ef0e 100644 --- a/docs/installation/4-gunicorn.md +++ b/docs/installation/4a-gunicorn.md @@ -1,10 +1,13 @@ # Gunicorn -Like most Django applications, NetBox runs as a [WSGI application](https://en.wikipedia.org/wiki/Web_Server_Gateway_Interface) behind an HTTP server. This documentation shows how to install and configure [gunicorn](http://gunicorn.org/) (which is automatically installed with NetBox) for this role, however other WSGI servers are available and should work similarly well. [uWSGI](https://uwsgi-docs.readthedocs.io/en/latest/) is a popular alternative and [installation instructions for uWSGI](uwsgi.md) are provided if you wish to use that instead of gunicorn. +!!! tip + This page provides instructions for setting up the [gunicorn](http://gunicorn.org/) WSGI server. If you plan to use [uWSGI](https://uwsgi-docs.readthedocs.io/en/latest/) instead, go [here](./4b-uwsgi.md). + +NetBox runs as a [WSGI application](https://en.wikipedia.org/wiki/Web_Server_Gateway_Interface) behind an HTTP server. This documentation shows how to install and configure [gunicorn](http://gunicorn.org/) (which is automatically installed with NetBox) for this role, however other WSGI servers are available and should work similarly well. ## Configuration -NetBox ships with a default configuration file for gunicorn. To use it, copy `/opt/netbox/contrib/gunicorn.py` to `/opt/netbox/gunicorn.py`. (We make a copy of this file rather than pointing to it directly to ensure that any local changes to it do not get overwritten by a future upgrade.) +NetBox ships with a default configuration file for gunicorn. To use it, copy `/opt/netbox/contrib/gunicorn.py` to `/opt/netbox/gunicorn.py`. (We make a copy of this file rather than pointing to it directly to ensure that any local changes to it do not get overwritten during a future NetBox upgrade.) ```no-highlight sudo cp /opt/netbox/contrib/gunicorn.py /opt/netbox/gunicorn.py diff --git a/docs/installation/uwsgi.md b/docs/installation/4b-uwsgi.md similarity index 66% rename from docs/installation/uwsgi.md rename to docs/installation/4b-uwsgi.md index 39f1a4181..3b7b5f76c 100644 --- a/docs/installation/uwsgi.md +++ b/docs/installation/4b-uwsgi.md @@ -1,6 +1,9 @@ # uWSGI -Like most Django applications, NetBox runs as a [WSGI application](https://en.wikipedia.org/wiki/Web_Server_Gateway_Interface) behind an HTTP server. This documentation shows how to install and configure [uWSGI](https://uwsgi-docs.readthedocs.io/en/latest/) for this role, however other WSGI servers are available and should work similarly well. [gunicorn](http://gunicorn.org/) is a popular alternative and [installation instructions for gunicorn](4-gunicorn.md) are provided if you wish to use that instead of uWSGI. +!!! tip + This page provides instructions for setting up the [uWSGI](https://uwsgi-docs.readthedocs.io/) WSGI server. If you plan to use [gunicorn](http://gunicorn.org/) instead, go [here](./4a-gunicorn.md). + +NetBox runs as a [WSGI application](https://en.wikipedia.org/wiki/Web_Server_Gateway_Interface) behind an HTTP server. This documentation shows how to install and configure [uWSGI](https://uwsgi-docs.readthedocs.io/en/latest/) for this role, however other WSGI servers are available and should work similarly well. ## Installation @@ -19,24 +22,31 @@ sudo sh -c "echo 'pyuwgsi' >> /opt/netbox/local_requirements.txt" ## Configuration -NetBox ships with a default configuration file for uWSGI. To use it, copy `/opt/netbox/contrib/uwsgi/uwsgi.ini` to `/opt/netbox/uwsgi.ini`. (We make a copy of this file rather than pointing to it directly to ensure that any local changes to it do not get overwritten by a future upgrade.) +NetBox ships with a default configuration file for uWSGI. To use it, copy `/opt/netbox/contrib/uwsgi.ini` to `/opt/netbox/uwsgi.ini`. (We make a copy of this file rather than pointing to it directly to ensure that any local changes to it do not get overwritten during a future NetBox upgrade.) ```no-highlight -sudo cp /opt/netbox/contrib/uwsgi/uwsgi.ini /opt/netbox/uwsgi.ini +sudo cp /opt/netbox/contrib/uwsgi.ini /opt/netbox/uwsgi.ini ``` -While the provided configuration should suffice for most initial installations, you may wish to edit this file to change the bound IP address and/or port number, or to make performance-related adjustments. See [the uWSGI documentation](https://uwsgi-docs-additions.readthedocs.io/en/latest/Options.html) for the available configuration parameters and check the [Things to know](https://uwsgi-docs.readthedocs.io/en/latest/ThingsToKnow.html) page in the uWSGI documentation. Django also provides [additional documentation](https://docs.djangoproject.com/en/5.0/howto/deployment/wsgi/uwsgi/) on configuring uWSGI with a Django app. +While the provided configuration should suffice for most initial installations, you may wish to edit this file to change the bound IP address and/or port number, or to make performance-related adjustments. See [the uWSGI documentation](https://uwsgi-docs-additions.readthedocs.io/en/latest/Options.html) for the available configuration parameters and take a minute to review the [Things to know](https://uwsgi-docs.readthedocs.io/en/latest/ThingsToKnow.html) page. Django also provides [additional documentation](https://docs.djangoproject.com/en/5.0/howto/deployment/wsgi/uwsgi/) on configuring uWSGI with a Django app. ## systemd Setup -We'll use systemd to control both uWSGI and NetBox's background worker process. First, copy `contrib/uwsgi/netbox.service` and `contrib/netbox-rq.service` to the `/etc/systemd/system/` directory and reload the systemd daemon. +We'll use systemd to control both uWSGI and NetBox's background worker process. First, copy `contrib/netbox.service` and `contrib/netbox-rq.service` to the `/etc/systemd/system/` directory. + +```no-highlight +sudo cp -v /opt/netbox/contrib/*.service /etc/systemd/system/ +sudo systemctl daemon-reload +``` + +The reference configuration assumes that gunicorn is in use, so we need to update it. Edit the `netbox.service` file to remove the line beginning with `ExecStart=/opt/netbox/venv/bin/gunicorn` and uncomment the line below it. !!! warning "Check user & group assignment" The stock service configuration files packaged with NetBox assume that the service will run with the `netbox` user and group names. If these differ on your installation, be sure to update the service files accordingly. +Once the configuration file has been saved, reload the service: + ```no-highlight -sudo cp -v /opt/netbox/contrib/netbox-rq.service /etc/systemd/system/ -sudo cp -v /opt/netbox/contrib/uwsgi/netbox.service /etc/systemd/system/ sudo systemctl daemon-reload ``` diff --git a/docs/installation/5-http-server.md b/docs/installation/5-http-server.md index b81c6d84a..7496d3bf4 100644 --- a/docs/installation/5-http-server.md +++ b/docs/installation/5-http-server.md @@ -35,6 +35,9 @@ Once nginx is installed, copy the nginx configuration file provided by NetBox to sudo cp /opt/netbox/contrib/nginx.conf /etc/nginx/sites-available/netbox ``` +!!! tip "gunicorn vs. uWSGI" + The reference nginx configuration file assumes that gunicorn is in use. If using uWSGI instead, you'll need to remove the gunicorn-specific configuration (lines beginning with `proxy_pass` and `proxy_set_header`) and uncomment the uWSGI section below them before proceeding. + Then, delete `/etc/nginx/sites-enabled/default` and create a symlink in the `sites-enabled` directory to the configuration file you just created. ```no-highlight diff --git a/mkdocs.yml b/mkdocs.yml index 354c10608..c17354db9 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -94,7 +94,8 @@ nav: - 1. PostgreSQL: 'installation/1-postgresql.md' - 2. Redis: 'installation/2-redis.md' - 3. NetBox: 'installation/3-netbox.md' - - 4. Gunicorn: 'installation/4-gunicorn.md' + - 4a. Gunicorn: 'installation/4a-gunicorn.md' + - 4b. uWSGI: 'installation/4b-uwsgi.md' - 5. HTTP Server: 'installation/5-http-server.md' - 6. LDAP (Optional): 'installation/6-ldap.md' - Upgrading NetBox: 'installation/upgrading.md'