Vish/homelab-optimized
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ca723d77b92e333bbc20c6e7c5c3cfba005be972
homelab-optimized/docs/services/individual/netbox.md
Gitea Mirror Bot ca723d77b9
Some checks failed
Documentation / Deploy to GitHub Pages (push) Has been cancelled
Details
Documentation / Build Docusaurus (push) Has been cancelled
Details
Sanitized mirror from private repository - 2026-04-20 00:50:49 UTC
2026-04-20 00:50:49 +00:00

6.8 KiB
Raw Blame History

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 39 (10GbE, 1GbE, virtual, Tailscale, switch ports)
MAC Addresses 17 (all physical NICs with SSH access)
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.)

MAC Addresses

NetBox v4.2+ stores MAC addresses as separate objects (/api/dcim/mac-addresses/), not as fields on interfaces. Each MAC is linked to an interface via assigned_object_type + assigned_object_id.

Populated MACs (2026-03-30):

Device Interface MAC Address
atlantis eth0 90:09:D0:8B:0C:E9
atlantis eth1 90:09:D0:8B:0C:EA
atlantis ovs_eth2 90:09:D0:8B:0C:EB
calypso eth0 90:09:D0:5D:DD:DE
calypso ovs_eth2 90:09:D0:5B:DC:70
concord-nuc eno1 F4:4D:30:65:52:56
guava enp1s0f0np0 E8:EB:D3:C1:11:D8
guava enp1s0f1np1 E8:EB:D3:C1:11:D9
homelab-vm eth0 3A:E3:15:F8:B3:90
olares enp129s0 84:F7:58:3F:DB:2A
pi-5 eth0 88:A2:9E:00:1A:C5
setillo eth0 90:09:D0:76:97:3E
seattle eth0 00:50:56:54:38:A2
pve eno1 94:C6:91:A4:F4:63
matrix-ubuntu ens3 02:11:32:20:04:FE
jellyfish eth0 2C:CF:67:24:39:D6
homeassistant end0 20:F8:3B:02:29:A1

Devices without MACs (no SSH access): archer-be800, msi-prestige, pi-5-kevin, shield-tv, shinku-ryuu (offline).

API

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

NetBox v4 uses v2 API tokens with the Bearer keyword:

# Create a token via Django shell (plaintext only shown once):
docker exec netbox python3 /app/netbox/netbox/manage.py shell -c "
from users.models import Token, User
admin = User.objects.get(username='admin')
t = Token(user=admin, description='my-token', write_enabled=True)
t.save()
print(f'nbt_{t.key}.{t._token}')
"

# Use the 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.

Key API endpoints:

  • /api/dcim/devices/ -- devices
  • /api/dcim/interfaces/ -- network interfaces
  • /api/dcim/mac-addresses/ -- MAC addresses (v4.2+ separate model)
  • /api/ipam/ip-addresses/ -- IP addresses
  • /api/dcim/cables/ -- physical cabling

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
Reference in New Issue View Git Blame Copy Permalink