Install via Docker Compose

The official upstream is netbox-community/netbox-docker. Clone it:

git clone -b release https://github.com/netbox-community/netbox-docker.git
cd netbox-docker
tee docker-compose.override.yml <<'EOF'
services:
  netbox:
    ports:
      - "127.0.0.1:8000:8080"
EOF

docker compose pull
docker compose up -d
docker compose logs -f netbox

Wait until the migrations finish. Then create an admin user:

docker compose exec netbox \
    /opt/netbox/netbox/manage.py createsuperuser

Browse to http://localhost:8000/ and log in.

Reverse proxy

# Caddy
netbox.example.com {
    reverse_proxy 127.0.0.1:8000
}

Set ALLOWED_HOSTS and CSRF_TRUSTED_ORIGINS in env/netbox.env to include the public hostname.

What to model first

Setup order that doesn't backtrack:

  1. Sites & Regions. Even for a homelab, "home", "cottage", "AWS:us-east-1" as separate Sites makes everything else cleaner.
  2. Racks (if applicable). Define racks within sites; later devices live in racks at specific U positions.
  3. Device Roles ("Router", "Switch", "Access Point", "Hypervisor", "Server") and Device Types (Mikrotik CRS328-24P, Dell R720XD, Raspberry Pi 5). Device-type definitions can be imported from the community-maintained devicetype-library.
  4. Manufacturers & Platforms — vendor names + OS (Cisco IOS, RouterOS, Linux, etc.).
  5. Devices. Each device gets a name, role, type, site, optional rack position, status (active / planned / decommissioning).
  6. Interfaces & IP addresses. Per-device, define every physical and virtual interface. Assign IPs from prefixes; NetBox tracks free vs used per prefix.
  7. Cables. Connect device A's interface 1 to device B's interface 3. Visualized in the rack and circuit diagrams.

IPAM: the half people use most

The IPAM (IP Address Management) features are NetBox's most-loved:

  • Aggregates — top-level summaries (e.g. "10.0.0.0/8 is private LAN").
  • Prefixes — subnets within aggregates (e.g. "10.0.20.0/24 is the IOT VLAN").
  • IP Addresses — individual IPs assigned to device interfaces.
  • VLANs — with VLAN groups for scoping (so VLAN 30 at home and VLAN 30 at the cottage are distinct).
  • VRFs — for overlapping address spaces (rare in homelabs, common in service-provider networks).

From the prefix page, NetBox shows the entire utilization: which children prefixes are allocated, which IPs are used vs free, and a "next available" picker for assignments. The combination kills the "which IP is free in this subnet" question that spreadsheets get wrong.

Custom fields & tags

Out of the box, every object can be tagged (free-form labels) or have custom fields added (Site → "Power circuit cost," Device → "Warranty expires," IP → "Public-facing service"). Custom fields make the schema reflect the questions specific to your environment without forking NetBox.

The REST and GraphQL API

Every model is exposed via REST under /api/ and GraphQL at /graphql/. Authenticate with a token (Users → Tokens):

# Get all active routers
curl -H "Authorization: Token <token>" \
    https://netbox.example.com/api/dcim/devices/?role=router&status=active \
    | jq '.results[].name'

# Allocate the next free IP in a prefix
curl -X POST \
    -H "Authorization: Token <token>" \
    -H "Content-Type: application/json" \
    -d '{"description": "new server", "status": "active"}' \
    https://netbox.example.com/api/ipam/prefixes/42/available-ips/

The "available-ips" endpoint is a built-in concurrency-safe allocator — two concurrent calls return different IPs.

Ansible / Terraform integration

NetBox is the source-of-truth for "what should exist," and a config-management tool turns that into "make it so":

  • Ansible — the netbox.netbox collection includes a dynamic inventory plugin. ansible-playbook -i nb-inventory.yml site.yml targets every active device of role "switch" in site "home," pulled from NetBox.
  • Terraform — the e-breuninger/netbox provider can read or manage NetBox state; usually paired the other way (NetBox is the source, Terraform writes to it).
  • Nautobot Golden Config / NetPicker / SuzieQ — tools that pull NetBox's intended state, fetch a device's actual config, and report differences.

Change logging

Every NetBox object has a built-in changelog: every edit is recorded with the user, timestamp, and field-level diff. The "Object History" tab shows the audit trail. For richer review workflows, the optional Branching feature in 4.x lets changes happen in branches that can be reviewed and merged like Git.

Plugins worth knowing

  • netbox-acls — model device access-control-lists alongside their devices.
  • netbox-dns — manage DNS zones and records from NetBox; ANSWER why the spreadsheet exists.
  • netbox-bgp — BGP peers, communities, route policies as first-class objects.
  • netbox-secrets — store device credentials encrypted with a per-user key.

Backups

Just back up the Postgres database (pg_dump) and the media/ volume (custom images, scripts). The Redis state is regenerable. docker compose exec postgres pg_dump -U netbox netbox | gzip > backup.sql.gz.

When NetBox is overkill

For a flat home network with one router and a dozen devices, a text file works. NetBox starts paying off when the questions become "which switch port is that camera on?" or "if I take that switch offline, what breaks?" — questions that grow exponentially with network size.