---
title: "Label-Based Proxy & DNS"
description: "How to automate Nginx Proxy Manager and Pi-hole DNS using Docker labels."
date: 2026-04-28T14:45:00-04:00
lastmod: 2026-04-28
author: wompmacho
tags: ["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.

<!-- more -->

## 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](https://github.com/Redth/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](https://github.com/theonlysinjin/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](https://git.wompmacho.com/wompmacho/configs/src/branch/main/docker_compose/dozzel/docker-compose.yaml), the configuration is clean, portable, and self-documenting:

```yaml
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.
