How to Install NetBox on Docker?

Suresh Vina -

In today's quick post, I'll walk you through installing NetBox on Docker. If you've been wanting to get NetBox up and running without getting lost in complex instructions, you're in the right place. I'll show you how straightforward it is to set it up with just a few commands. Before we dive in, I'm assuming you've got a basic understanding of Docker – mainly, how to install it and how to use Docker Compose. If you are new to Docker, feel free to check out my other docker introduction posts here.

Honestly, I'm not the best with Linux. Whenever I try to install any application the traditional way, following every step precisely, something usually goes wrong, and I end up having to start from scratch. That's why the Docker route is a game-changer for me. It simplifies the whole process, practically eliminating those frustrating do-overs. If you're nodding along, thinking you could use a simpler solution too, you're in the right place.

Here are the high-level steps to install NetBox on Docker, broken down into simple, manageable parts. Here is the official installation guide if you want to check it out.

  1. Install Docker and Docker Compose - Update your system and install Docker, then download and install Docker Compose.
  2. Clone the NetBox Docker Repository - Use Git to clone the NetBox Docker project from GitHub into your local environment.
  3. Create a Docker Compose Override File - Customize your NetBox installation by creating a docker-compose.override.yml file, allowing you to specify certain configurations like the port mappings.
  4. Start NetBox with Docker Compose - Use Docker Compose to bring up your NetBox instance, making it accessible via the specified port.
  5. Access NetBox Web Interface - Once NetBox is running, access its web interface through your browser to confirm it's up and operational.
  6. Create an Admin User - Finally, create an administrative user for NetBox, giving you the ability to manage the application fully.

What Exactly is Docker Compose?

Before we dive into the setup, let's quickly talk about Docker Compose. Essentially, Docker Compose is a tool that helps you define and run multi-container Docker applications. With it, you use a YAML file to configure your application's services, networks, and volumes. Then, with a single command, you create and start all the services from your configuration.

This compose file is like a recipe that tells Docker how to set up and link the containers for NetBox, including its dependencies like PostgreSQL and Redis. It specifies everything from which images to use, how they should interact, what environment variables to set, and where to store persistent data. Think of it as a blueprint for Docker to follow, making the whole process of deploying complex applications like NetBox straightforward and repeatable. No need to manually set up each component; Docker Compose handles the heavy lifting, allowing us to focus on using NetBox rather than configuring it.

How to Install NetBox on Docker?

For this guide, I'm using an Amazon Linux 2 image running on an EC2 instance in AWS. First things first, we need to get Docker and Docker Compose up and running on our instance. Here’s how we can do that. If you are using a different flavour or Linux then the process may slightly vary.

Docker Install and Initial Setup

sudo yum update -y
sudo amazon-linux-extras install docker

sudo service docker start
sudo systemctl enable docker

sudo usermod -a -G docker ec2-user

! REBOOT !

docker version

Here is how to install docker-compose

sudo curl -L https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m) -o /usr/local/bin/docker-compose

sudo chmod +x /usr/local/bin/docker-compose

docker-compose version
💡
Quick note on docker compose vs docker-compose You might notice that the official guide mentions docker compose (without a dash), while in this guide, we're using docker-compose (with a dash). Here's the difference, docker-compose is the original command-line tool that comes as a separate package to manage Docker applications based on a YAML file. On the other hand, docker compose (no dash) is a newer integration directly into the Docker CLI, aiming to simplify the process.

NetBox Install

The next step in setting up NetBox on Docker involves getting the NetBox Docker project from its GitHub repository and making a slight tweak to configure it for our needs. After cloning, you'll have a new directory called netbox-docker containing all the necessary Docker files for NetBox.

git clone https://github.com/netbox-community/netbox-docker

cd netbox-docker/

Next, create a docker-compose.override.yml file. This step allows you to customize the Docker Compose setup without altering the original docker-compose.yml file. You might use a text editor like vim (or any editor you're comfortable with) to create and edit this file.

vim docker-compose.override.yml
version: '3.4'
services:
  netbox:
    ports:
    - 8000:8080

This configuration exposes NetBox on port 8000 of the host, mapping it to port 8080 of the NetBox container.

Finally, run docker-compose up and you are all set. Wait for a few minutes for everything to come online and access NetBox GUI via http://<ip_address:8000

Some Errors

In case you get the following error, make sure that you are running the latest docker-compose version.

ERROR: The Compose file './docker-compose.yml' is invalid because:
services.netbox-housekeeping.depends_on contains an invalid type, it should be an array
services.netbox-worker.depends_on contains an invalid type, it should be an array

Please note that on the first try, I did also get this error dependency failed to start: container netbox-docker-netbox-1 is unhealthy but when I tried again, everything went well.

Create admin user

Once you've got NetBox up and running and can access the web interface, there's one more important step, creating an admin user. Before running the command to create an admin user, make sure you're in the right directory where your docker-compose files are located. The below command tells Docker Compose to execute a command inside the netbox service container. 

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

🧬 loaded config '/etc/netbox/config/configuration.py'
🧬 loaded config '/etc/netbox/config/extra.py'
🧬 loaded config '/etc/netbox/config/logging.py'
🧬 loaded config '/etc/netbox/config/plugins.py'
Username (leave blank to use 'unit'): admin
Email address: 
Password: 
Password (again): 
Superuser created successfully.

Closing Up

And there you have it—a straightforward guide to getting NetBox up and running on Docker. With your NetBox instance now ready, dive in and start managing your network more efficiently. Remember, the beauty of Docker makes managing and updating your NetBox instance easier, so you can focus on what's important, managing your network infrastructure. I'm planning on writing more NetBox-related content in the future so, feel free to subscribe to receive all the updates.