netbox-docker
The GitHub repository houses the components needed to build NetBox as a container. Images are built regularly using the code in that repository and are pushed to Docker Hub, Quay.io and GitHub Container Registry.
Do you have any questions?
Before opening an issue on Github,
please join our Slack and ask for help in the #netbox-docker
channel.
Quickstart
To get NetBox Docker up and running run the following commands. There is a more complete Getting Started guide on our wiki which explains every step.
git clone -b release https://github.com/netbox-community/netbox-docker.git
cd netbox-docker
tee docker-compose.override.yml <<EOF
version: '3.4'
services:
netbox:
ports:
- 8000:8080
EOF
docker compose pull
docker compose up
The whole application will be available after a few minutes.
Open the URL http://0.0.0.0:8000/
in a web-browser.
You should see the NetBox homepage.
To create the first admin user run this command:
docker compose exec netbox /opt/netbox/netbox/manage.py createsuperuser
If you need to restart Netbox from an empty database often, you can also set the SUPERUSER_*
variables in your docker-compose.override.yml
as shown in the example.
Container Image Tags
New container images are built and published automatically every ~24h.
We recommend to use either the
vX.Y.Z-a.b.c
tags or thevX.Y-a.b.c
tags in production!
vX.Y.Z-a.b.c
,vX.Y-a.b.c
: These are release builds containing NetBox versionvX.Y.Z
. They contain the support files of NetBox Docker versiona.b.c
. You must use NetBox Docker versiona.b.c
to guarantee the compatibility. These images are automatically built from the corresponding releases of NetBox.latest-a.b.c
: These are release builds, containing the latest stable version of NetBox. They contain the support files of NetBox Docker versiona.b.c
. You must use NetBox Docker versiona.b.c
to guarantee the compatibility. These images are automatically built from themaster
branch of NetBox.snapshot-a.b.c
: These are prerelease builds. They contain the support files of NetBox Docker versiona.b.c
. You must use NetBox Docker versiona.b.c
to guarantee the compatibility. These images are automatically built from thedevelop
branch of NetBox.
For each of the above tag, there is an extra tag:
vX.Y.Z
,vX.Y
: This is the same version asvX.Y.Z-a.b.c
(orvX.Y-a.b.c
, respectively). It always points to the latest version of NetBox Docker.latest
This is the same version aslatest-a.b.c
. It always points to the latest version of NetBox Docker.snapshot
This is the same version assnapshot-a.b.c
. It always points to the latest version of NetBox Docker.
Documentation
Please refer to our wiki on GitHub for further information on how to use the NetBox Docker image properly. The wiki covers advanced topics such as using files for secrets, configuring TLS, deployment to Kubernetes, monitoring and configuring LDAP.
Our wiki is a community effort. Feel free to correct errors, update outdated information or provide additional guides and insights.
Getting Help
Feel free to ask questions in our GitHub Community
or join our Slack and ask in our channel #netbox-docker
,
which is free to use and where there are almost always people online that can help you in the Slack channel.
If you need help with using NetBox or developing for it or against it's API
you may find the #netbox
channel on the same Slack instance very helpful.
Dependencies
This project relies only on Docker and docker-compose meeting these requirements:
- The Docker version must be at least
20.10.10
. - The containerd version must be at least
1.5.6
. - The docker-compose version must be at least
1.28.0
.
To check the version installed on your system run docker --version
and docker compose version
.
Updating
Please read the release notes carefully when updating to a new image version. Note that the version of the NetBox Docker container image must stay in sync with the code.
If you update for the first time, be sure to follow our How To Update NetBox Docker guide in the wiki.
Rebuilding the Image
./build.sh
can be used to rebuild the container image. See ./build.sh --help
for more information.
For more details on custom builds consult our wiki.
Tests
We have a test script. It runs NetBox's own unit tests and ensures that all initializers work:
IMAGE=netboxcommunity/netbox:latest ./test.sh
Support
This repository is currently maintained by the community. Please consider sponsoring the maintainers of this project.