extern/netbox-docker
1
0
Fork 0
mirror of https://github.com/netbox-community/netbox-docker.git synced 2024-12-11 09:11:14 +01:00
Code Issues Packages Projects Releases Wiki Activity

Updated TLS (markdown)

Christian Mäder 2021-04-20 10:00:40 +02:00
parent 5c7212abd9
commit b1ff811900
1 changed files with 92 additions and 56 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

148
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