Merge pull request #8650 from netbox-community/8649-config-module

Closes #8649: Enable customization of configuration module

.github/workflows/ci.yml

@@ -3,6 +3,8 @@ on: [push, pull_request]
 jobs:
   build:
     runs-on: ubuntu-latest
+    env:
+      NETBOX_CONFIGURATION: netbox.configuration_testing
     strategy:
       matrix:
         python-version: ['3.8', '3.9', '3.10']
@@ -57,7 +59,6 @@ jobs:
         python -m pip install --upgrade pip
         pip install -r requirements.txt
         pip install pycodestyle coverage
-        ln -s configuration.testing.py netbox/netbox/configuration.py
 
     - name: Build documentation
       run: mkdocs build

docs/configuration/index.md

@@ -1,6 +1,11 @@
 # NetBox Configuration
 
-NetBox's local configuration is stored in `$INSTALL_ROOT/netbox/netbox/configuration.py`. An example configuration is provided as `configuration.example.py`. You may copy or rename the example configuration and make changes as appropriate. NetBox will not run without a configuration file.  While NetBox has many configuration settings, only a few of them must be defined at the time of installation: these are defined under "required settings" below.
+NetBox's local configuration is stored in `$INSTALL_ROOT/netbox/netbox/configuration.py` by default. An example configuration is provided as `configuration_example.py`. You may copy or rename the example configuration and make changes as appropriate. NetBox will not run without a configuration file.  While NetBox has many configuration settings, only a few of them must be defined at the time of installation: these are defined under "required settings" below.
+
+!!! info "Customizing the Configuration Module"
+    A custom configuration module may be specified by setting the `NETBOX_CONFIGURATION` environment variable. This must be a dotted path to the desired Python module. For example, a file named `my_config.py` in the same directory as `settings.py` would be referenced as `netbox.my_config`.
+
+    For the sake of brevity, the NetBox documentation refers to the configuration file simply as `configuration.py`.
 
 Some configuration parameters may alternatively be defined either in `configuration.py` or within the administrative section of the user interface. Settings which are "hard-coded" in the configuration file take precedence over those defined via the UI.
 

docs/development/getting-started.md

@@ -85,7 +85,7 @@ Collecting Django==3.1 (from -r requirements.txt (line 1))
 
 ### Configure NetBox
 
-Within the `netbox/netbox/` directory, copy `configuration.example.py` to `configuration.py` and update the following parameters:
+Within the `netbox/netbox/` directory, copy `configuration_example.py` to `configuration.py` and update the following parameters:
 
 * `ALLOWED_HOSTS`: This can be set to `['*']` for development purposes
 * `DATABASE`: PostgreSQL database connection parameters

docs/installation/3-netbox.md

@@ -112,11 +112,11 @@ Create a system user account named `netbox`. We'll configure the WSGI and HTTP s
 
 ## Configuration
 
-Move into the NetBox configuration directory and make a copy of `configuration.example.py` named `configuration.py`. This file will hold all of your local configuration parameters.
+Move into the NetBox configuration directory and make a copy of `configuration_example.py` named `configuration.py`. This file will hold all of your local configuration parameters.
 
 ```no-highlight
 cd /opt/netbox/netbox/netbox/
-sudo cp configuration.example.py configuration.py
+sudo cp configuration_example.py configuration.py
 ```
 
 Open `configuration.py` with your preferred editor to begin configuring NetBox. NetBox offers [many configuration parameters](../configuration/index.md), but only the following four are required for new installations:

docs/release-notes/version-3.2.md

@@ -142,6 +142,7 @@ Where it is desired to limit the range of available VLANs within a group, users
 * [#8307](https://github.com/netbox-community/netbox/issues/8307) - Add `data_type` indicator to REST API serializer for custom fields
 * [#8463](https://github.com/netbox-community/netbox/issues/8463) - Change the `created` field on all change-logged models from date to datetime
 * [#8572](https://github.com/netbox-community/netbox/issues/8572) - Add a `pre_run()` method for reports
+* [#8649](https://github.com/netbox-community/netbox/issues/8649) - Enable customization of configuration module using `NETBOX_CONFIGURATION` environment variable
 
 ### Other Changes
 

netbox/netbox/settings.py

@@ -39,12 +39,14 @@ if sys.version_info < (3, 8):
 #
 
 # Import configuration parameters
+config_path = os.getenv('NETBOX_CONFIGURATION', 'netbox.configuration')
 try:
-    from netbox import configuration
+    configuration = importlib.import_module(config_path)
 except ModuleNotFoundError as e:
-    if getattr(e, 'name') == 'configuration':
+    if getattr(e, 'name') == config_path:
         raise ImproperlyConfigured(
-            "Configuration file is not present. Please define netbox/netbox/configuration.py per the documentation."
+            f"Specified configuration module ({config_path}) not found. Please define netbox/netbox/configuration.py "
+            f"per the documentation, or specify an alternate module in the NETBOX_CONFIGURATION environment variable."
         )
     raise
 
@@ -61,9 +63,7 @@ if hasattr(configuration, 'RELEASE_CHECK_TIMEOUT'):
 # Enforce required configuration parameters
 for parameter in ['ALLOWED_HOSTS', 'DATABASE', 'SECRET_KEY', 'REDIS']:
     if not hasattr(configuration, parameter):
-        raise ImproperlyConfigured(
+        raise ImproperlyConfigured(f"Required parameter {parameter} is missing from configuration.")
-            "Required parameter {} is missing from configuration.py.".format(parameter)
-        )
 
 # Set required parameters
 ALLOWED_HOSTS = getattr(configuration, 'ALLOWED_HOSTS')