Metadata-Version: 2.4
Name: local-dev-proxy
Version: 1.0.0rc2
Summary: Connect local applications to a shared Traefik development proxy
Keywords: docker,compose,traefik,development,proxy
Author: SmileyChris
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development
Requires-Dist: click>=8.2,<9
Requires-Dist: ruamel-yaml>=0.18.10,<0.19
Requires-Python: >=3.11
Project-URL: Homepage, https://github.com/SmileyChris/local-dev-proxy
Project-URL: Documentation, https://github.com/SmileyChris/local-dev-proxy/tree/main/docs
Project-URL: Repository, https://github.com/SmileyChris/local-dev-proxy
Project-URL: Issues, https://github.com/SmileyChris/local-dev-proxy/issues
Description-Content-Type: text/markdown

# Local Development Proxy

A single, persistent [Traefik](https://traefik.io/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](https://docs.astral.sh/uv/getting-started/installation/), and loopback
port 80 available. Start the proxy without cloning this repository:

```sh
uvx local-dev-proxy
```

Open [http://traefik.localhost](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:

```sh
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:

```yaml
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](docs/integrating-applications.md) 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](docs/generating-an-override.md).

## Documentation

- [Architecture](docs/architecture.md) — ownership, discovery, networking, and
  hostname conventions
- [Integrating applications](docs/integrating-applications.md) — complete
  Compose examples and application requirements
- [Generating Compose configuration](docs/generating-an-override.md) — add an
  existing service or scaffold a Dockerfile or host-native application
- [Operating the proxy](docs/operations.md) — lifecycle, upgrades, ports, and
  inspection
- [Troubleshooting](docs/troubleshooting.md) — common failures and diagnostic
  commands
- [Security and trust](docs/security.md) — Docker socket and package-trust
  risks
- [Development and releases](docs/development.md) — fixtures, tests, CI, and
  release-candidate checks


## License

[MIT](LICENSE)
