docs-public/posts/automated-homelab-proxy-dns.md

title, description, date, lastmod, author, tags

title	description	date	lastmod	author	tags
Label-Based Proxy & DNS	How to automate Nginx Proxy Manager and Pi-hole DNS using Docker labels.	2026-04-28T14:45:00-04:00	2026-04-28	wompmacho	docker automation pihole npm homelab iac

Managing a homelab often involves a lot of manual repetition: spin up a container, add a DNS record in Pi-hole, then create a proxy host in Nginx Proxy Manager (NPM).

By leveraging Docker labels, we can treat our homelab as Infrastructure as Code (IaC), defining our entire environment within a single docker-compose.yaml file.

The Core Concept

Instead of configuring our infrastructure in multiple Web UIs, we define the requirements directly at the service level. This ensures that our proxy and DNS settings live and die with the containers they serve. Two key "shim" containers make this automation possible:

1. npm-docker-sync: This container monitors the Docker socket for npm.proxy.* labels. When it detects a new service, it calls the Nginx Proxy Manager API to instantly create or update a proxy host.
2. docker-pihole-dns-shim: Similarly, this service watches for pihole.custom-record labels. It syncs these records to your Pi-hole instance, ensuring that myservice.local always points to your Docker host or reverse proxy IP.

Simple Service Example: Dozzle

For a standard service like Dozzle, the configuration is clean, portable, and self-documenting:

services:
  dozzle:
    container_name: dozzle
    image: ghcr.io/amir20/dozzle:latest
    labels:
      # Nginx Proxy Manager Automation
      - "npm.proxy.domains=dozzle"
      - "npm.proxy.port=8888"
      - "npm.proxy.scheme=http"
      
      # Pi-hole Automation (Point to Docker Host IP)
      - "pihole.custom-record=[[\"dozzle\", \"10.0.0.190\"]]"

When this container starts, the DNS record for dozzle is created, and a proxy host is instantly available in NPM. No manual clicking required.

Why Websockets Matter

If your UI feels unresponsive or "frozen" (common with GTK/Broadway apps like Nicotine+), it’s often because the websocket connection is blocked. Always include npm.proxy.websockets=true in your labels to ensure the reverse proxy allows the real-time communication required by modern interactive apps.

By adopting this Infrastructure as Code approach, we make our homelab reproducible, version-controlled, and significantly easier to maintain.