Local Development Proxy

A single, persistent Traefik reverse proxy for independent Docker Compose development projects. Applications opt into a shared network while keeping their own lifecycle.

This is local-development infrastructure, not a production proxy configuration.

Quick start

You need Docker Engine or Docker Desktop, Docker Compose 5.x, uv, and loopback port 80 available. Start the proxy without cloning this repository:

uvx local-dev-proxy

Open http://traefik.localhost for the dashboard. The command creates or reconciles the proxy and waits for it to become healthy. To stop and remove it later, run:

uvx local-dev-proxy down

uvx local-dev-proxy uses the current published CLI release. To hold a specific reviewed version, use uvx local-dev-proxy@1.0.0 instead.

Connect an application

Compose uses the checkout directory as the project name. If that name is unique and contains only lowercase letters, digits, and hyphens, no configuration is needed.

Attach the service to the shared network and opt into Traefik:

services:
  web:
    networks:
      - default
      - local-dev-proxy
    labels:
      - "traefik.enable=true"
      - "traefik.docker.network=local-dev-proxy"
      - "traefik.http.routers.${COMPOSE_PROJECT_NAME}-web.rule=Host(`${COMPOSE_PROJECT_NAME}.localhost`)"
      - "traefik.http.services.${COMPOSE_PROJECT_NAME}-web.loadbalancer.server.port=8000"

networks:
  local-dev-proxy:
    external: true

The application must listen on 0.0.0.0:8000 inside its container. A checkout directory named my-project is available at http://my-project.localhost after docker compose up -d, without DNS or /etc/hosts changes.

See Integrating applications for the full contract, explicit service association, secondary services, multiple checkouts, and framework settings.

Or generate the Compose integration interactively with uvx local-dev-proxy generate; see Generating a local override.

Documentation

• Architecture — ownership, discovery, networking, and hostname conventions
• Integrating applications — complete Compose examples and application requirements
• Generating Compose configuration — add an existing service or scaffold a Dockerfile or host-native application
• Operating the proxy — lifecycle, upgrades, ports, and inspection
• Troubleshooting — common failures and diagnostic commands
• Security and trust — Docker socket and package-trust risks
• Development and releases — fixtures, tests, CI, and release-candidate checks

License

MIT