From 4379fb2d9aa54c4a80efe037ad415d0fcbfe9ad7 Mon Sep 17 00:00:00 2001 From: wompmacho Date: Tue, 28 Apr 2026 01:45:38 +0000 Subject: [PATCH] add notes on labels setup for nginx/pihole sautomation --- projects/Pihole/index.md | 28 ++++++++++++++++++++++++++- projects/nginx-proxy-manager/index.md | 26 +++++++++++++++++++++++++ 2 files changed, 53 insertions(+), 1 deletion(-) diff --git a/projects/Pihole/index.md b/projects/Pihole/index.md index be064b1..114726b 100644 --- a/projects/Pihole/index.md +++ b/projects/Pihole/index.md @@ -14,11 +14,37 @@ without installing any client-side software. Useful for blocking ad services at a DNS level. It uses a list of known ad services stored on github, can add your own. It can also operate as a internal dns router and dhcp server. +## Automation (Docker Labels) + +To automate adding Custom DNS entries to Pi-hole when creating new Docker containers, I use the `docker-pihole-dns-shim` sidecar. This prevents the need to manually update Pi-hole's DNS records every time a new service is deployed. + +### Docker Compose Example (The Shim) +The shim runs alongside your other management containers and watches the Docker socket. **Note:** Use the direct IP address of your Pi-hole (e.g., `10.0.0.11`) to ensure the container can reach the API. + +```yaml +{{% include "/srv/configs/docker_compose/pihole-external-dns/docker-compose.yaml" %}} +``` + +### How to Auto-Configure a Service +To create a DNS record in Pi-hole for a new container, add the following label to its `docker-compose.yaml`. The shim will automatically detect this and call the Pi-hole API. + +```yaml +services: + my-app: + image: my-app:latest + labels: + # Format: [["domain", "IP_Address"]] + - "pihole.custom-record=[[\"myapp.wompmacho.com\", \"10.0.0.190\"]]" +``` + +> [!important] Reverse Proxies +> When using a reverse proxy like Nginx Proxy Manager, you should point the Pi-hole DNS record to the **IP of the Docker host/Proxy** (e.g., `10.0.0.190`), *not* the internal Docker IP of the individual container. + ## Pihole Setup If you have a raspberry-pi or another device, its super easy to get things going. - +... - [pihole setup](https://github.com/pi-hole/pi-hole/?tab=readme-ov-file#one-step-automated-install). Any debian based system should be able to get things going quickly. Then all you diff --git a/projects/nginx-proxy-manager/index.md b/projects/nginx-proxy-manager/index.md index 5b57a9f..561ebd5 100644 --- a/projects/nginx-proxy-manager/index.md +++ b/projects/nginx-proxy-manager/index.md @@ -32,6 +32,32 @@ configurations. {{% include "/srv/configs/docker_compose/nginx-proxy-manager/docker-compose.yaml" %}} ``` +## Automation (Docker Labels) + +To avoid manually configuring Proxy Hosts in the UI (and to keep configuration tightly coupled with the services themselves), I use the `npm-sync` sidecar container. + +This sidecar monitors the Docker socket. When a container spins up with specific labels, `npm-sync` automatically talks to the Nginx Proxy Manager API and creates the Proxy Host. When the container is destroyed, the route is cleaned up. + +### How to Auto-Configure a Service +To expose a new container, simply add the following labels to its `docker-compose.yaml`. You do not need to touch the NPM UI. + +```yaml +services: + my-app: + image: my-app:latest + labels: + - "npm.proxy.domains=myapp.wompmacho.com" # The URL + - "npm.proxy.port=8080" # Internal port the app listens on + - "npm.proxy.scheme=http" # Usually http or https + - "npm.proxy.ssl.force=true" # Force HTTPS + - "npm.proxy.ssl.letsencrypt=true" # Auto-provision SSL certificate +``` + +> [!important] Direct Edits +> Avoid making direct edits to NPM `.conf` files on the host, as it will desync the database and the Web UI. Always use the Web UI or API-driven automation like `npm-sync`. + +## Nginx routing + Nginx gives you that great routing to your internal networked servers. Also helps you set up your DNS both inside and outside the network. Can be a little confusing at first.