Getting Started

Getting Started with NetBox Docker

This is a basic introduction on how to get started using NetBox with Docker on your local machine.

Requirements

It is required that you have a recent installation of Docker Community Edition (or compatible) and docker-compose. (The current minimal requirements are defined in our README.md).

You also need to have Git installed.

And finally you should be working on a Linux or macOS computer. NetBox Docker should technically also work on Docker for Windows (with Linux backend) or on the Windows Subsystem for Linux (WSL), but this guide does not cover this (yet).

First Time Setup

The first step is to clone the netbox-docker repository to your computer. For that, open a terminal (e.g. Terminal on macOS or xterm on Linux).

1. First you should navigate to the directory where you would like to clone the project to, e.g. ~/projects/.
2. Second you have to clone the project.
3. Then you should change to the new directory.

# (1)
mkdir -p ~/projects && cd projects

# (2)
git clone -b release https://github.com/netbox-community/netbox-docker.git

# (3)
cd netbox-docker

Now you need to create a new file which defines the port under which NetBox will be available. The file name must be docker-compose.override.yml and its content should be as follows:

version: '3.4'
services:
  netbox:
    ports:
    - 8000:8080

This file will define that NetBox Docker will always listen on port 8000 when it starts up. (Without that file it would listen on a random port so that you can start multiple NetBox instances in parallel.) If you already have something listening on port 8000 feel free to change it.

To get NetBox Docker up-and-running, here are the two final steps:

4. You will need to pull all the containers from the Docker registry. This may take a while, depending on your internet connection.
5. Finally you can start all the required Docker containers.

# (4)
docker compose pull

# (5)
docker compose up

You will see a lot of output on your screen. NetBox will be initializing the database and then start.

The whole application will be available after a few minutes (check with docker ps until the NetBox container status being "healthy"). 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 in a separate terminal:

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

Shutdown

To stop NetBox press Ctrl+C in the same terminal that you ran docker compose up in.

If you started the container with docker compose up -d then use the following command to stop the container:

# Stop all the containers
docker compose stop

# Start the containers again
docker compose start

If you want to stop NetBox and clean up any resources it allocated (database, files, etc.), use the following command. Attention: It will remove any data you have entered in NetBox!

docker compose down -v