Sanitized mirror from private repository - 2026-03-21 11:14:37 UTC

2026-03-21 11:14:37 +00:00
commit bd82e850ee
1237 changed files with 307694 additions and 0 deletions
--- a/docs/services/individual/netbox.md
+++ b/docs/services/individual/netbox.md
@@ -0,0 +1,167 @@
+# 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:
+
+```bash
+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:
+```bash
+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`:
+```python
+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:
+```bash
+# 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
+
+```bash
+# 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
+```