Closes #4322: Introduce and document local_requirements.txt support for installation/upgrade of optional dependencies

docs/installation/3-netbox.md

@@ -103,6 +103,12 @@ NetBox supports integration with the [NAPALM automation](https://napalm-automati
 (venv) # pip3 install napalm
 ```
 
+To ensure NAPALM is automatically re-installed during future upgrades, create a file named `local_requirements.txt` in the NetBox root directory (alongside `requirements.txt`) and list the `napalm` package:
+
+```no-highlight
+# echo napalm >> local_requirements.txt
+```
+
 ### Remote File Storage (Optional)
 
 By default, NetBox will use the local filesystem to storage uploaded files. To use a remote filesystem, install the [`django-storages`](https://django-storages.readthedocs.io/en/stable/) library and configure your [desired backend](../../configuration/optional-settings/#storage_backend) in `configuration.py`.
@@ -111,6 +117,12 @@ By default, NetBox will use the local filesystem to storage uploaded files. To u
 (venv) # pip3 install django-storages
 ```
 
+Don't forget to add the `django-storages` package to `local_requirements.txt` to ensure it gets re-installed during future upgrades:
+
+```no-highlight
+# echo django-storages >> local_requirements.txt
+```
+
 ## Configuration
 
 Move into the NetBox configuration directory and make a copy of `configuration.example.py` named `configuration.py`.

docs/installation/5-ldap.md

@@ -4,24 +4,34 @@ This guide explains how to implement LDAP authentication using an external serve
 
 ## Install Requirements
 
-### Install openldap-devel
+### Install System Packages
 
 On Ubuntu:
 
 ```no-highlight
-sudo apt-get install -y libldap2-dev libsasl2-dev libssl-dev
+# apt-get install -y libldap2-dev libsasl2-dev libssl-dev
 ```
 
 On CentOS:
 
 ```no-highlight
-sudo yum install -y openldap-devel
+# yum install -y openldap-devel
 ```
 
 ### Install django-auth-ldap
 
+Activate the Python virtual environment and install the `django-auth-ldap` package using pip:
+
+```no-highlight
+# cd /opt/netbox/
+# source venv/bin/activate
+(venv) # pip3 install django-auth-ldap
+```
+
+Once installed, add the package to `local_requirements.txt` to ensure it is re-installed during future rebuilds of the virtual environment:
+
 ```no-highlight
-pip3 install django-auth-ldap
+(venv) # echo django-auth-ldap >> local_requirements.txt
 ```
 
 ## Configuration

docs/installation/upgrading.md

@@ -64,7 +64,7 @@ This guide assumes that NetBox is installed at `/opt/netbox`. Pull down the most
 
 ## Run the Upgrade Script
 
-Once the new code is in place, run the upgrade script:
+Once the new code is in place, verify that any optional Python packages required by your deployment (e.g. `napalm` or `django-auth-ldap`) are listed in `local_requirements.txt`. Then, run the upgrade script:
 
 ```no-highlight
 # ./upgrade.sh
@@ -73,7 +73,8 @@ Once the new code is in place, run the upgrade script:
 This script:
 
 * Destroys and rebuilds the Python virtual environment
-* Installs all required Python packages
+* Installs all required Python packages (listed in `requirements.txt`)
+* Installs any additional packages from `local_requirements.txt`
 * Applies any database migrations that were included in the release
 * Collects all static files to be served by the HTTP service
 * Deletes stale content types from the database

upgrade.sh

@@ -34,11 +34,21 @@ COMMAND="pip3 install wheel"
 echo "Installing Python system packages ($COMMAND)..."
 eval $COMMAND || exit 1
 
-# Install Python packages
+# Install required Python packages
 COMMAND="pip3 install -r requirements.txt"
-echo "Installing dependencies ($COMMAND)..."
+echo "Installing core dependencies ($COMMAND)..."
 eval $COMMAND || exit 1
 
+# Install optional packages (if any)
+if [ -f "local_requirements.txt" ]
+then
+  COMMAND="pip3 install -r local_requirements.txt"
+  echo "Installing local dependencies ($COMMAND)..."
+  eval $COMMAND || exit 1
+else
+  echo "Skipping local dependencies (local_requirements.txt not found)"
+fi
+
 # Apply any database migrations
 COMMAND="python3 netbox/manage.py migrate"
 echo "Applying database migrations ($COMMAND)..."