TLS

This page explains how to add TLS support for Netbox. There are many ways to do this. 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 configuration that ships with Netbox Docker.

TLS for localhost

SKIP to TLS Using a Caddy Container if you have your own CA & generated keys for a production deployment

This guide is intended for people developing with or on 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.

First install mkcert on your computer. It creates and installs a local CA-Certificate, which is used to create 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).

Use mkcert to create the certificates for localhost and it's IPv4 and IPv6 addresses:

mkcert -install
mkcert localhost 127.0.0.1 ::1

This should create a file called localhost+2.pem and another file called localhost+2-key.pem.

Continue with TLS Using a Caddy Container.

TLS Using a Caddy Container

Originally we suggested hitch for TLS proxy, but because hitch is protocol agnostic, It does not know about HTTP. In other words it did not set X-Forwarded-Proto or X-Forwarded-For on requests seen by the backend server and thus NetBox deployments using hitch would respond to API requests with http references instead of https.

Caddy is a powerful, extensible platform to serve your sites, services, and apps, written in Go. It is able to handle HTTP redirection, ensures the API responses reference https, and even auto create/renew your HTTPS Certificate using Let's Encrypt.

First, you need to create a Cadyfile with the required reverse proxy & tls settings you require.

Example Caddyfile using Cetificate/Key you Created:

# Caddyfile using your own certificate.
netbox.example.org, netbox.prod.example.org { # This line should match your allowed hosts
    reverse_proxy netbox:8080 # The reverse_proxy endpoint should point to the name of the netbox docker container
    encode gzip zstd
    tls /root/certs/localhost+2.pem /root/certs/localhost+2-key.pem
    #tls /root/certs/cert.crt /root/certs/key.key # A crt & key can also be used.

    log {
      level error
    }
}

You can use the Auto Certification request and renewal features of Caddy, but be warned, that you need to ensure the container has access the proper access to the internet.

Example Caddyfile using ZeroSSL/Let's Encrypt Auto Certification:

# Caddyfile using Let's Encrypt
{
    # email to use on Let's Encrypt
    email [email protected]
    # https://caddy.community/c/help/ if you have issues
}

netbox.example.org, netbox.prod.example.org { # This line should match your allowed hosts
    reverse_proxy netbox:8080 # The reverse_proxy endpoint should point to the name of the netbox docker container
    encode gzip zstd

    log {
      level error
    }
}

Example docker-compose.override.yml tweaks to setup the tls container using Caddy:

# docker-compose.override.yml
services:
  # ... Include your normal override config but add the tls service & update the existing netbox service to include "expose: ["8080"]
  netbox:
    expose:
      - 8080
  tls:
    image: caddy:2-alpine
    depends_on:
      - netbox
    volumes:
      - ./certs:/root/certs:z # Only needed if you use your own certificate & key or pems
      - ./Caddyfile:/etc/caddy/Caddyfile # Change the ./Caddyfile to wherever you place your Caddyfile
    ports:
      - 80:80 # Allows for http redirection
      - 443:443