How to Run NetBox via LinuxServer.io’s Docker Image

NetBox is “an infrastructure resource modeling (IRM) application designed to empower network automation.” In plain English, NetBox helps administrators track devices, their location in racks, what IP addresses and patch panel ports they are using, etc.

I decided to start using it for tracking the equipment and networking I am running at home now. I have juuuuust enough devices, cabling, and IP addresses in use that NetBox will be handy.† This post is about how I set it up using LinuxServer.io’s image.

This is my eighth post documenting images I use at home. You can also read about how I run the Unifi controller, how I run Plex, how I update DuckDNS, how I run Duplicacy., how I run Heimdall, how I run Librespeed, and how I run Home Assistant.

About LinuxServer.io

LinuxServer.io describes their organization as:

A group of like-minded enthusiasts from across the world who build and maintain the largest collection of Docker images on the web. At our core are the principles behind Free and Open Source Software. Our primary goal is to provide easy-to-use and streamlined Docker images with clear and concise documentation.

I’ve been using LinuxServer.io images for a couple of years. That’s because they’re easy to use, and they’re clearly and concisely documented. I tend to check here first when I need a new image.

Running the Image Via docker-compose

LinuxServer.io only officially supports running the image via docker run or, preferably, docker-compose. Here is what the relevant section of my docker-compose.yml file looks like:

networks:
  netbox:
    name: netbox

services:
  netbox:
    container_name: netbox
    image: lscr.io/linuxserver/netbox:v3.0.7-ls41
    restart: unless-stopped
  
    depends_on:
      - netbox-cache
      - netbox-db
    env_file:
      - ./common.env
      - ./secret.env
    environment:
      - DB_HOST=netbox-db
      - DB_PORT=5432
      - DB_NAME=netbox
      - REDIS_DB_CACHE=0
      - REDIS_DB_TASK=1
      - REDIS_HOST=netbox-cache
      - REDIS_PORT=6379
    networks:
      - netbox
    ports:
      - 8001:8000
    volumes:
      - ${SERVICE_DATA_DIR}/netbox:/config

  netbox-cache:
    container_name: netbox-cache
    image: redis:6.2.6
    restart: unless-stopped
    user: ${PUID}:${PGID}
  
    env_file:
      - ./common.env
      - ./secret.env
    networks:
      - netbox
    volumes:
      - ${SERVICE_DATA_DIR}/netbox-cache:/data

  netbox-db:
    container_name: netbox-db
    image: postgres:14.0-alpine
    restart: unless-stopped
    user: ${PUID}:${PGID}

    env_file:
      - ./common.env
      - ./secret.env
    networks:
      - netbox
    volumes:
      - ${SERVICE_DATA_DIR}/netbox-db:/var/lib/postgresql/data
      - /etc/passwd:/etc/passwd:ro

Overview

We are running three containers here: a database container, a caching container, and NetBox itself. NetBox depends on the two supporting containers and will not run without them.

A More Detailed Review

Let’s step through the most interesting nuggets one by one, starting from the top and working down. In each of the sections below, I’ve elided the parts I’m not currently discussing.

  netbox:
    image: lscr.io/linuxserver/netbox:v3.0.7-ls41

The interesting part here is LinuxServer.io’s new “pseudo-registry” lscr.io. You can learn more about the motivations for it in this blog post.

  netbox:
    depends_on:
      - netbox-cache
      - netbox-db

The depends_on directive is a critical feature of docker-compose. It explicitly tells compose that the netbox-cache and netbox-db containers need to be running in order for NetBox to function. And, as such, docker-compose will ensure those containers are started before starting NetBox itself.

networks:
  netbox:
    name: netbox

services:
  netbox:
    environment:
      - DB_HOST=netbox-db
      - DB_PORT=5432
      - DB_NAME=netbox
      - REDIS_DB_CACHE=0
      - REDIS_DB_TASK=1
      - REDIS_HOST=netbox-cache
      - REDIS_PORT=6379
    networks:
      - netbox
  netbox-cache:
    networks:
      - netbox
  netbox-db:
    networks:
      - netbox

The environment section contains all the configuration variables for NetBox to speak with the database and cache. Most of these values, like names and ports, are either default or examples I found in LinuxServer.io’s Github repositories. These values would be more important if the cache and database were shared by other applications. However, since NetBox has exclusive access to these other systems, the names are less important.

It’s worth pointing out the DB_HOST and REDIS_HOST variables. Because all three containers are on the same network named netbox, they can address each other via the service hash key. Handy.

  netbox-cache:
    image: redis:6.2.6
    user: ${PUID}:${PGID}
  
  netbox-db:
    image: postgres:14.0-alpine
    user: ${PUID}:${PGID}

    volumes:
      - /etc/passwd:/etc/passwd:ro

Here we have the directives for the database and cache services. The most interesting bit are the user: ${PUID}:${PGID} lines.

Since these images are not LinuxServer.io images, they do not follow the PUID and PGID conventions. Instead, we use compose’s built-in user support. Though this mechanism is different than LinuxServer.io’s approach, in my case, it has the same end result: persistent data files get saved with the correct user and group permissions.

The volume mapping for the database container is following the authors’ recommendations — see the “Arbitrary --user Notes section” of their image description.

Phenomenal Work on Display with NetBox

LinuxServer’s NetBox image is yet another example of that team’s phenomenal work. Despite the docker-compose configuration being fairly concise, I can tell that creating these images was no small task. What gives this away are the environment variables. There are quite a few of them, and I’m sure ensuring they populate other configurations in all the right places was not easy.

† To be clear, NetBox is totally overpowered for my small home network needs. I could certainly track everything in a single spreadsheet. But what’s the fun in that? NetBox has been a fun way for me to tinker with more Docker images.