Ansible Role: NetBox

Install and configure NetBox - an open-source IPAM and DCIM tool - using the netbox-docker image. The role runs five containers on a dedicated netbox Docker network: PostgreSQL (netbox-db), two Valkey instances (netbox-redis for the task queue and netbox-redis-cache for caching), the web application (netbox) and the background worker (netbox-worker).

Dependencies

• docker role (installs Docker).
• traefik role (reverse proxy in front of the web interface).

Both are executed before this role by playbook.yaml and fetched via roles/requirements.yml.

Variables

Variable	Required	Default	Description
vault_netbox_secret_key	Yes		NetBox SECRET_KEY, at least 50 characters
vault_netbox_api_token_pepper	Yes		Pepper for v2 API tokens, at least 50 characters
vault_netbox_db_password	Yes		PostgreSQL password of the NetBox database user
vault_netbox_superuser_password	Yes		Password of the initial superuser
netbox_version	No	"v4.7-5.1.1"	NetBox image tag (managed by Renovate)
netbox_postgres_version	No	"18-alpine"	PostgreSQL image tag (managed by Renovate)
netbox_valkey_version	No	"9.1-alpine"	Valkey image tag (managed by Renovate)
netbox_db_user	No	"netbox"	Database user
netbox_db_name	No	"netbox"	Database name
netbox_superuser_name	No	"admin"	Initial superuser name
netbox_superuser_email	No	"admin@example.com"	Initial superuser email
netbox_http_port	No	"8080"	Host port mapped to port 8080 of the web container

The role also uses the global variable timezone (passed as TZ to all containers), which is not defined in defaults/main.yaml and must be set in the inventory. The role fails in tasks/prerequisite.yaml when a required secret is empty. Keep the real values in sops-encrypted inventory vars.

Example

timezone: "Europe/Amsterdam"
vault_netbox_secret_key: "CHANGE-ME-at-least-50-random-characters"
vault_netbox_api_token_pepper: "CHANGE-ME-at-least-50-random-characters"
vault_netbox_db_password: "CHANGE-ME-db-password"
vault_netbox_superuser_password: "CHANGE-ME-admin-password"

Usage

Run the role through Semaphore using playbook.yaml. The playbook first runs ansible-galaxy install -f -r roles/requirements.yml on localhost, then executes the docker, traefik and netbox roles.

Operational notes

• PostgreSQL data lives in /mnt/netbox/postgres and the task queue data in /mnt/netbox/redis. Media, reports and scripts live in the Docker volumes netbox-media, netbox-reports and netbox-scripts.
• The Valkey instances have no password and are only reachable on the netbox Docker network.
• The superuser is created on first start only; changing the superuser variables afterwards does not alter it.
• The first start runs database migrations, so the web interface can take a minute to respond.
• After the containers are started the role prunes unused Docker containers, images, networks and volumes.