diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index fa0f74200..64cf5482a 100644 --- a/.github/workflows/ci.yml +++ b/.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 diff --git a/docs/configuration/index.md b/docs/configuration/index.md index 95ed3fc37..a863ef3dc 100644 --- a/docs/configuration/index.md +++ b/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. diff --git a/docs/development/getting-started.md b/docs/development/getting-started.md index 0e892bd4a..bc78bf635 100644 --- a/docs/development/getting-started.md +++ b/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 diff --git a/docs/installation/3-netbox.md b/docs/installation/3-netbox.md index cf9c19641..50b350d3a 100644 --- a/docs/installation/3-netbox.md +++ b/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: diff --git a/docs/release-notes/version-3.2.md b/docs/release-notes/version-3.2.md index 7ad564e35..557550cc4 100644 --- a/docs/release-notes/version-3.2.md +++ b/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 diff --git a/netbox/netbox/configuration.example.py b/netbox/netbox/configuration_example.py similarity index 100% rename from netbox/netbox/configuration.example.py rename to netbox/netbox/configuration_example.py diff --git a/netbox/netbox/configuration.testing.py b/netbox/netbox/configuration_testing.py similarity index 100% rename from netbox/netbox/configuration.testing.py rename to netbox/netbox/configuration_testing.py diff --git a/netbox/netbox/settings.py b/netbox/netbox/settings.py index 8b263b9c1..9447a4b37 100644 --- a/netbox/netbox/settings.py +++ b/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( - "Required parameter {} is missing from configuration.py.".format(parameter) - ) + raise ImproperlyConfigured(f"Required parameter {parameter} is missing from configuration.") # Set required parameters ALLOWED_HOSTS = getattr(configuration, 'ALLOWED_HOSTS')