netbox-docker Documentation

To get NetBox Docker up and running, clone the release branch, prepare the override configuration, and start the containers using Docker Compose. Once running, the application is accessible at http://0.0.0.0:8000/.

git clone -b release https://github.com/netbox-community/netbox-docker.git
cd netbox-docker
# Copy the example override file
cp docker-compose.override.yml.example docker-compose.override.yml
# Read and edit the file to your liking
docker compose pull
docker compose up

After the containers are running, you must create a superuser to access the NetBox web interface. Run the createsuperuser command via docker compose exec targeting the netbox service.

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

NetBox Docker requires the following minimum versions of Docker and Docker Compose:

• Docker: 20.10.10 or higher
• containerd: 1.5.6 or higher
• docker-compose: 1.28.0 or higher

To run the test script, which executes NetBox's unit tests and verifies that the container starts correctly, use the following command:

IMAGE=docker.io/netboxcommunity/netbox:latest ./test.sh

The postgres service uses the docker.io/postgres:18-alpine image. Database credentials and configuration are managed via the env/postgres.env file. Data is persisted in the netbox-postgres volume.

services:
  postgres:
    image: docker.io/postgres:18-alpine
    env_file: env/postgres.env
    volumes:
      - netbox-postgres:/var/lib/postgresql

NetBox uses Valkey (a Redis compatible provider) for both standard Redis tasks and caching.

• redis: Uses env/redis.env and persists data in netbox-redis-data.
• redis-cache: Uses env/redis-cache.env and persists data in netbox-redis-cache-data.

Both services require the REDIS_PASSWORD environment variable to be set for authentication.

services:
  redis:
    image: docker.io/valkey/valkey:9.1-alpine
    env_file: env/redis.env
    volumes:
      - netbox-redis-data:/data
  redis-cache:
    image: docker.io/valkey/valkey:9.1-alpine
    env_file: env/redis-cache.env
    volumes:
      - netbox-redis-cache-data:/data

The netbox service uses specific volume mounts for configuration and data persistence. Configuration is read from a local directory, while media, reports, and scripts are stored in named volumes. Environment variables are loaded from env/netbox.env.

services:
  netbox:
    image: docker.io/netboxcommunity/netbox:${VERSION-v4.6-5.0.2}
    env_file: env/netbox.env
    volumes:
      - ./configuration:/etc/netbox/config:z,ro
      - netbox-media-files:/opt/netbox/netbox/media:rw
      - netbox-reports-files:/opt/netbox/reports:rw
      - netbox-scripts-files:/opt/netbox/netbox/scripts:rw