homelab-optimized/docs/services/individual/netbox.md

NetBox — DCIM / IPAM

Data Center Infrastructure Management & IP Address Management

Service Overview

Property	Value
Host	homelab-vm (192.168.0.210)
Port	8443 (-> 8000 internal)
URL	https://nb.vish.gg
Local URL	http://192.168.0.210:8443
Image	linuxserver/netbox:latest
Stack	hosts/vms/homelab-vm/netbox.yaml
Data	/home/homelab/docker/netbox/{config,db,redis}

Credentials

Property	Value
Superuser Email	your-email@example.com
Superuser Password	Set via env var SUPERUSER_PASSWORD at deploy time
DB Password	Set via env var DB_PASSWORD
Redis Password	Set via env var REDIS_PASSWORD

Architecture

              Internet
                 |
          Cloudflare (proxied)
                 |
              nb.vish.gg
                 |
      NPM (matrix-ubuntu:443) --- SSL: *.vish.gg LE wildcard cert
                 |
    http://192.168.0.210:8443 (LAN)
                 |
         +-------+-------+
         |       |       |
    netbox-db  redis   netbox
   (pg:16)   (redis:7) (uwsgi)

NPM on matrix-ubuntu reaches homelab-vm via its LAN IP (192.168.0.210).

Components

Container	Image	Purpose
netbox	linuxserver/netbox:latest	Web UI + API + background worker
netbox-db	postgres:16-alpine	PostgreSQL database
netbox-redis	redis:7-alpine	Caching and task queue

DNS & Reverse Proxy

• Cloudflare: nb.vish.gg A record (proxied), auto-updated by DDNS
• DDNS: Listed in ddns-vish-proxied service (hosts/synology/atlantis/dynamicdnsupdater.yaml)
• NPM (matrix-ubuntu): Proxy host ID 46 -- nb.vish.gg -> http://192.168.0.210:8443
  • SSL: Let's Encrypt wildcard certificate (*.vish.gg)
  • Force SSL: yes
  • Block exploits: yes

Deployment

Deployed via docker compose with env vars for secrets:

cd /home/homelab/organized/repos/homelab/hosts/vms/homelab-vm

SUPERUSER_EMAIL=your-email@example.com \
SUPERUSER_PASSWORD="REDACTED_PASSWORD" \
DB_PASSWORD="REDACTED_PASSWORD" \
REDIS_PASSWORD="REDACTED_PASSWORD" \
docker compose -f netbox.yaml -p netbox up -d

First startup takes several minutes (DB migrations + static file collection).

Configuration

Main config persisted at: /home/homelab/docker/netbox/config/configuration.py

Key settings:

• ALLOWED_HOSTS = ['*'] -- NPM handles domain routing
• TIME_ZONE = 'UTC'
• LOGIN_REQUIRED = False (change to True to require auth for read access)
• SECRET_KEY -- auto-generated on first run, do not change

To edit:

sudo nano /home/homelab/docker/netbox/config/configuration.py
docker restart netbox

Authentication (Authentik OIDC)

NetBox uses Authentik SSO via OpenID Connect.

Setting	Value
Provider	NetBox (PK: 23, OAuth2/OIDC)
Application slug	netbox
Discovery URL	https://sso.vish.gg/application/o/netbox/
Client ID	BB7PiOu8xFOl58H2MUfl9IHISVLuJ4UwwMGvmJ9N
Redirect URI	https://nb.vish.gg/oauth/complete/oidc/
Scopes	openid, profile, email
User mapping	associate_by_email pipeline -- matches Authentik email to NetBox user

Login page shows "OpenID Connect" button. The vish Authentik user is mapped to a superuser account.

Configuration in /home/homelab/docker/netbox/config/configuration.py:

REMOTE_AUTH_ENABLED = True
REMOTE_AUTH_BACKEND = 'social_core.backends.open_id_connect.OpenIdConnectAuth'
REMOTE_AUTH_AUTO_CREATE_USER = True
SOCIAL_AUTH_OIDC_OIDC_ENDPOINT = 'https://sso.vish.gg/application/o/netbox/'
SOCIAL_AUTH_OIDC_KEY = '<client-id>'
SOCIAL_AUTH_OIDC_SECRET = '<client-secret>'

Inventory Data

NetBox is pre-populated with the full homelab inventory:

Category	Count
Sites	3 (Home, Seattle, Contabo VPS)
Devices	19 (NAS, VMs, switches, workstations, RPis)
Services	110 (all Docker containers with ports)
IP Addresses	28 (LAN + Tailscale for all hosts)
IP Prefixes	5 (LAN, Tailscale, Docker, K8s)
Interfaces	26 (10GbE, 1GbE, Tailscale, switch ports)
Cables	4 (10GbE switch connections)
Clusters	3 (Portainer Docker, Olares K8s, Headscale)
Virtual Machines	3 (homelab-vm, matrix-ubuntu, tdarr-node)
Tags	17 (media, monitoring, devops, ai-ml, etc.)

API

REST API at /api/, GraphQL at /graphql/.

NetBox v4 uses v2 API tokens with the Bearer keyword:

# Create a token: User menu -> API Tokens in the web UI
# v2 token format: Bearer nbt_<key>.<token>
curl -H "Authorization: Bearer nbt_<key>.<plaintext>" https://nb.vish.gg/api/dcim/devices/

Note: API_TOKEN_PEPPERS must be configured in configuration.py for v2 tokens to work.

Maintenance

# Logs
docker logs netbox --tail 50

# Restart
docker restart netbox

# Upgrade
docker compose -f netbox.yaml -p netbox pull && \
docker compose -f netbox.yaml -p netbox up -d

# Backup database
docker exec netbox-db pg_dump -U netbox netbox > /home/homelab/docker/netbox/backup-$(date +%Y%m%d).sql