netbox-docker: running NetBox as a Docker Compose stack

What netbox-docker actually packages

NetBox itself is a Django application. Installing it by hand means a Python virtual environment, a PostgreSQL server, a Redis instance for the task queue and cache, a web server, and a set of configuration files that have to agree with each other. netbox-docker removes that assembly work by publishing a container image of NetBox and shipping a Compose file that wires it to its dependencies. The README describes the repository as housing the components needed to build NetBox as a container, with images pushed to Docker Hub, Quay.io and GitHub Container Registry. The audience is infrastructure and network engineers who already run Docker somewhere and want NetBox available without owning a Python deployment. If you have no container runtime and no intention of adding one, this project is not aimed at you.

The Compose topology and what each service holds

The checked-in docker-compose.yml defines the whole system. The netbox service is an anchor reused by netbox-worker, which runs the same image with the command /opt/netbox/venv/bin/python /opt/netbox/netbox/manage.py rqworker and waits for the web service to report healthy before it starts. That split matters: background jobs such as reports, scripts and housekeeping run in a separate container, so a busy job queue does not block HTTP responses.

The dependencies are a postgres service on docker.io/postgres:18-alpine and two Valkey services, redis and redis-cache, on docker.io/valkey/valkey:9.1-alpine. The redis service starts valkey-server with appendonly yes and requires a password read from the environment. Each service has its own healthcheck, and the netbox healthcheck calls /opt/netbox/health.sh with a 90 second start period, which is the part that usually decides how long a first boot takes.

State lives in named volumes rather than bind mounts: netbox-postgres for the database, netbox-redis-data for the queue, and three separate volumes for media, reports and scripts. The configuration directory is mounted read-only at /etc/netbox/config. That read-only mount is the design decision worth noticing. Anything you want to change at runtime goes through the configuration directory or environment files, not through editing files inside the container.

Installing netbox-docker and reaching the homepage

The README gives a four-step quickstart. You clone the release branch, copy the example override file, pull the images and start the stack. The override file is where you set your own values before the first start.

git clone -b release https://github.com/netbox-community/netbox-docker.git
cd netbox-docker
cp docker-compose.override.yml.example docker-compose.override.yml
docker compose pull
docker compose up

According to the README the whole application becomes available after a few minutes at http://0.0.0.0:8000/ and you should see the NetBox homepage. Nothing is usable until an account exists, so the next command creates the first administrator inside the running container.

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

The README also notes that if you restart NetBox from an empty database often, you can set the SUPERUSER_* variables in docker-compose.override.yml instead of running that command each time. Before any of this, the dependency section sets a floor: Docker at least 20.10.10, containerd at least 1.5.6 and docker-compose at least 1.28.0. You can confirm your local versions with docker --version and docker compose version.

Image tags, and why latest is the wrong default

The tag scheme is the most consequential thing in the README. Tags of the form vX.Y.Z-a.b.c carry NetBox version vX.Y.Z plus the support files of netbox-docker version a.b.c. The README states plainly that you must use netbox-docker version a.b.c to guarantee compatibility with that image. There are shorter aliases, vX.Y.Z and vX.Y, that point at the same builds, plus latest-a.b.c and snapshot-a.b.c variants, and the unqualified latest and snapshot tags that always track the newest netbox-docker release of their kind.

The README recommends the vX.Y.Z-a.b.c or vX.Y-a.b.c tags in production. That is a direct warning about the floating tags. The compose file itself defaults to a pinned value through the VERSION variable, so an untouched checkout is not floating. The failure mode appears when you pull a new latest image against an old checkout, or edit the checkout without moving the image: the support files and the application version drift apart, and the README names that mismatch as the thing the a.b.c suffix exists to prevent.

Plugins, LDAP and other things the image does not do for you

The published image is NetBox plus a fixed set of Python dependencies. The Dockerfile shows how the maintainers shape that set: it strips gunicorn because the image serves through Granian, and it rewrites the upstream requirements to install social-auth-core with all extras and django-storages with the azure, boto3, dropbox, google, libcloud and sftp extras. Those edits happen at build time, which means a plugin that needs a dependency outside this set cannot be installed into a running container and survive.

That is why the repository ships build.sh and build-latest.sh. The README states that ./build.sh rebuilds the container image and that ./build.sh --help lists the options, with build-latest.sh as a worked example. Adding a plugin therefore means building your own image, not running pip inside the container. The same logic applies to LDAP and TLS. The README points to the wiki for files-based secrets, TLS, Kubernetes deployment, monitoring and LDAP, and calls the wiki a community effort. Treat those guides as community documentation rather than as tested product surface, and expect to verify the current steps yourself.

NetBox Docker versus a native install or a VM

The obvious alternative is installing NetBox directly on a host or inside a virtual machine, following the upstream NetBox installation documentation. The difference is in what you own. A native install gives you one Python environment you control completely: any plugin, any system package, any init system, and no container runtime in the path. It also means you own PostgreSQL, Redis, the web server, the upgrade procedure for each of them, and the drift between your host and the documented setup.

netbox-docker trades that control for a fixed, reproducible environment. PostgreSQL and Valkey arrive as pinned images, the healthchecks and start ordering are already written, and an upgrade becomes a change to one version value plus a pull. The cost is the boundary described above: you cannot install arbitrary software into the container and keep it, so anything outside the built-in dependency set pushes you toward maintaining your own image build. A VM-based install sits between the two: same operating model as native, but with the host state isolated. If your environment forbids container runtimes, netbox-docker is simply the wrong tool, and the upstream install path is the one to follow.

Upgrades, version sync and the licence

The README is explicit that the container image version must stay in sync with the Git repository version, and that release notes should be read carefully before moving to a new image version. First-time updaters are pointed at the wiki guide How To Update NetBox Docker. That is the real upgrade cost here: it is not the pull, it is the coordination between the tag you deploy and the checkout you keep. New images are built and published roughly every 24 hours, so there is no shortage of versions to choose from, and no obligation to take them.

The licence is Apache-2.0, which is permissive and generally places few conditions on how you run or redistribute the image. The images bundle NetBox and other software under their own licences, and this article is not legal advice; if you redistribute a modified image, check the terms of everything inside it rather than only the repository licence.

Editorial conclusion

Adopt netbox-docker if you want NetBox running from published images and can keep the image tag and the repository checkout in lockstep. Do not adopt it if you need a single-process install with no container runtime, or if you intend to run the unpinned latest tag in production. Before you commit, check that your Docker is at least 20.10.10, your containerd at least 1.5.6 and your docker-compose at least 1.28.0, and read the release notes for the version you are moving to, because the README states the image version must stay in sync with the Git repository version.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. netbox-community/netbox-docker on GitHub
3. Project website
4. README
5. Releases