diff --git a/contrib/netbox.service b/contrib/netbox.service index 3cd02d988..af6a6d988 100644 --- a/contrib/netbox.service +++ b/contrib/netbox.service @@ -12,7 +12,7 @@ Group=netbox PIDFile=/var/tmp/netbox.pid WorkingDirectory=/opt/netbox -ExecStart=/opt/netbox/venv/bin/gunicorn --pid /var/tmp/netbox.pid --pythonpath /opt/netbox/netbox --config /opt/netbox/gunicorn.py netbox.wsgi +ExecStart=/opt/netbox/venv/bin/uwsgi --ini /opt/netbox/netbox/local/uwsgi.ini Restart=on-failure RestartSec=30 diff --git a/docs/installation/4-uwsgi.md b/docs/installation/4-uwsgi.md new file mode 100644 index 000000000..f90f9061a --- /dev/null +++ b/docs/installation/4-uwsgi.md @@ -0,0 +1,59 @@ +# 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 [uWSGI](https://uwsgi-docs.readthedocs.io/en/latest/) (which is automatically installed with NetBox) for this role, however other WSGI servers are available and should work similarly well. [gunicorn](http://gunicorn.org/) is a popular alternative. + +## Configuration + +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 by a future upgrade.) + +```no-highlight +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. + +## systemd Setup + +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 and reload the systemd daemon. + +!!! 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. + +```no-highlight +sudo cp -v /opt/netbox/contrib/*.service /etc/systemd/system/ +sudo systemctl daemon-reload +``` + +Then, start the `netbox` and `netbox-rq` services and enable them to initiate at boot time: + +```no-highlight +sudo systemctl enable --now netbox netbox-rq +``` + +You can use the command `systemctl status netbox` to verify that the WSGI service is running: + +```no-highlight +systemctl status netbox.service +``` + +You should see output similar to the following: + +```no-highlight +● 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 + Docs: https://docs.netbox.dev/ + Main PID: 1140492 (uwsgi) + Tasks: 19 (limit: 4683) + Memory: 666.2M + CGroup: /system.slice/netbox.service + ├─1140492 /opt/netbox/venv/bin/python3 /opt/netbox/venv/bin/uwsgi --pid /va> + ├─1140513 /opt/netbox/venv/bin/python3 /opt/netbox/venv/bin/uwsgi --pid /va> + ├─1140514 /opt/netbox/venv/bin/python3 /opt/netbox/venv/bin/uwsgi --pid /va> +... +``` + +!!! note + 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. diff --git a/docs/installation/index.md b/docs/installation/index.md index 6ad4aa79e..25cfd5143 100644 --- a/docs/installation/index.md +++ b/docs/installation/index.md @@ -12,7 +12,7 @@ The following sections detail how to set up a new instance of NetBox: 1. [PostgreSQL database](1-postgresql.md) 1. [Redis](2-redis.md) 3. [NetBox components](3-netbox.md) -4. [Gunicorn](4-gunicorn.md) +4. [uWSGI](4-uwsgi.md) 5. [HTTP server](5-http-server.md) 6. [LDAP authentication](6-ldap.md) (optional)