Install NetBox

What NetBox is

A register of technical equipment and networks. Which computers you have, which IP addresses are taken, what is plugged into which outlet, and who is responsible for what. All in one place instead of in three spreadsheets and one person's head.

It sounds boring until the first time someone asks which address the printer has and nobody knows. Or until two people happen to give the same IP address to two different machines and half the network stops working. NetBox exists so that this kind of question has an answer.

For most companies this is too big a tool. It becomes interesting if you do something on the IT side, for example helping an association or a company with their equipment, because then the register is part of the service you sell.

This is a server program

NetBox is not installed like a regular program. It is a web service that runs in containers and that you reach through the browser. The tool that runs them is Docker, the same as in Install Docker. If you do not have Docker in place, start there and come back here.

On Windows, Docker Desktop means that you also get WSL2, which is Windows' built-in Linux. Docker Desktop normally installs it itself, but if you are asked, you should answer yes. Without WSL2, no container starts.

You also need git, which is the program that fetches code from the internet. It does not come with Windows, and that is where many people get stuck on line one.

Windows

Install git first. Open PowerShell and run:

winget install Git.Git

Close the window and open a new one, otherwise PowerShell does not recognize the command yet. Then run the four lines:

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

Linux Mint

The same thing, with two small differences. Git is installed with the package tool, and the copy command has a different name. Open Terminal:

sudo apt-get install git
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 up -d

The first start takes several minutes, because NetBox sets up its database before it opens. Follow along in docker compose logs -f if you want to see what happens, and press Ctrl and C to exit the log without shutting anything down. Then go to http://localhost:8000.

Three things to do first

1. Create an administrator account, because you cannot get in without one: docker compose exec netbox /opt/netbox/netbox/manage.py createsuperuser. It asks for a username and password in the window. This step is missing from surprisingly many guides, and then it looks like the login is broken.
2. Enter your own equipment, not sample equipment. Start with a site and a device. The structure in NetBox is strict, and it only becomes understandable once you try to fit in something you actually have.
3. Register your real network under IPAM, for example 192.168.1.0/24, and enter the addresses you know are taken. It takes twenty minutes and answers the question the tool exists for.

The most common trap

Believing that the container is the backup. Everything you enter ends up in volumes that remain after a restart and upgrade. But if someone runs docker compose down with the -v flag at the end, the volumes are deleted, and the entire registry goes with them. That exact flag appears in every third guide online, because it is convenient when testing. On your real installation it should never be used.

So export the tables to CSV at regular intervals, which you can do from the list views, and put the files where the company stores other things that must not be lost. A CSV file can be opened in any spreadsheet program, even if NetBox is gone.

One more thing about memory: NetBox starts several containers at the same time, including a database and a queue. On a computer with 8 GB of memory it works, but do not leave ten other programs open at the same time and wonder why everything crawls.