Like most Django applications, NetBox runs as a WSGI application behind an HTTP server. This documentation shows how to install and configure gunicorn (which is automatically installed with NetBox) for this role, however other WSGI servers are available and should work similarly well. uWSGI is a popular alternative.
NetBox ships with a default configuration file for gunicorn. To use it, copy
/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.)
sudo cp /opt/netbox/contrib/gunicorn.py /opt/netbox/gunicorn.py
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 Gunicorn documentation for the available configuration parameters.
We'll use systemd to control both gunicorn and NetBox's background worker process. First, copy
contrib/netbox-rq.service to the
/etc/systemd/system/ directory and reload the systemd daemon.
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.
sudo cp -v /opt/netbox/contrib/*.service /etc/systemd/system/
sudo systemctl daemon-reload
Then, start the
netbox-rq services and enable them to initiate at boot time:
sudo systemctl start netbox netbox-rq
sudo systemctl enable netbox netbox-rq
You can use the command
systemctl status netbox to verify that the WSGI service is running:
systemctl status netbox.service
You should see output similar to the following:
● netbox.service - NetBox WSGI Service
Loaded: loaded (/etc/systemd/system/netbox.service; enabled; vendor preset: enabled)
Active: active (running) since Mon 2021-08-30 04:02:36 UTC; 14h ago
Main PID: 1140492 (gunicorn)
Tasks: 19 (limit: 4683)
├─1140492 /opt/netbox/venv/bin/python3 /opt/netbox/venv/bin/gunicorn --pid /va>
├─1140513 /opt/netbox/venv/bin/python3 /opt/netbox/venv/bin/gunicorn --pid /va>
├─1140514 /opt/netbox/venv/bin/python3 /opt/netbox/venv/bin/gunicorn --pid /va>
If the NetBox service fails to start, issue the command
journalctl -eu netbox to check for log messages that may indicate the problem.
Once you've verified that the WSGI workers are up and running, move on to HTTP server setup.
There is a bug in the current stable release of gunicorn (v21.2.0) where automatic restarts of the worker processes can result in 502 errors under heavy load. (See gunicorn bug #3038 for more detail.) Users who encounter this issue may opt to downgrade to an earlier, unaffected release of gunicorn (
pip install gunicorn==20.1.0). Note, however, that this earlier release does not officially support Python 3.11.