From dcda444681ced48b61f7d7e9f085d489b8f44c75 Mon Sep 17 00:00:00 2001 From: Arthur Date: Wed, 27 Mar 2024 07:50:39 -0700 Subject: [PATCH 1/3] 15154 uwsgi docs --- docs/installation/4-gunicorn.md | 2 +- docs/installation/uwsgi.md | 73 +++++++++++++++++++++++++++++++++ 2 files changed, 74 insertions(+), 1 deletion(-) create mode 100644 docs/installation/uwsgi.md diff --git a/docs/installation/4-gunicorn.md b/docs/installation/4-gunicorn.md index 1e8d49453..2d9b3026b 100644 --- a/docs/installation/4-gunicorn.md +++ b/docs/installation/4-gunicorn.md @@ -1,6 +1,6 @@ # 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. +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. ## Configuration diff --git a/docs/installation/uwsgi.md b/docs/installation/uwsgi.md new file mode 100644 index 000000000..d4ab8780e --- /dev/null +++ b/docs/installation/uwsgi.md @@ -0,0 +1,73 @@ +# 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. + +## 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 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 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. + +## 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 + ├─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. From 491f751468dd4079851fe9ea4849d7053b5a06fa Mon Sep 17 00:00:00 2001 From: Arthur Date: Wed, 27 Mar 2024 08:01:44 -0700 Subject: [PATCH 2/3] 15154 uwsgi contrib files --- contrib/uwsgi/netbox.service | 22 ++++++++++++++++++++++ contrib/uwsgi/nginx.conf | 31 +++++++++++++++++++++++++++++++ contrib/uwsgi/uwsgi.ini | 18 ++++++++++++++++++ docs/installation/uwsgi.md | 19 +++++++++++++++---- 4 files changed, 86 insertions(+), 4 deletions(-) create mode 100644 contrib/uwsgi/netbox.service create mode 100644 contrib/uwsgi/nginx.conf create mode 100644 contrib/uwsgi/uwsgi.ini diff --git a/contrib/uwsgi/netbox.service b/contrib/uwsgi/netbox.service new file mode 100644 index 000000000..161a97e1b --- /dev/null +++ b/contrib/uwsgi/netbox.service @@ -0,0 +1,22 @@ +[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/contrib/uwsgi/nginx.conf b/contrib/uwsgi/nginx.conf new file mode 100644 index 000000000..ad8ee9e31 --- /dev/null +++ b/contrib/uwsgi/nginx.conf @@ -0,0 +1,31 @@ +server { + listen [::]:443 ssl ipv6only=off; + + # CHANGE THIS TO YOUR SERVER'S NAME + server_name netbox.example.com; + + ssl_certificate /etc/ssl/certs/netbox.crt; + ssl_certificate_key /etc/ssl/private/netbox.key; + + client_max_body_size 25m; + + location /static/ { + alias /opt/netbox/netbox/static/; + } + + location / { + 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; + } +} + +server { + # Redirect HTTP traffic to HTTPS + listen [::]:80 ipv6only=off; + server_name _; + return 301 https://$host$request_uri; +} diff --git a/contrib/uwsgi/uwsgi.ini b/contrib/uwsgi/uwsgi.ini new file mode 100644 index 000000000..d64803158 --- /dev/null +++ b/contrib/uwsgi/uwsgi.ini @@ -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 diff --git a/docs/installation/uwsgi.md b/docs/installation/uwsgi.md index d4ab8780e..1f1115d0d 100644 --- a/docs/installation/uwsgi.md +++ b/docs/installation/uwsgi.md @@ -19,23 +19,24 @@ 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 by a future upgrade.) +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.) ```no-highlight -sudo cp /opt/netbox/contrib/uwsgi.ini /opt/netbox/uwsgi.ini +sudo cp /opt/netbox/contrib/uwsgi/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. ## 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. +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. !!! 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 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 ``` @@ -71,3 +72,13 @@ You should see output similar to the following: 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 when copying the configuration file, instead of the default one for gunicorn you will want to use the provided uWSGI one: + +Once nginx is installed, copy the nginx configuration file provided by NetBox to `/etc/nginx/sites-available/netbox`. Be sure to replace `netbox.example.com` with the domain name or IP address of your installation. (This should match the value configured for `ALLOWED_HOSTS` in `configuration.py`.) + +```no-highlight +sudo cp /opt/netbox/contrib/uwsgi/nginx.conf /etc/nginx/sites-available/netbox +``` From 889ab57eec48c8a2057ce4d003a0bea41e0a8aa8 Mon Sep 17 00:00:00 2001 From: Arthur Date: Wed, 27 Mar 2024 11:11:23 -0700 Subject: [PATCH 3/3] 15154 review comments - merge nginx conf --- contrib/nginx.conf | 8 ++++++++ contrib/uwsgi/nginx.conf | 31 ------------------------------- docs/installation/uwsgi.md | 18 ++++++++++++++---- 3 files changed, 22 insertions(+), 35 deletions(-) delete mode 100644 contrib/uwsgi/nginx.conf diff --git a/contrib/nginx.conf b/contrib/nginx.conf index 34821cd52..67db188e3 100644 --- a/contrib/nginx.conf +++ b/contrib/nginx.conf @@ -18,6 +18,14 @@ server { 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; + } } diff --git a/contrib/uwsgi/nginx.conf b/contrib/uwsgi/nginx.conf deleted file mode 100644 index ad8ee9e31..000000000 --- a/contrib/uwsgi/nginx.conf +++ /dev/null @@ -1,31 +0,0 @@ -server { - listen [::]:443 ssl ipv6only=off; - - # CHANGE THIS TO YOUR SERVER'S NAME - server_name netbox.example.com; - - ssl_certificate /etc/ssl/certs/netbox.crt; - ssl_certificate_key /etc/ssl/private/netbox.key; - - client_max_body_size 25m; - - location /static/ { - alias /opt/netbox/netbox/static/; - } - - location / { - 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; - } -} - -server { - # Redirect HTTP traffic to HTTPS - listen [::]:80 ipv6only=off; - server_name _; - return 301 https://$host$request_uri; -} diff --git a/docs/installation/uwsgi.md b/docs/installation/uwsgi.md index 1f1115d0d..39f1a4181 100644 --- a/docs/installation/uwsgi.md +++ b/docs/installation/uwsgi.md @@ -75,10 +75,20 @@ Once you've verified that the WSGI workers are up and running, move on to HTTP s ## HTTP Server Installation -For server installation, you will want to follow the NetBox [HTTP Server Setup](5-http-server.md) guide, however when copying the configuration file, instead of the default one for gunicorn you will want to use the provided uWSGI one: - -Once nginx is installed, copy the nginx configuration file provided by NetBox to `/etc/nginx/sites-available/netbox`. Be sure to replace `netbox.example.com` with the domain name or IP address of your installation. (This should match the value configured for `ALLOWED_HOSTS` in `configuration.py`.) +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 -sudo cp /opt/netbox/contrib/uwsgi/nginx.conf /etc/nginx/sites-available/netbox + 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; + } ```