diff --git a/TLS.md b/TLS.md index 3589b32..0c26631 100644 --- a/TLS.md +++ b/TLS.md @@ -1,48 +1,110 @@ -This page explains how to add TLS support for Netbox. +This page explains how to add TLS support for NetBox Docker. There are many ways to do this. -We recommend setting up a reverse proxy that is independent of the Netbox Docker setup. +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_](#tls-using-caddy-container). -**We strongly advise _against_ changing the Nginx configuration that ships with Netbox Docker.** +**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 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](https://caddyserver.com/) is a powerful webserver written in Go and with 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 which. + +To begin, you need to create a `Caddyfile` with the required reverse proxy and TLS settings. + +```bash +# ./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 /root/certs/cert.crt /root/certs/key.key + # or: + # tls /root/certs/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). + +```yml +# docker-compose.override.yml +services: + tls: + image: caddy:2-alpine + depends_on: + - netbox + volumes: + - ./cert.crt:/root/certs/cert.crt:ro,z + - ./key.key:/root/certs/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](https://caddyserver.com/docs/automatic-https) of Caddy. + +**NOTE:** You need to ensure that the container has access to the internet and that your domain is already correctly configured. + +```bash +# ./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 -**SKIP to [TLS Using a Caddy Container](#tls-using-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`. +Developing locally and test 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`](https://github.com/FiloSottile/mkcert#installation) 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). +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). -Use `mkcert` to create the certificates for `localhost` and it's IPv4 and IPv6 addresses: +Begin by creating the certificates for `localhost` and it's IPv4 and IPv6 addresses using the following commands. ```bash 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-caddy-container).** - -## TLS Using a Caddy Container - -[Caddy](https://caddyserver.com/) 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:** +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: ```bash -# 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 +# ./Caddyfile +0.0.0.0, ::0, localhost { + reverse_proxy netbox:8080 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. + + tls /root/certs/cert.crt /root/certs/key.key log { level error @@ -50,43 +112,17 @@ netbox.example.org, netbox.prod.example.org { # This line should match your allo } ``` -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:** - -```bash -# Caddyfile using Let's Encrypt -{ - # email to use on Let's Encrypt - email youremail@example.org - # 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:** ```yml -# docker-compose.override.yml +# ./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 + - ./localhost+2.pem:/root/certs/cert.crt:ro,z + - ./localhost+2-key.pem:/root/certs/key.key:ro,z + - ./Caddyfile:/etc/caddy/Caddyfile:ro ports: - 80:80 # Allows for http redirection - 443:443