From d4f325bea0e4baf0ba7cfffa40af669e373c73f4 Mon Sep 17 00:00:00 2001 From: Ryan Merolle Date: Mon, 19 Apr 2021 18:35:38 -0400 Subject: [PATCH] Replace Hitch with Caddy --- TLS.md | 85 +++++++++++++++++++++++++++++++++++++--------------------- 1 file changed, 54 insertions(+), 31 deletions(-) diff --git a/TLS.md b/TLS.md index ccaef50..eec2b1e 100644 --- a/TLS.md +++ b/TLS.md @@ -2,12 +2,14 @@ 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_](#tls-using-hitch). +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.** ## 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`. @@ -23,52 +25,73 @@ 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`](https://hitch-tls.org/) needs these files in a combined form: + + +**Continue with [TLS Using a Caddy Container](#tls-using-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](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:** ```bash -cat localhost+2.pem localhost+2-key.pem > cert_and_key.pem +# 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 + } +} ``` -Continue with [TLS Using Hitch](#tls-using-hitch). +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. -## TLS Using Hitch - -[Hitch](https://hitch-tls.org/) 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: +**Example Caddyfile using ZeroSSL/Let's Encrypt Auto Certification:** ```bash -cat key.pem certificate.pem > cert_and_key.pem +# 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 + } +} ``` -To run the TLS proxy [a Docker image of hitch](https://hub.docker.com/r/zazukoians/hitch) can be used. -Add the following to your `docker-compose.override.yml` file: - +**Example docker-compose.override.yml tweaks to setup the tls container using Caddy:** ```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: 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 + image: caddy:2-alpine depends_on: - netbox volumes: - - ./cert_and_key.pem:/app/cert_and_key.pem # mount the TLS certificate + - ./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: - - 8443:443 # bind the container's port 443 to the host's port 8443; + - 80:80 # Allows for http redirection + - 443:443 ``` -> **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: -> -> ```patch -> # 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 -> ``` \ No newline at end of file