From 0851b97ba5445583a9c8452009b5b45a2e9f110e Mon Sep 17 00:00:00 2001 From: Jeremy Stretch Date: Wed, 26 Feb 2020 13:54:07 -0500 Subject: [PATCH] Update the upgrade script & instructions to use a virtual environment --- base_requirements.txt | 4 +++ docs/installation/4-http-daemon.md | 15 ++------ docs/installation/upgrading.md | 26 ++++++++++---- requirements.txt | 1 + upgrade.sh | 58 +++++++++++++++--------------- 5 files changed, 55 insertions(+), 49 deletions(-) diff --git a/base_requirements.txt b/base_requirements.txt index e1c29a2a2..ab33b1c06 100644 --- a/base_requirements.txt +++ b/base_requirements.txt @@ -58,6 +58,10 @@ djangorestframework # https://github.com/axnsan12/drf-yasg drf-yasg[validation] +# WSGI HTTP server +# https://gunicorn.org/ +gunicorn + # Platform-agnostic template rendering engine # https://github.com/pallets/jinja Jinja2 diff --git a/docs/installation/4-http-daemon.md b/docs/installation/4-http-daemon.md index 43206b26e..065c63b12 100644 --- a/docs/installation/4-http-daemon.md +++ b/docs/installation/4-http-daemon.md @@ -102,15 +102,9 @@ To enable SSL, consider this guide on [securing Apache with Let's Encrypt](https !!! note Certain components of NetBox (such as the display of rack elevation diagrams) rely on the use of embedded objects. Ensure that your HTTP server configuration does not override the `X-Frame-Options` response header set by NetBox. -## gunicorn Installation +## gunicorn Configuration -Check that the Python virtual environment created in [the previous step](3-netbox.md#set-up-python-environment) is still active, and install the `gunicorn` Python package. (If the virtual environment is not active, activate it with the command `source /opt/netbox/venv/bin/activate`.) - -```no-highlight -(venv) # pip3 install gunicorn -``` - -Copy `/opt/netbox/contrib/gunicorn.py` to `/opt/netbox/gunicorn.py`. We make a copy of this file to ensure that any changes to it do not get overwritten by a future upgrade. +Copy `/opt/netbox/contrib/gunicorn.py` to `/opt/netbox/gunicorn.py`. (We make a copy of this file to ensure that any changes to it do not get overwritten by a future upgrade.) ```no-highlight # cd /opt/netbox @@ -119,7 +113,7 @@ Copy `/opt/netbox/contrib/gunicorn.py` to `/opt/netbox/gunicorn.py`. We make a c You may wish to edit this file to change the bound IP address or port number, or to make performance-related adjustments. -## systemd configuration +## systemd Configuration We'll use systemd to control the daemonization of NetBox services. First, copy `contrib/netbox.service` and `contrib/netbox-rq.service` to the `/etc/systemd/system/` directory: @@ -127,9 +121,6 @@ We'll use systemd to control the daemonization of NetBox services. First, copy ` # cp contrib/*.service /etc/systemd/system/ ``` -!!! note - These service files assume that gunicorn is installed at `/usr/local/bin/gunicorn`. If the output of `which gunicorn` indicates a different path, you'll need to correct the `ExecStart` path in both files. - Then, start the `netbox` and `netbox-rq` services and enable them to initiate at boot time: ```no-highlight diff --git a/docs/installation/upgrading.md b/docs/installation/upgrading.md index e5cf93a28..101ec9c36 100644 --- a/docs/installation/upgrading.md +++ b/docs/installation/upgrading.md @@ -1,12 +1,12 @@ -# Review the Release Notes +## Review the Release Notes Prior to upgrading your NetBox instance, be sure to carefully review all [release notes](../../release-notes/) that have been published since your current version was released. Although the upgrade process typically does not involve additional work, certain releases may introduce breaking or backward-incompatible changes. These are called out in the release notes under the version in which the change went into effect. -# Install the Latest Code +## Install the Latest Code As with the initial installation, you can upgrade NetBox by either downloading the latest release package or by cloning the `master` branch of the git repository. -## Option A: Download a Release +### Option A: Download a Release Download the [latest stable release](https://github.com/netbox-community/netbox/releases) from GitHub as a tarball or ZIP archive. Extract it to your desired path. In this example, we'll use `/opt/netbox`. @@ -34,7 +34,7 @@ Be sure to replicate your uploaded media as well. (The exact action necessary wi Also make sure to copy over any reports that you've made. Note that if you made them in a separate directory (`/opt/netbox-reports` for example), then you will not need to copy them - the config file that you copied earlier will point to the correct location. ```no-highlight -# cp -r /opt/netbox-X.Y.X/netbox/reports /opt/netbox/netbox/reports/ +# cp -r /opt/netbox-X.Y.Z/netbox/reports /opt/netbox/netbox/reports/ ``` If you followed the original installation guide to set up gunicorn, be sure to copy its configuration as well: @@ -49,7 +49,7 @@ Copy the LDAP configuration if using LDAP: # cp netbox-X.Y.Z/netbox/netbox/ldap_config.py netbox/netbox/netbox/ldap_config.py ``` -## Option B: Clone the Git Repository (latest master release) +### Option B: Clone the Git Repository (latest master release) This guide assumes that NetBox is installed at `/opt/netbox`. Pull down the most recent iteration of the master branch: @@ -60,7 +60,19 @@ This guide assumes that NetBox is installed at `/opt/netbox`. Pull down the most # git status ``` -# Run the Upgrade Script +## Rebuild the Virtual Environment + +Destroy and recreate the Python virtual environment. This ensures that an up-to-date version of each dependency is installed while and that any obsolete packages are no longer present. + +```no-highlight +# cd /opt/netbox +# rm -rf venv +# python3 -m venv venv +# source venv/bin/activate +(venv) # pip3 install -r requirements.txt +``` + +## Run the Upgrade Script Once the new code is in place, run the upgrade script (which may need to be run as root depending on how your environment is configured). @@ -82,7 +94,7 @@ This script: This may occur due to semantic differences in environment, and can be safely ignored. Never attempt to create new migrations unless you are intentionally modifying the database schema. -# Restart the WSGI Service +## Restart the WSGI Service Finally, restart the WSGI services to run the new code. If you followed this guide for the initial installation, this is done using `systemctl: diff --git a/requirements.txt b/requirements.txt index 3b04494ed..d8e704874 100644 --- a/requirements.txt +++ b/requirements.txt @@ -13,6 +13,7 @@ django-taggit-serializer==0.1.7 django-timezone-field==4.0 djangorestframework==3.10.3 drf-yasg[validation]==1.17.0 +gunicorn==20.0.4 Jinja2==2.10.3 Markdown==2.6.11 netaddr==0.7.19 diff --git a/upgrade.sh b/upgrade.sh index 2ff585e8d..72e465661 100755 --- a/upgrade.sh +++ b/upgrade.sh @@ -1,52 +1,50 @@ #!/bin/bash # This script will prepare NetBox to run after the code has been upgraded to # its most recent release. -# -# Once the script completes, remember to restart the WSGI service (e.g. -# gunicorn or uWSGI). cd "$(dirname "$0")" +VIRTUALENV="$(pwd -P)/venv" -PYTHON="python3" -PIP="pip3" +# Remove the existing virtual environment (if any) +if [ -d "$VIRTUALENV" ]; then + COMMAND="rm -rf ${VIRTUALENV}" + echo "Removing old virtual environment..." + eval $COMMAND +fi -# Uninstall any Python packages which are no longer needed -COMMAND="${PIP} uninstall -r old_requirements.txt -y" -echo "Removing old Python packages ($COMMAND)..." +# Create a new virtual environment +COMMAND="/usr/bin/python3 -m venv ${VIRTUALENV}" +echo "Creating a new virtual environment at ${VIRTUALENV}..." eval $COMMAND -# Install any new Python packages -COMMAND="${PIP} install -r requirements.txt --upgrade" -echo "Updating required Python packages ($COMMAND)..." -eval $COMMAND +# Activate the virtual environment +source "${VIRTUALENV}/bin/activate" -# Validate Python dependencies -COMMAND="${PIP} check" -echo "Validating Python dependencies ($COMMAND)..." -eval $COMMAND || ( - echo "******** PLEASE FIX THE DEPENDENCIES BEFORE CONTINUING ********" - echo "* Manually install newer version(s) of the highlighted packages" - echo "* so that 'pip3 check' passes. For more information see:" - echo "* https://github.com/pypa/pip/issues/988" - exit 1 -) +# Install Python packages +COMMAND="pip3 install -r requirements.txt" +echo "Installing Python packages ($COMMAND)..." +eval $COMMAND # Apply any database migrations -COMMAND="${PYTHON} netbox/manage.py migrate" +COMMAND="python3 netbox/manage.py migrate" echo "Applying database migrations ($COMMAND)..." eval $COMMAND -# Delete any stale content types -COMMAND="${PYTHON} netbox/manage.py remove_stale_contenttypes --no-input" -echo "Removing stale content types ($COMMAND)..." -eval $COMMAND - # Collect static files -COMMAND="${PYTHON} netbox/manage.py collectstatic --no-input" +COMMAND="python3 netbox/manage.py collectstatic --no-input" echo "Collecting static files ($COMMAND)..." eval $COMMAND +# Delete any stale content types +COMMAND="python3 netbox/manage.py remove_stale_contenttypes --no-input" +echo "Removing stale content types ($COMMAND)..." +eval $COMMAND + # Clear all cached data -COMMAND="${PYTHON} netbox/manage.py invalidate all" +COMMAND="python3 netbox/manage.py invalidate all" echo "Clearing cache data ($COMMAND)..." eval $COMMAND + +echo "Upgrade complete! Don't forget to restart the NetBox services:" +echo " sudo systemctl restart netbox" +echo " sudo systemctl restart netbox-rq"