↓ Skip to main content
wiki.wompmacho.com

Label-Based Proxy & DNS

·293 words·2 mins·
Docker Automation Pihole Npm Homelab Iac
Michael
Author
Michael
some dude that works on datacenters, plays guitar, streams, has a lot of side projects and unhealthy addiction to ow

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.