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

New Issue

adam · 2025-12-29T21:46:36+01:00

adam commented

2025-12-29 21:46:36 +01:00

Originally created by @jnovinger on GitHub (Aug 29, 2025).

Originally assigned to: @jnovinger on GitHub.

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 GitHub (Aug 29, 2025). Originally assigned to: @jnovinger on GitHub. ### 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.

adam added the status: accepted type: documentation labels 2025-12-29 21:46:36 +01:00

adam closed this issue

2025-12-29 21:46:36 +01:00

Sign in to join this conversation.

Branches Tags

main

update-changelog-comments-docs

feature-removal-issue-type

20911-dropdown

20239-plugin-menu-classes-mutable-state

21097-graphql-id-lookups

feature

fix_module_substitution

20923-dcim-templates

20044-elevation-stuck-lightmode

feature-ip-prefix-link

v4.5-beta1-release

20068-import-moduletype-attrs

20766-fix-german-translation-code-literals

20378-del-script

7604-filter-modifiers-v3

circuit-swap

12318-case-insensitive-uniqueness

20637-improve-device-q-filter

20660-script-load

19724-graphql

20614-update-ruff

14884-script

02496-max-page

19720-macaddress-interface-generic-relation

19408-circuit-terminations-export-templates

20203-openapi-check

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

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: starred/netbox#11542