# 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 (calypso:8443) --- SSL: *.vish.gg origin cert
                 |
    http://100.67.40.126:8443 (Tailscale)
                 |
         +-------+-------+
         |       |       |
    netbox-db  redis   netbox
   (pg:16)   (redis:7) (uwsgi)
```

NPM reaches homelab-vm via its **Tailscale IP** (100.67.40.126), not the LAN IP -- calypso routes through Tailscale to reach homelab-vm services.

## 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**: Proxy host ID 46 -- `nb.vish.gg` -> `http://100.67.40.126:8443`
  - SSL: Cloudflare origin certificate (`*.vish.gg`, cert ID 1)
  - 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
```