--- name: Proxy Manager slug: proxy-manager version: 1.1.0 description: "Manage the shared nginx-proxy Docker container and its network connections. Auto-discovers app containers via VIRTUAL_HOST labels. Start this first — it creates the shared Docker network used by mysql-manager and worktree-manager." changelog: "v1.1.0: Pin image to jwilder/nginx-proxy:1.3.1, bind port 80 to 127.0.0.1, restrict auto-connect to PROJECT_PREFIX networks only with confirmation prompt, document Docker socket privilege and restart persistence." triggers: - "start proxy" - "stop proxy" - "nginx status" - "proxy status" - "conectar proxy" - "connect proxy" - "proxy-manager" - "rotas do nginx" - "nginx routes" metadata: {"clawdbot":{"emoji":"🔀","requires":{"bins":["docker"]},"os":["linux","darwin"]}} --- # Proxy Manager Manages the shared nginx-proxy Docker container (`jwilder/nginx-proxy`) and the Docker network (`nginx-proxy_net`) used by all dev instances. The proxy auto-discovers containers with `VIRTUAL_HOST` labels and creates routes. It also owns the shared Docker network that allows MySQL and app containers to communicate. ## Architecture ``` proxy-manager/ ├── docker-compose.yml # nginx-proxy container + codai_net network └── run.sh # lifecycle + network connection CLI ``` Start order: **proxy-manager first** (creates the network), then mysql-manager, then worktree-manager. ## Commands ```bash ./run.sh start # start nginx-proxy (creates codai_net network) ./run.sh stop # stop nginx-proxy ./run.sh status # show status, connected networks, active routes ./run.sh connect # connect proxy to instance's Docker network ./run.sh disconnect # disconnect proxy from instance network ./run.sh auto-connect # connect proxy to ALL project networks ./run.sh reload # reload nginx config without restart ``` ## How to Execute Tasks ### First-time setup ```bash cd proxy-manager && ./run.sh start ``` Creates the shared `nginx-proxy_net` Docker network and starts the proxy on port 80. ### After starting an app instance After `worktree-manager start `, connect the proxy so routes become available: ```bash ./run.sh connect ``` Routes: `http://.frontend.localhost` and `http://.backend.localhost` ### After restarting Docker or the host Proxy reconnects automatically via `restart: unless-stopped`. If routes are missing, run: ```bash ./run.sh auto-connect ``` ### Check active routes ```bash ./run.sh status ``` ## Startup Order 1. `proxy-manager start` — creates network, starts proxy 2. `mysql-manager start` — joins the shared network 3. `worktree-manager start ` — starts app containers 4. `proxy-manager connect ` — activates routing ## Configuration | Variable | Default | Purpose | |------------------|---------------------|----------------------------------| | `PROXY_CONTAINER`| `codai_nginx_proxy` | nginx-proxy container name | | `CODAI_NETWORK` | `nginx-proxy_net` | Shared Docker network name | | `PROJECT_PREFIX` | `codai-dev` | Docker Compose project prefix | ## How VIRTUAL_HOST Routing Works 1. App containers declare `VIRTUAL_HOST=.frontend.localhost` as a label 2. `jwilder/nginx-proxy` reads Docker socket events and generates nginx config 3. Proxy container must share at least one Docker network with the app container 4. `./run.sh connect ` connects proxy to the instance's network ## Security Notes - **Docker socket**: The proxy mounts `/var/run/docker.sock:ro` to auto-discover containers. This is required for VIRTUAL_HOST routing but grants the container read access to Docker daemon state. Only run on trusted development machines. - **Port 80**: Bound to `127.0.0.1` — routes are reachable from the host only, not from other machines on the network. - **Image provenance**: Pinned to `jwilder/nginx-proxy:1.3.1`. Review image updates before pulling a newer tag. ## Rules - Start proxy-manager **before** mysql-manager and worktree-manager. - After `worktree-manager start `, always run `proxy-manager connect ` to activate routes. - `auto-connect` only connects to networks matching `PROJECT_PREFIX` and requires confirmation — use `connect ` for targeted single-instance connections. - `stop` does NOT remove the Docker network. Other containers on the network remain reachable. - The container uses `restart: unless-stopped` — it survives Docker daemon restarts. Run `./run.sh stop` when done. ## Related Plugins - `mysql-manager` — shared MySQL container (start after proxy-manager) - `worktree-manager` — app instances and git worktrees (start after both)

Proxy Manager

Description

Latest Changes

Install Proxy Manager with One Click