Document NetBox configuration approach with environment variables and third-party libraries #1372

New Issue

MrUnknownDE · 2026-04-06T00:14:53+02:00

MrUnknownDE commented

2026-04-06 00:14:53 +02:00

Originally created by @jnovinger on 8/29/2025

Change Type

Addition

Area

Configuration

Proposed Changes

Add guidance explaining NetBox's configuration approach and why environment variables don't work as expected with third-party libraries like django-storages. Many Django libraries expect to use environment variable patterns, but NetBox's explicit configuration approach might affect how these libraries function.

Issue Context: Users following third-party library documentation (for example in #20184) expect environment variables to be automatically detected. This leads to confusion when standard patterns don't work as documented.

Documentation Updates Needed:

In docs/configuration/index.md: explain NetBox's explicit configuration approach:
- NetBox uses explicit Python configuration rather than environment variable detection
- Benefits: Clear configuration, version control, explicit parameter definition
- Impacts: Third-party libraries that rely on automatic environment variable detection require explicit configuration

Environment Variable Usage Patterns: Document how to use environment variables in NetBox:

# Explicitly reading environment variables when needed
import os

SECRET_KEY = os.environ.get('NETBOX_SECRET_KEY')

# Third-party library configuration requires explicit parameter passing
STORAGES = {
    'staticfiles': {
        'BACKEND': 'storages.backends.s3.S3Storage',
        'OPTIONS': {
            'bucket_name': os.environ.get('AWS_STORAGE_BUCKET_NAME'),
          'location': 'static/',
        }
    }
}

Common Third-Party Integration Gotchas: Document that libraries expecting automatic environment variable detection need explicit configuration in NetBox context

This addresses recurring support questions about why documented patterns from Django libraries don't work in NetBox and provides clear guidance on NetBox's configuration approach.

*Originally created by @jnovinger on 8/29/2025* ### Change Type Addition ### Area Configuration ### Proposed Changes Add guidance explaining NetBox's configuration approach and why environment variables don't work as expected with third-party libraries like `django-storage`s. Many Django libraries expect to use environment variable patterns, but NetBox's explicit configuration approach might affect how these libraries function. Issue Context: Users following third-party library documentation (for example in #20184) expect environment variables to be automatically detected. This leads to confusion when standard patterns don't work as documented. Documentation Updates Needed: 1. In `docs/configuration/index.md`: explain NetBox's explicit configuration approach: - NetBox uses explicit Python configuration rather than environment variable detection - Benefits: Clear configuration, version control, explicit parameter definition - Impacts: Third-party libraries that rely on automatic environment variable detection require explicit configuration 2. Environment Variable Usage Patterns: Document how to use environment variables in NetBox: ```py # Explicitly reading environment variables when needed import os SECRET_KEY = os.environ.get('NETBOX_SECRET_KEY') # Third-party library configuration requires explicit parameter passing STORAGES = { 'staticfiles': { 'BACKEND': 'storages.backends.s3.S3Storage', 'OPTIONS': { 'bucket_name': os.environ.get('AWS_STORAGE_BUCKET_NAME'), 'location': 'static/', } } } ``` 3. Common Third-Party Integration Gotchas: Document that libraries expecting automatic environment variable detection need explicit configuration in NetBox context This addresses recurring support questions about why documented patterns from Django libraries don't work in NetBox and provides clear guidance on NetBox's configuration approach.

MrUnknownDE closed this issue

2026-04-06 00:14:53 +02:00

Sign in to join this conversation.

Branches Tags

main

21455-sql-indexes-audit

21357-register-model-actions

feature

20924-plugin-ui-components

21766-improve-test-coverage-for-sortable-table-columns

21157-export-template-public-models

21025-pre-render-config-contexts

21364-swagger

feature-ip-prefix-link

20911-dropdown-3

fix_module_substitution

21160-filterset

20911-dropdown-2

20044-elevation-stuck-lightmode

7604-filter-modifiers-v3

20660-script-load

19724-graphql

14884-script

19720-macaddress-interface-generic-relation

fix-19669-api-image-download

7604-filter-modifiers

19275-fixes-interface-bulk-edit

fix-17794-get_field_value_return_list

11507-show-aggregate-and-rir-on-api

9583-add_column_specific_search_field_to_tables

No Label status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted type: documentation type: documentation type: documentation type: documentation type: documentation type: documentation type: documentation type: documentation type: documentation type: documentation type: documentation type: documentation type: documentation type: documentation type: documentation type: documentation type: documentation type: documentation type: documentation type: documentation type: documentation type: documentation type: documentation type: documentation type: documentation type: documentation type: documentation type: documentation type: documentation type: documentation type: documentation

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github/netbox#1372