NetBox¶
Network source of truth (IPAM/DCIM).
| Runtime | Container (Docker Swarm), 5 containers: netbox, netbox-worker, netbox-housekeeping, postgres, redis, redis-cache |
| Tier | Apps (Important) |
| Node | swarm-core |
| Image | netboxcommunity/netbox:v4.6.5 (netbox/worker/housekeeping share this); postgres:16-alpine; redis:7-alpine (two separate instances) |
| URL | https://netbox.lab.riversfamily.uk |
| Auth | Native OIDC |
| Source | ansible/stacks/apps/netbox/ |
Five containers — tied with Paperless-ngx for the most sidecars of any
service in the stack. netbox-worker runs rqworker;
netbox-housekeeping runs /opt/netbox/housekeeping.sh. Both share the main
netbox service's full env/secrets/network via a YAML anchor.
Configuration¶
Two separate Redis instances: redis (tasks/queues, persisted to a volume)
and redis-cache (ephemeral cache, no volume). OIDC and reverse-proxy trust
settings are rendered into mounted oidc.py and proxy.py config files
(/etc/netbox/config/) rather than env vars — proxy.py.j2 sets
CSRF_TRUSTED_ORIGINS and SECURE_PROXY_SSL_HEADER, since NetBox has no
forwarded-proto trust by default.
Volumes¶
| Volume | Path | Backing | Contents |
|---|---|---|---|
media |
/opt/netbox/netbox/media |
Local | Uploaded attachments |
database |
/var/lib/postgresql/data |
Local | Postgres data — never NFS |
redis |
/data |
Local | Task/queue Redis (redis-cache has no volume) |
| (rendered) | /etc/netbox/config/oidc.py, /etc/netbox/config/proxy.py |
Read-only | OIDC and proxy-trust config |
Networking¶
netbox joins both the shared traefik network (for its Traefik route)
and this stack's private internal network. netbox-worker,
netbox-housekeeping, postgres, redis and redis-cache join internal
only — they are unreachable from every other stack.
Secrets¶
| Vault variable | Delivered as | Purpose |
|---|---|---|
vault_netbox_db_password |
Swarm secret (DB_PASSWORD_FILE), read by postgres and netbox/worker/housekeeping |
Postgres password |
vault_netbox_secret_key |
Swarm secret (SECRET_KEY_FILE), must be ≥50 characters |
Django secret key |
vault_netbox_superuser_password |
Swarm secret (SUPERUSER_PASSWORD_FILE) |
Initial superuser password |
vault_netbox_oidc_client_secret |
Rendered into oidc.py |
OIDC client secret |
The first three are genuinely file-based Swarm secrets, unlike most other apps' non-database secrets.