diff --git a/TLS.md b/TLS.md new file mode 100644 index 0000000..cff4898 --- /dev/null +++ b/TLS.md @@ -0,0 +1,45 @@ +This page explains how to add TLS support for Netbox. +There are many ways to do this. + +## 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`](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). + +Use `mkcert` to create the certificates for `localhost` and it's IPv4 and IPv6 addresses: + +```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`. +The TLS proxy [`hitch`](https://hitch-tls.org/) needs these files in a combined form: + +```bash +cat localhost+2.pem localhost+2-key.pem > localhost+2-full.pem +``` + +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: + +```yml +# docker-compose.override.yml + +services: + # ... + + tls: + image: zazukoians/hitch + environment: + HITCH_PEM: /app/localhost.pem # path within the container to the TLS certificate + HITCH_PARAMS: --backend=[nginx]:8080 --frontend=[*]:443 # listen on *:443 and forward traffic to nginx:8080 + volumes: + - ./localhost+2-full.pem:/app/localhost.pem # mount the TLS certificate + ports: + - 8443:443 # bind the container's port 443 to the host's port 8443 -> https://[::1]:8443 +``` \ No newline at end of file