Deployment guide

NetBox on a VPS: self-hosted IPAM and network inventory

Deploy on a VPS Cloud →

Tutorial

Self-hosting

NetBox on a VPS: self-hosted IPAM and network inventory

The IP address spreadsheet always has one wrong line: an address assigned twice, a server retired but never removed, a VLAN nobody can explain anymore. NetBox replaces that file with a source of truth: every prefix, address, rack and cable is an object linked to the others, browsable in the web UI and driven by an API. This guide installs it on a VPS with Docker Compose, closes it to anonymous visitors, serves it over HTTPS behind nginx and connects it to your scripts and to Ansible.

6 min read3 steps
Contents· What NetBox does1/11
  1. 01What NetBox does
  2. 02What NetBox gives you
  3. 03Spreadsheet or NetBox on your VPS
  4. 04Before you start
  5. 05Install NetBox with Docker Compose
  6. 06Never change the two secrets afterwards
  7. 07Serve NetBox over HTTPS behind nginx
  8. 08First steps: site, prefixes and addresses
  9. 09Automate with the API and Ansible
  10. 10Back up and upgrade
  11. 11NetBox in one click on ServOrbit

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 spreadsheetNetBox on your VPS
Address assigned twiceNothing prevents itFlagged on entry
Free space of a networkCounted again by handCalculated for every prefix
Link between address, device, rackCopied columnsLinked objects
Change historyFile versionsPer-object change log
Read by your scriptsCSV exportREST 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

  1. Prepare the folder and the .env file

    This file holds the instance secrets. SECRET_KEY and API_TOKEN_PEPPER_1 must 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 .env
  2. Write 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: {}
  3. Start and check

    The first start applies every database migration and creates the admin account: allow five to ten minutes on a small VPS. The login page must answer 200, 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.

Share this articleservorbit.com/ma-en/blog/self-host-netbox-vps-ipam-dcim