From a8e3104ec73c43e2f38583ef7e048424b14f62be Mon Sep 17 00:00:00 2001 From: William Trelawny <22324745+willman42@users.noreply.github.com> Date: Fri, 5 May 2023 23:30:54 -0400 Subject: [PATCH 1/4] Create traefik-v2-docker.md Current docs for Traefik config seem to be for Traefik v1 so I've provided some for v2. I also have provided 2 scenarios- a) both Traefik and Pi-hole are containers on same Docker host, and b) Traefik is containerized but Pi-hole is remote. Signed-off-by: William Trelawny <22324745+willman42@users.noreply.github.com> --- docs/guides/webserver/traefik-v2-docker.md | 65 ++++++++++++++++++++++ 1 file changed, 65 insertions(+) create mode 100644 docs/guides/webserver/traefik-v2-docker.md diff --git a/docs/guides/webserver/traefik-v2-docker.md b/docs/guides/webserver/traefik-v2-docker.md new file mode 100644 index 0000000..015321f --- /dev/null +++ b/docs/guides/webserver/traefik-v2-docker.md @@ -0,0 +1,65 @@ +### Notes & Warnings + +- **This is an unsupported configuration created by the community** +- This describes how to use Traefik v2 in a Docker container (via docker-compose.yml) to serve the Pi-hole web admin interface via https and includes a permenent http -> https redirect. +- This does not describe how to proxy DNS or DHCP requests to Pi-hole, which is not recommended. +- For ACME challenges, the Traefik container may need to be able to resolve the desired Pi-hole hostname without relying on Pi-hole to do so. Provide this via the `extra_hosts` parameter in your Traefik container's config in docker-compose.yml if needed. +- For LetsEncrypt to work Traefik must be reachable on port 80 and 443 from the Internet and have `domain.tld` pointed at its external address. + +### Basic requirements + +1. Have a Traefik v2 Docker container running where it can access port 80 of the Pi-hole server. + +1. The following Traefik static config (passed as `command` arguments to the Traefik container in docker-compose.yml): +``` +- "--providers.docker=true" +- "--providers.docker.network=traefik-net" # replace with your configured Docker network name +- "--entrypoints.web.address=:80" +- "--entrypoints.web.http.redirections.entrypoint.to=websecure" +- "--entrypoints.websecure.address=:443" +- "--certificatesresolvers.letsencrypt.acme.httpchallenge=true" +- "--certificatesresolvers.letsencrypt.acme.email=your-email@example.com" +- "--certificatesresolvers.letsencrypt.acme.storage=acme.json" +- "--certificatesresolvers.letsencrypt.acme.httpchallenge.entrypoint=web" +``` + +3. The next step has 2 scenarios: + +- If Pi-hole is running in a container on the same Docker host as Traefik, put the following `labels` in your Pi-hole container's config in docker-compose.yml: +``` +- "traefik.http.routers.pihole.rule=Host(`pihole.domain.tld`)" +- "traefik.http.routers.pihole.entrypoints=websecure" +- "traefik.http.routers.pihole.tls=true" +- "traefik.http.routers.pihole.tls.certresolver=letsencrypt" +- "traefik.http.routers.pihole.tls.domains[0].main=pihole.domain.tld" +- "traefik.http.routers.pihole.tls.domains[0].sans=pihole.domain.tld" +- "traefik.http.services.pihole.loadbalancer.server.port=80" +``` + +- If Pi-hole is running on a different host, you need to provide the Pi-hole (dynamic) config via a `traefik.yml` file to Traefik. This is best done by bind mounting the local directory containing this file to the `/etc/traefik` directory within the container: +``` +# Traefik container config: +volumes: + - './traefik/fileproviders:/etc/traefik' +``` +``` +# traefik.yml dynamic config for Pi-hole: +http: + routers: + pihole: + rule: Host(`pihole.domain.tld`) + entrypoints: websecure + tls: + certresolver: letsencrypt + domains: + - main: pihole.domain.tld + sans: + - pihole.domain.tld + services: + pihole: + loadbalancer: + servers: + - url: "http://pihole.domain.tld/" + ``` + +4. Restart the Traefik and Pi-hole containers, then you should be able to access your pihole via `https://pihole.domain.tld/` From 1df10c65273c46518b703e0e44777365aaf7fdee Mon Sep 17 00:00:00 2001 From: William Trelawny <22324745+willman42@users.noreply.github.com> Date: Fri, 5 May 2023 23:43:45 -0400 Subject: [PATCH 2/4] Update traefik-v2-docker.md Fixed markdown-lint errors Signed-off-by: William Trelawny <22324745+willman42@users.noreply.github.com> --- docs/guides/webserver/traefik-v2-docker.md | 102 +++++++++++---------- 1 file changed, 53 insertions(+), 49 deletions(-) diff --git a/docs/guides/webserver/traefik-v2-docker.md b/docs/guides/webserver/traefik-v2-docker.md index 015321f..4120105 100644 --- a/docs/guides/webserver/traefik-v2-docker.md +++ b/docs/guides/webserver/traefik-v2-docker.md @@ -11,55 +11,59 @@ 1. Have a Traefik v2 Docker container running where it can access port 80 of the Pi-hole server. 1. The following Traefik static config (passed as `command` arguments to the Traefik container in docker-compose.yml): -``` -- "--providers.docker=true" -- "--providers.docker.network=traefik-net" # replace with your configured Docker network name -- "--entrypoints.web.address=:80" -- "--entrypoints.web.http.redirections.entrypoint.to=websecure" -- "--entrypoints.websecure.address=:443" -- "--certificatesresolvers.letsencrypt.acme.httpchallenge=true" -- "--certificatesresolvers.letsencrypt.acme.email=your-email@example.com" -- "--certificatesresolvers.letsencrypt.acme.storage=acme.json" -- "--certificatesresolvers.letsencrypt.acme.httpchallenge.entrypoint=web" -``` -3. The next step has 2 scenarios: + ``` + - "--providers.docker=true" + - "--providers.docker.network=traefik-net" # replace with your configured Docker network name + - "--entrypoints.web.address=:80" + - "--entrypoints.web.http.redirections.entrypoint.to=websecure" + - "--entrypoints.websecure.address=:443" + - "--certificatesresolvers.letsencrypt.acme.httpchallenge=true" + - "--certificatesresolvers.letsencrypt.acme.email=your-email@example.com" + - "--certificatesresolvers.letsencrypt.acme.storage=acme.json" + - "--certificatesresolvers.letsencrypt.acme.httpchallenge.entrypoint=web" + ``` -- If Pi-hole is running in a container on the same Docker host as Traefik, put the following `labels` in your Pi-hole container's config in docker-compose.yml: -``` -- "traefik.http.routers.pihole.rule=Host(`pihole.domain.tld`)" -- "traefik.http.routers.pihole.entrypoints=websecure" -- "traefik.http.routers.pihole.tls=true" -- "traefik.http.routers.pihole.tls.certresolver=letsencrypt" -- "traefik.http.routers.pihole.tls.domains[0].main=pihole.domain.tld" -- "traefik.http.routers.pihole.tls.domains[0].sans=pihole.domain.tld" -- "traefik.http.services.pihole.loadbalancer.server.port=80" -``` - -- If Pi-hole is running on a different host, you need to provide the Pi-hole (dynamic) config via a `traefik.yml` file to Traefik. This is best done by bind mounting the local directory containing this file to the `/etc/traefik` directory within the container: -``` -# Traefik container config: -volumes: - - './traefik/fileproviders:/etc/traefik' -``` -``` -# traefik.yml dynamic config for Pi-hole: -http: - routers: - pihole: - rule: Host(`pihole.domain.tld`) - entrypoints: websecure - tls: - certresolver: letsencrypt - domains: - - main: pihole.domain.tld - sans: - - pihole.domain.tld - services: - pihole: - loadbalancer: - servers: - - url: "http://pihole.domain.tld/" - ``` +1. The next step has 2 scenarios: -4. Restart the Traefik and Pi-hole containers, then you should be able to access your pihole via `https://pihole.domain.tld/` + - If Pi-hole is running in a container on the same Docker host as Traefik, put the following `labels` in your Pi-hole container's config in docker-compose.yml: + + ``` + - "traefik.http.routers.pihole.rule=Host(`pihole.domain.tld`)" + - "traefik.http.routers.pihole.entrypoints=websecure" + - "traefik.http.routers.pihole.tls=true" + - "traefik.http.routers.pihole.tls.certresolver=letsencrypt" + - "traefik.http.routers.pihole.tls.domains[0].main=pihole.domain.tld" + - "traefik.http.routers.pihole.tls.domains[0].sans=pihole.domain.tld" + - "traefik.http.services.pihole.loadbalancer.server.port=80" + ``` + + - If Pi-hole is running on a different host, you need to provide the Pi-hole (dynamic) config via a `traefik.yml` file to Traefik. This is best done by bind mounting the local directory containing this file to the `/etc/traefik` directory within the container: + + ``` + # Traefik container config: + volumes: + - './traefik/fileproviders:/etc/traefik' + ``` + + ``` + # traefik.yml dynamic config for Pi-hole: + http: + routers: + pihole: + rule: Host(`pihole.domain.tld`) + entrypoints: websecure + tls: + certresolver: letsencrypt + domains: + - main: pihole.domain.tld + sans: + - pihole.domain.tld + services: + pihole: + loadbalancer: + servers: + - url: "http://pihole.domain.tld/" + ``` + +1. Restart the Traefik and Pi-hole containers, then you should be able to access your pihole via `https://pihole.domain.tld/` From 1b7c376e33f68701beb643129eb0f33d96f3f944 Mon Sep 17 00:00:00 2001 From: William Trelawny <22324745+willman42@users.noreply.github.com> Date: Sun, 7 May 2023 17:28:14 -0400 Subject: [PATCH 3/4] Update traefik-v2-docker.md Added link to Traefik docs Signed-off-by: William Trelawny <22324745+willman42@users.noreply.github.com> --- docs/guides/webserver/traefik-v2-docker.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/webserver/traefik-v2-docker.md b/docs/guides/webserver/traefik-v2-docker.md index 4120105..e5e7a50 100644 --- a/docs/guides/webserver/traefik-v2-docker.md +++ b/docs/guides/webserver/traefik-v2-docker.md @@ -1,7 +1,7 @@ ### Notes & Warnings - **This is an unsupported configuration created by the community** -- This describes how to use Traefik v2 in a Docker container (via docker-compose.yml) to serve the Pi-hole web admin interface via https and includes a permenent http -> https redirect. +- This describes how to use [Traefik](https://doc.traefik.io/traefik/) v2 in a Docker container (via docker-compose.yml) to serve the Pi-hole web admin interface via https and includes a permenent http -> https redirect. - This does not describe how to proxy DNS or DHCP requests to Pi-hole, which is not recommended. - For ACME challenges, the Traefik container may need to be able to resolve the desired Pi-hole hostname without relying on Pi-hole to do so. Provide this via the `extra_hosts` parameter in your Traefik container's config in docker-compose.yml if needed. - For LetsEncrypt to work Traefik must be reachable on port 80 and 443 from the Internet and have `domain.tld` pointed at its external address. From 2e3911b209dbaaf8bf51d627fd60bc71a9f52127 Mon Sep 17 00:00:00 2001 From: William Trelawny <22324745+willman42@users.noreply.github.com> Date: Sun, 7 May 2023 17:30:23 -0400 Subject: [PATCH 4/4] Update mkdocs.yml Added "Traefik v2 (with Docker)" and distinguished other Traefik doc link as being for v1. Signed-off-by: William Trelawny <22324745+willman42@users.noreply.github.com> --- mkdocs.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index a391d28..806911d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -182,7 +182,8 @@ nav: - 'Web server': - 'NGINX': guides/webserver/nginx.md - 'Caddy': guides/webserver/caddy.md - - 'Traefik (not in Docker)': guides/webserver/traefik-nodocker.md + - 'Traefik v1 (not in Docker)': guides/webserver/traefik-nodocker.md + - 'Traefik v2 (with Docker)': guides/webserver/traefik-v2-docker.md - 'Router setup': - 'ASUS router': routers/asus.md - 'Fritz!Box (EN)': routers/fritzbox.md