Vish/homelab-optimized

Fork 0

Files

Gitea Mirror Bot 25c3532414

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-19 09:44:40 UTC

2026-04-19 09:44:40 +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

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

6.8 KiB Raw Blame History