Self-Hosting NetBox: Network Documentation and IPAM Done Right

Every growing homelab or business network eventually reaches the point where you can't keep track of what's connected where. Spreadsheets of IP addresses get stale. That wiki page about the VLAN layout hasn't been updated in months. You're SSHing into switches to figure out what's plugged into port 24.

Photo by Growtika on Unsplash

NetBox is an open source infrastructure modeling tool built by DigitalOcean's network engineering team. It gives you a structured database for documenting IP addresses, racks, devices, cables, circuits, VLANs, and more — with a REST API that makes it programmable.

What NetBox Is (and Isn't)

NetBox is a source of truth for your network infrastructure. It doesn't monitor your network, configure devices, or collect metrics. Instead, it provides a single, authoritative place to document what your network looks like and how it's organized.

Think of it as the database behind your network, not the dashboard on top of it.

NetBox vs. Alternatives

When to choose NetBox

• You need more than just IPAM. If you want to document racks, devices, cables, power, and circuits alongside IP addresses, NetBox does all of it.
• You want an API-first tool. NetBox's REST API is comprehensive — everything you can do in the UI, you can do via API. This makes it easy to integrate with automation tools.
• You run a homelab with real networking gear. If you have managed switches, multiple VLANs, and a growing number of devices, NetBox scales with you.

When phpIPAM is enough

• You only need IP address tracking. phpIPAM is simpler and faster to set up if all you need is subnet management and IP assignment.
• You don't need rack diagrams or cable documentation. phpIPAM stays focused on its core job.

Self-Hosting: What You Need

Server requirements

• CPU: 2+ cores recommended
• RAM: 4 GB minimum (8 GB for large installations)
• Storage: 10 GB+ (depends on the size of your documentation)
• Python: 3.10+
• Database: PostgreSQL 14+
• Cache: Redis 6+

Docker setup

The official NetBox Docker project provides a well-maintained compose setup:

version: "3.8"
services:
  netbox:
    image: netboxcommunity/netbox:latest
    depends_on:
      - postgres
      - redis
    environment:
      DB_HOST: postgres
      DB_NAME: netbox
      DB_USER: netbox
      DB_PASSWORD: your-db-password
      REDIS_HOST: redis
      SECRET_KEY: your-secret-key-at-least-50-chars
      SUPERUSER_NAME: admin
      SUPERUSER_EMAIL: [email protected]
      SUPERUSER_PASSWORD: your-admin-password
    volumes:
      - netbox-media:/opt/netbox/netbox/media
      - netbox-reports:/opt/netbox/netbox/reports
      - netbox-scripts:/opt/netbox/netbox/scripts
    ports:
      - "8000:8080"
    restart: unless-stopped

  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: netbox
      POSTGRES_USER: netbox
      POSTGRES_PASSWORD: your-db-password
    volumes:
      - postgres-data:/var/lib/postgresql/data
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    restart: unless-stopped

volumes:
  netbox-media:
  postgres-data:
  netbox-reports:
  netbox-scripts:

After starting, access NetBox at http://your-server:8000 and log in with your superuser credentials.

Core Concepts

NetBox organizes infrastructure data into several modules:

IPAM (IP Address Management)

The most commonly used feature. NetBox lets you define:

• RIRs (Regional Internet Registries) — who allocates your public IP space
• Aggregates — top-level IP blocks you own or use
• Prefixes — Subnets within your aggregates, with utilization tracking
• IP Addresses — Individual assignments, linked to device interfaces
• VLANs — Layer 2 VLAN definitions, linked to prefixes
• VRFs — Routing table separation for overlapping address spaces

The IPAM module automatically calculates subnet utilization, flags conflicts, and shows you which addresses are available in any prefix.

DCIM (Data Center Infrastructure Management)

For documenting physical infrastructure:

• Sites — Physical locations (data centers, offices, closets)
• Racks — Equipment racks with unit positions
• Devices — Servers, switches, firewalls, UPS units — anything with a network presence
• Interfaces — Network ports on devices
• Cables — Physical connections between interfaces
• Power — PDUs, outlets, and power feeds

In a homelab context, you might have one "site" (your house), one or two "racks" (or just a shelf), and a dozen devices. NetBox handles this just as well as it handles enterprise data centers.

Circuits

Track internet connections, cross-connects, and WAN links:

• Providers — Your ISPs or circuit vendors
• Circuits — Individual connections with contract details
• Circuit terminations — Where each end of a circuit connects

Tenancy

If you manage infrastructure for multiple tenants (or want to tag resources by project/purpose), NetBox supports multi-tenancy with tenant groups and tenant assignments on most object types.

The API

NetBox's API is its killer feature for automation. Every object in the system is accessible via REST:

# List all prefixes
curl -s -H "Authorization: Token your-api-token" \
  http://netbox:8000/api/ipam/prefixes/ | jq '.results[].prefix'

# Find the next available IP in a prefix
curl -s -X POST -H "Authorization: Token your-api-token" \
  http://netbox:8000/api/ipam/prefixes/5/available-ips/ \
  -d '{"description": "new-server"}' | jq '.address'

# Create a new device
curl -s -X POST -H "Authorization: Token your-api-token" \
  -H "Content-Type: application/json" \
  http://netbox:8000/api/dcim/devices/ \
  -d '{"name": "switch-01", "device_type": 1, "site": 1, "role": 1}'

Common integrations:

• Ansible — Use NetBox as an inventory source. The netbox.netbox Ansible collection queries NetBox's API to build dynamic inventories.
• Terraform — The NetBox Terraform provider lets you manage NetBox objects as infrastructure-as-code.
• DNS automation — Webhooks can trigger DNS record creation when new IPs are assigned.
• Monitoring — Auto-register new devices in your monitoring system when they appear in NetBox.

What NetBox Won't Do

• No auto-discovery. NetBox doesn't scan your network to find devices. You populate it manually or via API. (Some plugins add discovery, but it's not built-in.)
• No monitoring or alerting. NetBox is purely a documentation system. Pair it with Prometheus, Zabbix, or LibreNMS for monitoring.
• No device configuration. NetBox documents what your network should look like. Use Ansible, Nornir, or NAPALM to push configurations based on NetBox data.
• Learning curve. The data model is powerful but requires understanding. Plan your taxonomy (regions, sites, device types, roles) before importing data.

Backups

NetBox data lives primarily in PostgreSQL:

# Database backup
docker exec netbox-postgres pg_dump -U netbox netbox > netbox-backup.sql

# Media files (uploaded images, attachments)
docker run --rm -v netbox_netbox-media:/data -v $(pwd):/backup \
  alpine tar czf /backup/netbox-media.tar.gz -C /data .

Automate this daily — NetBox is your source of truth, and losing it means reconstructing your network documentation from scratch.

Bottom Line

NetBox is overkill for a three-device home network. But if you have managed switches, multiple VLANs, a growing device count, and you've ever thought "I should document this properly," NetBox is the right tool.

Start with IPAM — document your subnets and IP assignments. Then add devices and interfaces. Once you have the basics in place, the API opens up automation possibilities that spreadsheets can never match.

The Apache 2.0 license means it's genuinely free with no enterprise paywalls on core features. DigitalOcean actively maintains it, the community is strong, and the plugin ecosystem is growing. For infrastructure documentation, it's the standard.