Restructure gunicorn/uWSGI installation docs

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

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;

contrib/uwsgi/netbox.service

@@ -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

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

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
 ```
 

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

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'