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 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://.