diff --git a/TLS.md b/TLS.md index 5551274..621430f 100644 --- a/TLS.md +++ b/TLS.md @@ -77,6 +77,95 @@ netbox.example.org, netbox.prod.example.org { # This line should match the ALL } ``` +## TLS Using Traefik + LetsEncrypt + Cloudflare DNS verification + +[Traefik](https://traefik.io/traefik/) is a modern open source reverse proxy and ingress controller that makes deploying services and APIs easy. Like Caddy, it can automatically provision certificates to your web services via ACME (Letsencrypt etc.) and then proxy traffic to your web apps. +All configuration can be placed in docker compose file or using separate dynamic config files. + +First, create a "traefik.yml" file at root of your netbox install. +```bash +# traefik.yml +api: + dashboard: true # Set this to false to disable builtin dashboard at :8080 + insecure: false + debug: false +entryPoints: + web: + address: ":80" + http: + redirections: + entryPoint: + to: websecure + scheme: https + websecure: + address: ":443" +serversTransport: + insecureSkipVerify: true +providers: + docker: + endpoint: "unix:///var/run/docker.sock" + exposedByDefault: false +certificatesResolvers: + letencrypt: + acme: + email: your@email.com + storage: /certs/acme.json + # caServer: https://acme-v02.api.letsencrypt.org/directory # prod (default) + caServer: https://acme-staging-v02.api.letsencrypt.org/directory # staging + dnsChallenge: + provider: cloudflare + delayBeforeCheck: 10 +``` +The caServer is set to staging in this example to not hit LetsEncrypt rate limits while testing. Comment it out and remove comment from the prod line when you are done testing. + +When changing from staging to production you need to remove the traefik docker volume to fetch new certificate. Do this by running `docker volume rm traefik-certs`. + +Now we need to edit the docker-compose.override.yml file to include Traefik docker image and set http routing from Traefik to Netbox container: +```bash +# docker-compose.override.yml +services: + netbox: + # Add following config to your netbox service: + labels: + - "traefik.enable=true" # This tells traefik to connect to this container + - "traefik.http.routers.netbox.rule=Host(`netbox.domain.com`)" # Change this to your hostname + - "traefik.http.routers.netbox.entrypoints=websecure" # This tells to use HTTPS frontend + - "traefik.http.routers.netbox.tls=true" # Use TLS + - "traefik.http.routers.netbox.tls.certresolver=letencrypt" # Use LetsEncrypt to fetch certificates + - "traefik.http.services.netbox.loadbalancer.server.port=8080" # Tell traefik to send requests to port 8080 in the Netbox container. + + # Service config for Traefik + traefik: + image: traefik:v3 + container_name: traefik + restart: unless-stopped + security_opt: + - no-new-privileges:true + env_file: env/traefik.env # Traefik env file containing your DNS provider credentials + ports: + - 80:80 # HTTP entryPoints + - 443:443 # HTTPS entryPoints + - 8080:8080 # Builtin dashboard + volumes: + - /var/run/docker.sock:/var/run/docker.sock:ro # Docker socket to watch for Traefik + - ./traefik.yml:/traefik.yml:ro # Traefik config file + - traefik-certs:/certs # Docker volume to store the acme file for the Certifactes + +volumes: + traefik-certs: + name: traefik-certs +``` + +And finally we create the env file which contains credentials for your cloudflare DNS zone. +```bash +# env/traefik.env +TZ=Europe/Amsterdam # Change to your timezone +CF_API_EMAIL=your.cloudflare@email.com +CF_DNS_API_TOKEN=YourDNSZoneToken +``` +Now just run `docker compose pull` and `docker compose up -d` to download traefik image and start it up. +You should be able to browse to https://your.domain.name and open Netbox. + ## TLS for localhost Developing locally and testing TLS (i.e. `https`) features often poses a challenge.