zeigren/netbox repository overview

⁠Docker Stack For netbox⁠

⁠Links

⁠Docker Hub⁠

⁠ghcr.io⁠

⁠GitHub⁠

⁠Tags

• latest
• v2.11.9

⁠Stack

• Python:Alpine - netbox
• Caddy or NGINX - web server
• Postgres:Alpine - database
• Redis:Alpine - cache

⁠Usage

Use Docker Compose⁠ or Docker Swarm⁠ to deploy. Containers are available from both Docker Hub and the GitHub Container Registry.

There are examples for using either Caddy⁠ or NGINX⁠ as the web server and examples for using Caddy, NGINX, or Traefik⁠ for HTTPS (the Traefik example also includes using it as a reverse proxy). The NGINX examples are in the nginx folder.

⁠Recommendations

I recommend using Caddy as the web server and either have it handle HTTPS or pair it with Traefik as they both have native ACME⁠ support for automatically getting HTTPS certificates from Let's Encrypt⁠ or will create self signed certificates for local use.

If you can I also recommend using Docker Swarm⁠ over Docker Compose⁠ as it supports Docker Secrets⁠ and Docker Configs⁠.

If Caddy doesn't work for you or you are chasing performance then checkout the NGINX examples. I haven't done any performance testing but NGINX has a lot of configurability which may let you squeeze out better performance if you have a lot of users, also check the performance section below.

⁠Configuration

Configuration consists of setting environment variables in the .yml files. More environment variables for configuring netbox⁠ can be found in docker-entrypoint.sh and for Caddy in netbox_caddyfile.

Setting the DOMAIN variable changes whether Caddy uses HTTP, HTTPS with a self signed certificate, or HTTPS with a certificate from Let's Encrypt or ZeroSSL. Check the Caddy documentation⁠ for more info.

On first run you'll need to create a superuser by setting the relevant environment variables in the .yml files.

⁠Docker Swarm⁠

I personally use this with Traefik⁠ as a reverse proxy, I've included an example traefik.yml but it's not necessary.

You'll need to create the appropriate Docker Secrets⁠ and Docker Configs⁠.

Any environment variables for netbox in docker-entrypoint.sh can instead be set using Docker Secrets, there's an example of how to do this in the relevant .yml files.

Run with docker stack deploy --compose-file docker-swarm.yml netbox

⁠Docker Compose⁠

Run with docker-compose -f docker-compose.yml up -d. View using 127.0.0.1:9080.

⁠Performance Tuning

The web servers set the relevant HTTP headers to have browsers cache as much as they can for as long as they can while requiring browsers to check if those files have changed, this is to get the benefit of caching without having to deal with the caches potentially serving old content. If content doesn't change that often or can be invalidated in another way then this behavior can be changed to reduce the number of requests.

The number of workers⁠ Gunicorn uses can be set with the GUNICORN_WORKERS environment variable.

⁠Theory of operation

The Dockerfile⁠ uses multi-stage builds⁠ creating a build container that has all the dependencies for the python packages which are installed into a python virtual environment⁠. The production container copies the python virtual environment from the build container and runs netbox from there, this allows it to be much more lightweight.

On startup, the container first runs the docker-entrypoint.sh script before running gunicorn.

docker-entrypoint.sh creates configuration files and runs commands based on environment variables that are declared in the various .yml files.

env_secrets_expand.sh handles using Docker Secrets.