TLS

This page explains how to add TLS support for NetBox Docker. There are many ways to do this. But we recommend setting up a reverse proxy that is independent of the NetBox Docker setup.

You can do this by installing a webserver like nginx on your host machine directly (and forward all traffic to the container) or by running such a webserver in a container, as explained below on the example of Caddy.

We strongly advise against changing the Nginx Unit configuration that ships with NetBox Docker. The reason is that we don't see the internal configuration as part of the "user interface" and therefore we change it whenever we think it's necessary. Such changes may also not be mentioned in the release notes either. So it would be up to you to keep your configuration in sync with what the NetBox Docker project comes up with.

TLS using Caddy

Caddy is a powerful webserver written in Go and has many built-in features that make it the perfect fit for our case. It can even automatically create and renew your HTTPS Certificate using Let's Encrypt if you wish.

To begin, you need to create a Caddyfile with the required reverse proxy and TLS settings.

# ./Caddyfile
netbox.example.org, netbox.prod.example.org {   # This line should match the ALLOWED_HOSTS in your NetBox Docker configuration
    reverse_proxy netbox:8080
    encode gzip zstd
    
    tls /etc/ssl/private/cert.crt /etc/ssl/private/key.key
    # or:
    # tls /etc/ssl/private/cert.pem

    log {
      level error
    }
}

Now we need to tell Docker Compose to start Caddy. For this, edit your existing docker-compose.override.yml (or create the file if you don't have one already).

# docker-compose.override.yml
services:
  tls:
    image: caddy:2-alpine
    depends_on:
      - netbox
    volumes:
      - ./cert.crt:/etc/ssl/private/cert.crt:ro,z
      - ./key.key:/etc/ssl/private/key.key:ro,z
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
    ports:
      - 80:80   # Allows for http redirection
      - 443:443

Now run docker compose up and you should be able to access NetBox via HTTPS.

Automatic Certificates

You can use the automatic certificate request and renewal features of Caddy.

NOTE: You need to ensure that the container has access to the internet and that your domain is already correctly configured.

# ./Caddyfile
{
    # Email to use on Let's Encrypt
    email youremail@example
}

netbox.example.org, netbox.prod.example.org {   # This line should match the ALLOWED_HOSTS in your NetBox Docker configuration
    reverse_proxy netbox:8080
    encode gzip zstd

    log {
      level error
    }
}

TLS Using Traefik + LetsEncrypt + Cloudflare DNS verification

Traefik is a modern open source reverse proxy and ingress controller that makes deploying services and APIs easy. Like Caddy, it can automatically provision certificates to your web services via ACME (Letsencrypt etc.) and then proxy traffic to your web apps. All configuration can be placed in docker compose file or using separate dynamic config files.

First, create a "traefik.yml" file at root of your netbox install.

# traefik.yml
api:
  dashboard: true # Set this to false to disable builtin dashboard at :8080
  insecure: false
  debug: false
entryPoints:
  web:
    address: ":80"
    http:
      redirections:
        entryPoint:
          to: websecure
          scheme: https
  websecure:
    address: ":443"
serversTransport:
  insecureSkipVerify: true
providers:
  docker:
    endpoint: "unix:///var/run/docker.sock"
    exposedByDefault: false
certificatesResolvers:
  letencrypt:
    acme:
      email: [email protected]
      storage: /certs/acme.json
      # caServer: https://acme-v02.api.letsencrypt.org/directory # prod (default)
      caServer: https://acme-staging-v02.api.letsencrypt.org/directory # staging
      dnsChallenge:
        provider: cloudflare
        delayBeforeCheck: 10

The caServer is set to staging in this example to not hit LetsEncrypt rate limits while testing. Comment it out and remove comment from the prod line when you are done testing.

When changing from staging to production you need to remove the traefik docker volume to fetch new certificate. Do this by running docker volume rm traefik-certs.

Now we need to edit the docker-compose.override.yml file to include Traefik docker image and set http routing from Traefik to Netbox container:

# docker-compose.override.yml
services:
  netbox:
    # Add following config to your netbox service:
    labels:
      - "traefik.enable=true" # This tells traefik to connect to this container
      - "traefik.http.routers.netbox.rule=Host(`netbox.domain.com`)" # Change this to your hostname
      - "traefik.http.routers.netbox.entrypoints=websecure" # This tells to use HTTPS frontend
      - "traefik.http.routers.netbox.tls=true" # Use TLS
      - "traefik.http.routers.netbox.tls.certresolver=letencrypt" # Use LetsEncrypt to fetch certificates
      - "traefik.http.services.netbox.loadbalancer.server.port=8080" # Tell traefik to send requests to port 8080 in the Netbox container.

  # Service config for Traefik
  traefik:
    image: traefik:v3
    container_name: traefik
    restart: unless-stopped
    security_opt:
      - no-new-privileges:true
    env_file: env/traefik.env # Traefik env file containing your DNS provider credentials 
    ports:
      - 80:80 # HTTP entryPoints
      - 443:443 # HTTPS entryPoints
      - 8080:8080 # Builtin dashboard
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro # Docker socket to watch for Traefik
      - ./traefik.yml:/traefik.yml:ro # Traefik config file
      - traefik-certs:/certs # Docker volume to store the acme file for the Certifactes

volumes:
  traefik-certs:
    name: traefik-certs

And finally we create the env file which contains credentials for your cloudflare DNS zone.

# env/traefik.env
TZ=Europe/Amsterdam # Change to your timezone
[email protected]
CF_DNS_API_TOKEN=YourDNSZoneToken

Now just run docker compose pull and docker compose up -d to download traefik image and start it up. You should be able to browse to https://your.domain.name and open Netbox.

TLS for localhost

Developing locally and testing TLS (i.e. https) features often poses a challenge. This guide is intended for people developing with, on or for NetBox or NetBox Docker on their computer. It allows to access NetBox Docker through TLS on https://localhost:8443, https://127.0.0.1:8443 and https://[::1]:8443. It is based on the setup we recommend above.

First install mkcert on your computer. It creates and installs a local CA-Certificate, which will be used by mkcert to create and sign other certificates. This way, your certificates are trusted on your own computer and you don't get a TLS warning in your tools (browsers, cURL, and so forth).

Begin by creating the certificates for localhost and it's IPv4 and IPv6 addresses using the following commands.

mkcert -install
mkcert localhost 127.0.0.1 ::1

This should have created a file called localhost+2.pem and another file called localhost+2-key.pem. Use these two certificates with the setup proposed above:

# ./Caddyfile
0.0.0.0, ::0, localhost {
    reverse_proxy netbox:8080
    encode gzip zstd
    
    tls /etc/ssl/private/cert.crt /etc/ssl/private/key.key

    log {
      level error
    }
}

# ./docker-compose.override.yml
services:
  tls:
    image: caddy:2-alpine
    depends_on:
      - netbox
    volumes:
      - ./localhost+2.pem:/etc/ssl/private/cert.crt:ro,z
      - ./localhost+2-key.pem:/etc/ssl/private/key.key:ro,z
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
    ports:
      - 80:80 # Allows for http redirection
      - 443:443

Run docker compose up and then you're able to access NetBox at https://localhost.

About hitch

Originally, hitch was suggested to use as a TLS proxy.

We later learned that hitch is protocol agnostic, so it does not know about HTTP. In other words, it did not set X-Forwarded-Proto or X-Forwarded-For headers on requests sent to NetBox, thous it would respond to API requests to https:// with references to http://.