mdnx

Expose Docker services as secure .local domains in development

• Traefik as reverse proxy
• Custom mDNS responder
• Easy to configure with docker labels

Currently on macOS only

How it works

mdnx runs a background daemon (installed as a macOS LaunchAgent) that combines three pieces:

1. Traefik as a reverse proxy in front of your Docker containers.
2. A custom mDNS responder that resolves *.local queries on your local network to your machine's IP.
3. A self-signed CA and TLS certificates so HTTPS on those .local domains works without browser warnings.

Any container with the right labels, on the mdnx Docker network, automatically gets picked up and made reachable at https://<yourhost>.local.

Requirements

• macOS
• Docker (Docker Desktop or compatible)

Install

# Install globally
npm i -g @bitaffair/mdnx

# Create the external Docker network mdnx services attach to
docker network create mdnx

# Init mdnx: starts the daemon, generates a local CA and
# imports it into the macOS System keychain (asks for your sudo password)
mdnx init

Example docker-compose.yml

networks:
  mdnx:
    external: true

services:
  foo:
    image: traefik/whoami
    networks:
      - mdnx
    labels:
      - traefik.enable=true
      - mdnx.enable=true
      - traefik.http.routers.foo.rule=Host(`foo.bar.local`)

# Start the mdnx daemon + Traefik
mdnx start

# Start your environment
docker compose up -d

Your service is now reachable at https://foo.bar.local with a trusted certificate — no /etc/hosts editing, no browser warnings.

Commands

| Command | Description | | ---------------- | --------------------------------------------------------------------------------------------------------- | | mdnx init | Starts the daemon, generates the local CA and imports it into the macOS System keychain (sudo required) | | mdnx start | Installs/loads the daemon (LaunchAgent) and starts Traefik | | mdnx stop | Stops Traefik and unloads the daemon | | mdnx restart | Restarts daemon and Traefik | | mdnx status | Shows daemon status (installed/loaded/running/pid) and, if running, the detected local IP and domains | | mdnx uninstall | Removes the daemon LaunchAgent completely | | mdnx version | Prints the installed mdnx version |

Uninstalling

mdnx stop
mdnx uninstall

This removes the background daemon. If you also want to remove the trusted CA certificate, open Keychain Access, go to the System keychain, find the mdnx CA and delete it.

Troubleshooting

• *.local domain doesn't resolve — make sure mdnx status shows the daemon as running, and that mDNS/Bonjour isn't blocked by your firewall.
• Browser shows a certificate warning — re-run mdnx init to (re-)import the CA into the System keychain, and make sure you trust it (see Keychain Access).
• Service doesn't show up — check that the container has both traefik.enable=true and mdnx.enable=true labels, is attached to the external mdnx network, and defines a traefik.http.routers.<name>.rule with a Host(...) rule.