Merge pull request #20323 from netbox-community/20206-document-env-var-config-approach

#20206: Clarify `django-storages` configuration from env vars

Author: bctiemann

docs/configuration/data-validation.md

@@ -17,7 +17,7 @@ CUSTOM_VALIDATORS = {
         },
         "my_plugin.validators.Validator1"
     ],
-    "dim.device": [
+    "dcim.device": [
         "my_plugin.validators.Validator1"
     ]
 }

docs/configuration/system.md

@@ -257,6 +257,46 @@ The specific configuration settings for each storage backend can be found in the
 !!! note
     Any keys defined in the `STORAGES` configuration parameter replace those in the default configuration. It is only necessary to define keys within the `STORAGES` for the specific backend(s) you wish to configure.
 
+### Environment Variables and Third-Party Libraries
+
+NetBox uses an explicit Python configuration approach rather than automatic environment variable detection. While this provides clear configuration management and version control capabilities, it affects how some third-party libraries like `django-storages` function within NetBox's context.
+
+Many Django libraries (including `django-storages`) expect to automatically detect environment variables like `AWS_STORAGE_BUCKET_NAME` or `AWS_S3_ACCESS_KEY_ID`. However, NetBox's configuration processing prevents this automatic detection from working as documented in some of these libraries.
+
+When using third-party libraries that rely on environment variable detection, you may need to explicitly read environment variables in your NetBox `configuration.py`:
+
+```python
+import os
+
+STORAGES = {
+    'default': {
+        'BACKEND': 'storages.backends.s3.S3Storage',
+        'OPTIONS': {
+            'bucket_name': os.environ.get('AWS_STORAGE_BUCKET_NAME'),
+            'access_key': os.environ.get('AWS_S3_ACCESS_KEY_ID'),
+            'secret_key': os.environ.get('AWS_S3_SECRET_ACCESS_KEY'),
+            'endpoint_url': os.environ.get('AWS_S3_ENDPOINT_URL'),
+            'location': 'media/',
+        }
+    },
+    'staticfiles': {
+        'BACKEND': 'storages.backends.s3.S3Storage',
+        'OPTIONS': {
+            'bucket_name': os.environ.get('AWS_STORAGE_BUCKET_NAME'),
+            'access_key': os.environ.get('AWS_S3_ACCESS_KEY_ID'),
+            'secret_key': os.environ.get('AWS_S3_SECRET_ACCESS_KEY'),
+            'endpoint_url': os.environ.get('AWS_S3_ENDPOINT_URL'),
+            'location': 'static/',
+        }
+    },
+}
+```
+
+This approach works because the environment variables are resolved during NetBox's configuration processing, before the third-party library attempts its own environment variable detection.
+
+!!! warning "Configuration Behavior"
+    Simply setting environment variables like `AWS_STORAGE_BUCKET_NAME` without explicitly reading them in your configuration will not work. The variables must be read using `os.environ.get()` within your `configuration.py` file.
+
 ---
 
 ## TIME_ZONE