15154 Add uWSGI as option to gunicorn (#15550)
* 15154 uwsgi docs * 15154 uwsgi contrib files * 15154 review comments - merge nginx conf * Restructure gunicorn/uWSGI installation docs --------- Co-authored-by: Jeremy Stretch <jstretch@netboxlabs.com>
This commit is contained in:
parent
744be59a4d
commit
99508150d3
|
@ -12,8 +12,12 @@ Group=netbox
|
||||||
PIDFile=/var/tmp/netbox.pid
|
PIDFile=/var/tmp/netbox.pid
|
||||||
WorkingDirectory=/opt/netbox
|
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
|
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
|
Restart=on-failure
|
||||||
RestartSec=30
|
RestartSec=30
|
||||||
PrivateTmp=true
|
PrivateTmp=true
|
||||||
|
|
|
@ -14,10 +14,20 @@ server {
|
||||||
}
|
}
|
||||||
|
|
||||||
location / {
|
location / {
|
||||||
|
# Remove these lines if using uWSGI instead of Gunicorn
|
||||||
proxy_pass http://127.0.0.1:8001;
|
proxy_pass http://127.0.0.1:8001;
|
||||||
proxy_set_header X-Forwarded-Host $http_host;
|
proxy_set_header X-Forwarded-Host $http_host;
|
||||||
proxy_set_header X-Real-IP $remote_addr;
|
proxy_set_header X-Real-IP $remote_addr;
|
||||||
proxy_set_header X-Forwarded-Proto $scheme;
|
proxy_set_header X-Forwarded-Proto $scheme;
|
||||||
|
|
||||||
|
# Uncomment these lines if using uWSGI instead of Gunicorn
|
||||||
|
# include uwsgi_params;
|
||||||
|
# uwsgi_pass 127.0.0.1:8001;
|
||||||
|
# uwsgi_param Host $host;
|
||||||
|
# uwsgi_param X-Real-IP $remote_addr;
|
||||||
|
# uwsgi_param X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||||
|
# uwsgi_param X-Forwarded-Proto $http_x_forwarded_proto;
|
||||||
|
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|
|
@ -0,0 +1,18 @@
|
||||||
|
[uwsgi]
|
||||||
|
; bind to the specified UNIX/TCP socket and port (usually localhost)
|
||||||
|
socket = 127.0.0.1:8001
|
||||||
|
|
||||||
|
; fail to start if any parameter in the configuration file isn’t explicitly understood by uWSGI.
|
||||||
|
strict = true
|
||||||
|
|
||||||
|
; re-spawn and pre-fork workers
|
||||||
|
master = true
|
||||||
|
|
||||||
|
; clear environment on exit
|
||||||
|
vacuum = true
|
||||||
|
|
||||||
|
; exit if no app can be loaded
|
||||||
|
need-app = true
|
||||||
|
|
||||||
|
; do not use multiple interpreters
|
||||||
|
single-interpreter = true
|
|
@ -1,10 +1,13 @@
|
||||||
# Gunicorn
|
# 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.
|
!!! 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
|
## 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
|
```no-highlight
|
||||||
sudo cp /opt/netbox/contrib/gunicorn.py /opt/netbox/gunicorn.py
|
sudo cp /opt/netbox/contrib/gunicorn.py /opt/netbox/gunicorn.py
|
|
@ -0,0 +1,104 @@
|
||||||
|
# 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
|
||||||
|
|
||||||
|
Activate the Python virtual environment and install the `pyuwsgi` package using pip:
|
||||||
|
|
||||||
|
```no-highlight
|
||||||
|
source /opt/netbox/venv/bin/activate
|
||||||
|
pip3 install pyuwsgi
|
||||||
|
```
|
||||||
|
|
||||||
|
Once installed, add the package to `local_requirements.txt` to ensure it is re-installed during future rebuilds of the virtual environment:
|
||||||
|
|
||||||
|
```no-highlight
|
||||||
|
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.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.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 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/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 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
|
||||||
|
├─1061 /opt/netbox/venv/bin/python3 /opt/netbox/venv/bin/uwsgi --ini /opt/netbox/uwsgi.ini
|
||||||
|
├─1976 /opt/netbox/venv/bin/python3 /opt/netbox/venv/bin/uwsgi --ini /opt/netbox/uwsgi.ini
|
||||||
|
...
|
||||||
|
```
|
||||||
|
|
||||||
|
!!! 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.
|
||||||
|
|
||||||
|
## HTTP Server Installation
|
||||||
|
|
||||||
|
For server installation, you will want to follow the NetBox [HTTP Server Setup](5-http-server.md) guide, however after copying the configuration file, you will need to edit the file and change the `location` section to uncomment the uWSGI parameters:
|
||||||
|
|
||||||
|
```no-highlight
|
||||||
|
location / {
|
||||||
|
# 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
|
||||||
|
include uwsgi_params;
|
||||||
|
uwsgi_pass 127.0.0.1:8001;
|
||||||
|
uwsgi_param Host $host;
|
||||||
|
uwsgi_param X-Real-IP $remote_addr;
|
||||||
|
uwsgi_param X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||||
|
uwsgi_param X-Forwarded-Proto $http_x_forwarded_proto;
|
||||||
|
}
|
||||||
|
```
|
|
@ -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
|
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.
|
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
|
```no-highlight
|
||||||
|
|
|
@ -94,7 +94,8 @@ nav:
|
||||||
- 1. PostgreSQL: 'installation/1-postgresql.md'
|
- 1. PostgreSQL: 'installation/1-postgresql.md'
|
||||||
- 2. Redis: 'installation/2-redis.md'
|
- 2. Redis: 'installation/2-redis.md'
|
||||||
- 3. NetBox: 'installation/3-netbox.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'
|
- 5. HTTP Server: 'installation/5-http-server.md'
|
||||||
- 6. LDAP (Optional): 'installation/6-ldap.md'
|
- 6. LDAP (Optional): 'installation/6-ldap.md'
|
||||||
- Upgrading NetBox: 'installation/upgrading.md'
|
- Upgrading NetBox: 'installation/upgrading.md'
|
||||||
|
|
Loading…
Reference in New Issue