What NetBox does
NetBox documents a network and the infrastructure behind it. On the IPAM side it manages hierarchical prefixes, IP ranges and addresses, VLANs and VRFs, and calculates the free space of every network. On the DCIM side it describes sites, racks and their elevations, devices, their interfaces, cables and power. The two meet: an IP address belongs to a device interface, mounted in a rack at a site.
The project is released under the Apache-2.0 license. The official Docker stack, netbox-docker, relies on PostgreSQL and on Valkey (or Redis) for caching and the background task queue. On a VPS, the application and its worker use less than 1 GB of memory at rest.
What NetBox gives you
- A single source of truth — the intended state of the network, instead of ten files that contradict each other.
- An IPAM that calculates — free space per prefix, next available address, duplicate detection.
- A map of your racks — every device in its place, with its ports and cables.
- An API for every object — REST and GraphQL, with OpenAPI documentation served by the instance.
- A change log — who changed what and when, with the before and after state.
- Automation — webhooks, custom scripts, Ansible dynamic inventory.
Spreadsheet or NetBox on your VPS
Scroll the table
| Shared spreadsheet | NetBox on your VPS | |
|---|---|---|
| Address assigned twice | Nothing prevents it | Flagged on entry |
| Free space of a network | Counted again by hand | Calculated for every prefix |
| Link between address, device, rack | Copied columns | Linked objects |
| Change history | File versions | Per-object change log |
| Read by your scripts | CSV export | REST and GraphQL API |
Before you start
Plan an Ubuntu 24.04 VPS with at least 2 GB of RAM, 4 GB for a team, 2 vCPUs and 20 GB of disk, with Docker and the Compose plugin installed. You also need a hostname pointing to the VPS, for example netbox.example.com: NetBox only accepts forms, login included, from the origin declared in CSRF_TRUSTED_ORIGINS, and it will be served over HTTPS.
Install NetBox with Docker Compose
Prepare the folder and the .env file
This file holds the instance secrets.
SECRET_KEYandAPI_TOKEN_PEPPER_1must be at least 50 characters long: the first signs sessions, the second is used to hash API tokens.mkdir -p /opt/netbox && cd /opt/netbox cat > .env <<EOF DB_PASSWORD=$(openssl rand -hex 16) REDIS_PASSWORD=$(openssl rand -hex 16) SECRET_KEY=$(openssl rand -hex 32) API_TOKEN_PEPPER_1=$(openssl rand -hex 32) SUPERUSER_PASSWORD=$(openssl rand -hex 16) DOMAIN=netbox.example.com EOF chmod 600 .envWrite the docker-compose.yml file
Four services: PostgreSQL, password-protected Valkey, NetBox and its background worker. The port is only published on the loopback interface: nginx alone will face the Internet.
x-netbox: &netbox image: netboxcommunity/netbox:v4.7.5-5.1.2 restart: unless-stopped user: "netbox:root" environment: &netbox-env DB_HOST: postgres DB_NAME: netbox DB_USER: netbox DB_PASSWORD: "${DB_PASSWORD}" REDIS_HOST: redis REDIS_PASSWORD: "${REDIS_PASSWORD}" REDIS_CACHE_HOST: redis REDIS_CACHE_PASSWORD: "${REDIS_PASSWORD}" REDIS_CACHE_DATABASE: "1" SECRET_KEY: "${SECRET_KEY}" API_TOKEN_PEPPER_1: "${API_TOKEN_PEPPER_1}" SKIP_SUPERUSER: "false" SUPERUSER_NAME: admin SUPERUSER_PASSWORD: "${SUPERUSER_PASSWORD}" LOGIN_REQUIRED: "true" CSRF_TRUSTED_ORIGINS: "https://${DOMAIN}" volumes: - netbox-media:/opt/netbox/netbox/media services: postgres: image: postgres:18.7-alpine restart: unless-stopped environment: POSTGRES_DB: netbox POSTGRES_USER: netbox POSTGRES_PASSWORD: "${DB_PASSWORD}" volumes: - netbox-postgres:/var/lib/postgresql redis: image: valkey/valkey:9.1.3-alpine restart: unless-stopped command: ["valkey-server", "--appendonly", "yes", "--requirepass", "${REDIS_PASSWORD}"] volumes: - netbox-redis:/data netbox: <<: *netbox depends_on: [postgres, redis] ports: - "127.0.0.1:8080:8080" netbox-worker: <<: *netbox depends_on: [netbox] command: ["/opt/netbox/venv/bin/python", "/opt/netbox/netbox/manage.py", "rqworker"] volumes: netbox-postgres: {} netbox-redis: {} netbox-media: {}Start and check
The first start applies every database migration and creates the
adminaccount: allow five to ten minutes on a small VPS. The login page must answer200, and the last command prints the administrator password.docker compose up -d docker compose logs -f netbox # wait for "Initialisation is done" curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8080/login/ grep SUPERUSER_PASSWORD .env
Never change the two secrets afterwards
A new SECRET_KEY logs everyone out; a new API_TOKEN_PEPPER_1 invalidates every API token already issued, and your scripts break at the same time. Back up the .env file along with the database. Likewise, SUPERUSER_PASSWORD is only used on first start: change the password from your profile afterwards.
Serve NetBox over HTTPS behind nginx
NetBox listens in HTTP on 127.0.0.1:8080; nginx terminates TLS and forwards requests to it. Keep X-Forwarded-Proto so the application knows it is served over HTTPS, and a client_max_body_size large enough for attachments and imports.
server {
listen 443 ssl;
server_name netbox.example.com;
ssl_certificate /etc/letsencrypt/live/netbox.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/netbox.example.com/privkey.pem;
client_max_body_size 25m;
location / {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}If the origin does not match CSRF_TRUSTED_ORIGINS, login fails with a 403 "CSRF verification failed" error: check the https:// scheme and the exact hostname.
First steps: site, prefixes and addresses
Log in at https://netbox.example.com/login/ as admin. Start by creating a site, then the prefixes you use (IPAM, Prefixes): NetBox arranges them into a hierarchy automatically and shows how full each one is. Then add your devices (Devices), their interfaces and their IP addresses.
To bring in an existing spreadsheet, every list offers CSV or YAML import: paste the rows, NetBox validates every field and rejects the whole import if one line is wrong, which avoids half-finished migrations.
Automate with the API and Ansible
Create a token from your profile, API Tokens menu. It goes in the Authorization: Bearer header, and the interactive documentation is served at /api/schema/swagger-ui/.
export NETBOX_TOKEN='nbt_xxxxxxxx.yyyyyyyyyyyyyyyy'
curl -s -H "Authorization: Bearer $NETBOX_TOKEN" -H "Accept: application/json" \
"https://netbox.example.com/api/ipam/prefixes/?status=active"
# Reserve the next free address of a prefix (id 1) in one request
curl -s -X POST -H "Authorization: Bearer $NETBOX_TOKEN" -H "Content-Type: application/json" \
-d '{"description": "web-01"}' \
"https://netbox.example.com/api/ipam/prefixes/1/available-ips/"On the Ansible side, the netbox.netbox collection provides a dynamic inventory: your hosts and their groups come from NetBox, no more hand-maintained file. The token is passed in the NETBOX_TOKEN environment variable.
# netbox_inventory.yml — ansible-galaxy collection install netbox.netbox
plugin: netbox.netbox.nb_inventory
api_endpoint: https://netbox.example.com
validate_certs: true
group_by: [sites, device_roles]Back up and upgrade
Two things to back up: the PostgreSQL database and the attachments volume, plus the .env file.
cd /opt/netbox
docker compose exec -T postgres pg_dump -U netbox netbox | gzip > netbox-$(date +%F).sql.gz
docker run --rm -v netbox_netbox-media:/media -v "$PWD":/backup alpine \
tar czf /backup/netbox-media-$(date +%F).tar.gz -C /media .To upgrade, change the image tag in docker-compose.yml, then run docker compose pull and docker compose up -d: migrations are applied on start. Read the release notes before changing major version, and take a backup right before.
NetBox in one click on ServOrbit
The ServOrbit Marketplace installs exactly this stack: official netbox-docker image, PostgreSQL, Valkey and the worker, port published on 127.0.0.1 only, secrets generated, admin account created, login required and HTTPS configured on your domain or on the VPS's free subdomain. The administrator password is shown in your client area.
servorbit.com/ma-en/blog/self-host-netbox-vps-ipam-dcim