# Add Compose Watch to a Docker Compose Project

Yes. An agent replaces the bind mounts in your Compose files with develop.watch sync and rebuild rules, proves them with docker compose watch, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-compose-watch/docker-compose/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent clones the repository into its own cloud sandbox and reads how each sample reloads code today before it writes a `develop` block. In a collection shaped like docker/awesome-compose, no `compose.yaml` has a `develop:` section yet. `react-express-mysql/compose.yaml` gets live reload the old way: the `backend` service bind-mounts `./backend/src:/code/src:ro`, `package.json` and `package-lock.json` into `/code`, runs `npm run start-watch` (which `backend/package.json` defines as `nodemon src/index.js --inspect=0.0.0.0:9229`) and hides the container's `node_modules` behind a named volume called `back-notused`. The `frontend` service mounts `./frontend/src:/code/src` and an anonymous `/code/node_modules` volume so `react-scripts start` picks up edits.

Those mounts are what Compose Watch replaces. For `backend` the agent adds `develop.watch` with one `sync` rule from `./backend/src` to `/code/src`, so nodemon inside the container still sees every save, and one `rebuild` rule on `./backend/package.json` and `package-lock.json`, because a dependency change has to re-run the `npm ci` layer in `backend/Dockerfile` rather than copy a lockfile over a container that already installed the old one. The `frontend` service gets a `sync` rule from `./frontend/src` to `/code/src` with `node_modules` in its `ignore` list, and a `rebuild` rule on its `package.json`. The volumes that only existed to shadow `node_modules` go away along with the bind mounts; `db-data` and the `db-password` secret stay as they are.

`nginx-golang` is the other shape in the repository: a `backend` service built from `backend/Dockerfile` with `target: builder`, where the `dev-envs` stage ends in `go run main.go` and the compiled binary is copied into a `scratch` image. A synced file does nothing for a compiled Go server, so the agent writes a `rebuild` rule on `./backend` for it, and a `sync+restart` rule for the `proxy` service's `./proxy/nginx.conf`, which is mounted read-only today and only takes effect after nginx restarts. Each sample's `README.md` gets a short section showing `docker compose watch` next to the existing `docker compose up -d` instructions.

Then it proves the rules do what the file says. In the sandbox it runs `docker compose watch` for each changed sample, edits a file that a `sync` rule covers, confirms from the service log that nodemon or react-scripts restarted, touches a file under a `rebuild` rule and confirms Compose rebuilt the image. The last step is a `docker compose config` on every file it touched, so a YAML mistake is caught before a reviewer sees it, and a pull request with the diff and the watch logs.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add Compose Watch to the Compose files in this repository that currently use bind mounts for live reload. For each such service, replace the source bind mounts with a develop.watch section: sync rules for source directories that the running process reloads on its own, sync+restart for config files, and rebuild rules for files that change the image such as package.json and lockfiles. Remove volumes that only existed to hide node_modules. Run docker compose config on every file you change, start each changed stack with docker compose watch, make one edit per rule and confirm from the logs that it synced, restarted or rebuilt. Update each sample's README with the watch command. Open a pull request that lists each service and the rules it got.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

What comes back is a pull request on its own branch. Its diff touches the `compose.yaml` of each sample that used bind mounts for reload, removes the `volumes:` entries that pointed at `src` directories or shadowed `node_modules`, and adds a `develop:` block under each affected service with `watch:` rules. The description lists every service with its rules in a table: the path, the container target, the action and, for `sync` rules, what the `ignore` list leaves out. The README changes sit beside them.

The run's record holds the proof. For each sample it keeps `docker compose config` output showing the merged file parsed cleanly, the `docker compose watch` session with the lines Compose prints when it syncs a file or rebuilds a service, and the log line from the service showing nodemon or react-scripts picked the change up. Nothing is pushed to a registry and no image tag changes.

Before merging, a reviewer checks three things: that no `rebuild` rule was turned into a `sync` rule for a compiled service, where a copied file changes nothing; that every path a `sync` rule covers is one the Dockerfile also copies, so a fresh build and a synced edit produce the same container; and that the secrets and database volumes the samples depend on were left alone.

## Run it on every new Compose sample

In the console, an automation with a `github` trigger on `pull_request.opened` and `pull_request.synchronize` starts one run per pull request that adds or changes a `compose.yaml`, with the pull request as its context, in the Project that has the repository. The run reviews the new file for bind mounts used as reload and proposes the equivalent `develop.watch` rules as a review comment or as a commit on the pull request's branch, as the prompt says.

From your own server, the same work is one `POST /o/{org}/sessions` per repository, with the repository in `resources`. A webhook on the API key posts `run.completed` or `run.failed` when the turn finishes, with the `session_url` to read the pull request link and the watch logs.

## Why run it on Rush?

Compose Watch rules are only right once you have seen them fire. The sandbox has Docker, so the agent runs `docker compose watch`, makes the edit, and reads the sync and rebuild lines Compose prints. On a laptop that means pulling every base image and starting every database in the repository; here it happens in a disposable machine whose log is kept with the run.

A repository with many samples is many small, independent changes. One run per sample, or one run that walks all of them, each produce a pull request a reviewer can read file by file, with the `docker compose config` output that shows each file still parses and the watch session that shows each rule did what its action says.

## Frequently asked questions

### Does the stack still work with plain docker compose up?

Yes. `develop.watch` only takes effect under `docker compose watch` or `docker compose up --watch`. A plain `up` ignores the section and runs the image as built, which is why the rules have to cover what the bind mounts used to provide and nothing else.

### Why rebuild on package.json instead of syncing it?

The dependency install happens in an image layer, `npm ci` in `backend/Dockerfile` in the React, Express and MySQL sample. Copying a changed `package.json` into a running container leaves `node_modules` as it was. A `rebuild` rule rebuilds the image and recreates the container, so the new dependency is installed.

### What about the volume that hid node_modules?

It existed because a bind mount of the whole source tree would have shadowed the container's installed `node_modules` with the host's. Once the bind mount is gone the volume has no job, so the agent removes it. If a sample mounts the entire project directory, the agent uses `ignore` on the sync rule instead of keeping the volume.

### Which Compose version do I need?

Compose Watch is part of Docker Compose v2 and ships with current Docker Desktop and the `docker-compose-plugin` package. The agent runs `docker compose version` at the start of the run and notes the version it tested with in the pull request, so you can compare it with what your team runs.

### Will it change samples that already reload correctly without mounts?

No. A service with no bind mount for source code, such as a database image or a static nginx proxy with nothing mounted, gets no `develop` section. The pull request only lists services whose reload path it changed.

## More Docker Compose jobs

- [Add Scheduled Database Backups to a Docker Compose Stack](https://getrush.ai/run/add-database-backups/docker-compose/)
- [Add Dependabot to a Docker Compose Repository](https://getrush.ai/run/add-dependabot/docker-compose/)
- [Add a Dev Container to a Docker Compose Project](https://getrush.ai/run/add-dev-containers/docker-compose/)

## More jobs like this: Hand off a long task

- [Add Response Compression to an Axum API](https://getrush.ai/run/add-compression/axum/)
- [Add Response Compression to an Echo App](https://getrush.ai/run/add-compression/echo/)
- [Add Response Compression to a Fastify App](https://getrush.ai/run/add-compression/fastify/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
