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 Hitch.

We strongly advise against changing the Nginx configuration that ships with Netbox Docker.

TLS for localhost

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. The TLS proxy hitch needs these files in a combined form:

cat localhost+2.pem localhost+2-key.pem > cert_and_key.pem

Continue with TLS Using Hitch.

TLS Using Hitch

Hitch is a high performance TLS proxy by the people behind the famous Varnish.

First you need to combine your TLS key and TLS certificate into one file:

cat key.pem certificate.pem > cert_and_key.pem

To run the TLS proxy a Docker image of hitch can be used. Add the following to your docker-compose.override.yml file:

# docker-compose.override.yml

services:
  # ...

  tls:
    image: zazukoians/hitch
    environment:
      HITCH_PEM: /app/cert_and_key.pem # path within the container to the TLS certificate
      HITCH_PARAMS: --backend=[netbox]:8080 --frontend=[*]:443 # listen on *:443 and forward traffic to netbox:8080
    depends_on:
      - netbox
    volumes:
      - ./cert_and_key.pem:/app/cert_and_key.pem # mount the TLS certificate
    ports:
      - 8443:443 # bind the container's port 443 to the host's port 8443;

NOTE:

Prior to Netbox Docker 1.0.0, the nginx service is was used to serve traffic. The traffic must be forwarded to the nginx service directly:

# Prior to Netbox Docker 1.0.0:
-      HITCH_PARAMS: --backend=[netbox]:8080 --frontend=[*]:443 # listen on *:443 and forward traffic to netbox:8080
+      HITCH_PARAMS: --backend=[nginx]:8080 --frontend=[*]:443 # listen on *:443 and forward traffic to nginx:8080