Stop Guessing Your Network
If your network lives in your head, a few screenshots, and a text file you swear you will update later, you are not alone. A lot of homelabs and small environments start exactly like that. It works for a while, right up until you need to answer a simple question and realize you do not actually know what is current anymore.
That is where NetBox comes in.
For this setup, the goal is straightforward: run NetBox on Ubuntu Server 24.04 with [Docker Compose](/blog/stop-uploading-your-memories-to-big-tech-self-host-immich) and use it the way it is meant to be used, as a source of truth for your environment. That means documenting things like IP space, VLANs, devices, and virtual machines in one place instead of spreading that information across random notes and memory.
What NetBox actually solves
The big idea behind NetBox is not just that it stores data. The real value is that it becomes the place you trust for network and infrastructure information.
That matters more than people think.
When you are building a homelab, learning Linux, or trying to level up toward networking and infrastructure work, documentation is one of those habits that separates chaos from repeatability. If you do not know what subnets you already used, which VLANs exist, what devices are deployed at a site, or which VM is tied to which function, every change gets slower and riskier.
NetBox gives you a professional way to track that information.
Based on the focus of this setup, some of the key things you can use NetBox for include:
- IP address management
- Prefixes
- IP ranges
- VLAN-related documentation
- Sites
- Devices
- Virtual machines
That is why this is not just a cool homelab app. It is also useful if you are building skills for real infrastructure and networking work.
Why this belongs in a serious homelab
A lot of people treat documentation like the last step. In reality, it should be part of the build.
If you are running multiple VLANs, testing services, spinning up VMs, or rebuilding parts of your environment often, eventually you hit the point where memory stops being reliable. You might remember the general shape of the network, but not the actual details that matter when troubleshooting or planning changes.
NetBox helps because it gives structure to your environment.
Instead of asking questions like:
- “Did I already use that subnet?”
- “Which device is supposed to be in that site?”
- “What was I using that VM for again?”
You can actually look it up in one place.
That beats spreadsheets when the environment starts growing, because the point is not just storing rows of data. The point is keeping related infrastructure information organized in a way that reflects how your network really works.
The platform used here
The setup centers on Ubuntu Server 24.04 and Docker Compose.
That combination makes sense for a lot of homelab users because it gives you a modern Linux server base with a containerized deployment model that is easier to manage than building every dependency manually. The flow here includes preparing the VM, making sure Docker and Compose are working, creating a dedicated NetBox folder, pulling the example Compose setup, and bringing the stack online.
There is also a quick look at the official docs and install options before jumping into the deployment itself, which is important because NetBox can be installed in more than one way. For this walkthrough, though, the focus stays on Docker Compose.
Why a dedicated Docker server is worth considering
One of the practical points in this setup is the recommendation to think about using a dedicated Docker server in your homelab.
That is a smart habit.
Even in a small environment, separating services in a predictable way makes management easier. If you are going to run multiple containers over time, having a dedicated place for Docker workloads can simplify maintenance, make troubleshooting cleaner, and reduce the chance that your infrastructure turns into a pile of unrelated services glued together on one box.
You do not have to overcomplicate it. The main takeaway is that planning where NetBox lives matters. Since this is the place you want to trust for your infrastructure documentation, it deserves a stable home.
What the deployment flow looks like
The install path here is practical and structured.
At a high level, the process includes:
- Preparing an Ubuntu Server 24.04 VM
- Installing Docker
- Verifying Docker and Compose are functioning properly
- Creating a folder for the NetBox deployment
- Pulling the example Docker Compose setup
- Reviewing what each service in the stack does
- Bringing the stack up
- Verifying ports, logs, and container health
- Logging in for the first time
- Changing the password and creating a new admin user
That flow matters because it keeps you from blindly copying commands and hoping for the best. The health checks and log verification step is especially important. A container stack starting is not the same thing as the application being healthy.
A real gotcha: secret key and API token pepper issues
One of the most useful parts of this walkthrough is the troubleshooting section.
There is a specific issue called out around the secret key and API token pepper error, followed by fixing it. That is exactly the kind of thing that trips people up when they assume a containerized deployment should just work automatically.
So here is the mistake to avoid:
Do not treat initial app secrets like optional details
If your NetBox stack comes up but something is wrong around application secrets, you can end up chasing container-level problems when the real issue is application configuration. This is one of those situations where checking logs and validating the deployment details matters more than simply seeing containers in a running state.
That is why the workflow includes verifying logs and health, not just starting the stack and moving on.
If you skip that step, you can burn a lot of time assuming the problem is Docker itself when it may actually be tied to secret-related configuration inside the NetBox setup.
First login and initial cleanup
Once the stack is up cleanly, the next practical step is getting into NetBox and handling the initial access tasks.
That includes:
- First login
- Changing the password
- Creating a new admin user
That might sound basic, but it is part of doing this the right way. A lot of self-hosted tools get deployed, tested once, and then left in a half-finished state. If NetBox is going to become your source of truth, finish the initial administrative setup properly from the beginning.
The areas in NetBox that matter most early on
One thing I like about the way this is framed is that it does not try to turn NetBox into everything at once.
The tour focuses on the core areas most people can benefit from immediately:
- IPAM
- Prefixes
- IP ranges
- Sites
- Devices
That is the right way to start.
You do not need to model your entire universe on day one. In fact, trying to do that is one of the fastest ways to make documentation feel like a chore. The better approach is to start with the data you already know you need to reference regularly.
For most homelab users, that means network ranges, site structure if you use it, important devices, and systems like VMs that support the services you care about.
Why NetBox beats spreadsheets
Spreadsheets are usually the default documentation tool because they are easy to start and familiar to everyone. The problem is that they tend to become disconnected snapshots of reality.
You add a subnet here, a device there, maybe a VLAN sheet later, and before long you have documentation, but not clarity.
NetBox is positioned differently. It is not just a list of disconnected facts. It gives you a structured inventory of network and infrastructure information that supports real-world use. That makes it more useful when you are trying to understand relationships across your environment instead of hunting for the latest version of a file.
If you have ever opened an old spreadsheet and immediately wondered whether it is current, you already know why a proper source of truth matters.
Best practices that make NetBox useful instead of painful
A few best-practice ideas stand out here, and they are worth taking seriously.
Start small
This is the big one.
Do not try to document every cable, every test VM, and every historical experiment on day one. Start with the core network information and the systems that matter most. Build momentum with clean, useful data.
Keep your data clean
Bad documentation is often worse than no documentation because it creates false confidence. If NetBox is going to be your source of truth, then update it consistently and avoid dumping in messy or incomplete records just to say you have documentation.
Back it up
If you are putting real trust in NetBox, backups are part of the plan. A source of truth that disappears after a mistake or failure is not much of a source of truth.
Understand what NetBox is not
This point really matters.
NetBox is not automation.
It can support better operations by giving you accurate infrastructure data, but that is different from being the automation system itself. Keeping that distinction clear helps set the right expectations from the start.
Who should be doing this
This setup makes sense for a few groups in particular:
Homelab builders
If your lab is getting big enough that memory and screenshots are no longer cutting it, NetBox is a solid next step.
Linux learners
Running something like this on Ubuntu Server 24.04 with Docker Compose is a great way to get more comfortable with self-hosting, containers, logs, and service validation.
People working toward networking or infrastructure roles
Learning how professionals document networks, IPs, VLANs, devices, and VMs is useful on its own. It is one of those skills that translates beyond the lab.
Final thoughts
The biggest win with NetBox is not that it looks polished or that it runs in containers. The win is that it helps you stop guessing.
If you want your homelab to be more than a pile of experiments, documentation has to become part of the workflow. Running NetBox on Ubuntu Server 24.04 with Docker Compose is a practical way to do that, and it gives you a cleaner path to organizing the parts of your environment that actually matter.
Keep it simple, verify your stack properly, watch out for secret-related setup issues, and start with clean data instead of trying to model everything at once.
Catch you in the next one.
~ KeepItTechie