# Convert a Compose Project's Dockerfiles to Multi-stage Builds

Yes. An agent rewrites the single-stage Dockerfiles as multi-stage builds, keeps the non-root user and health checks, runs the stack and opens a PR.

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

## What the agent does

The agent starts by finding which images are single-stage and what each one carries into production. In a sample like `nginx-wsgi-flask` in docker/awesome-compose, `compose.yaml` builds two services: `flask-app` from `flask/` with a `command` of `gunicorn -w 3 -t 60 -b 0.0.0.0:8000 app:app` and a `curl`-based health check on `/flask-health-check`, and `nginx-proxy` from `nginx/`, which mounts `default.conf` to `/tmp/default.conf`, runs `start.sh` to `envsubst` the `FLASK_SERVER_ADDR` into it and checks `/health-check`. `flask/Dockerfile` is one stage on `python:3.9.2-alpine`: it upgrades pip, installs `curl`, creates a `nonroot` user and `/var/log/flask-app`, switches to `USER nonroot`, copies the whole directory, creates a venv at `/home/app/venv`, runs `pip install -r requirements.txt` (Flask 1.1.1 and gunicorn 20.0.4), has a no-op `RUN export FLASK_APP=app.py`, exposes 5000 although Compose binds 8000, and ends in `CMD ["python", "app.py"]`, which Compose overrides. `nginx/Dockerfile` on `nginx:1.19.7-alpine` adds bash and fixes permissions so nginx can run as `USER nginx`.

For the Flask image the agent writes two stages. A `builder` stage on the same Python base creates the venv and runs `pip install --no-cache-dir -r requirements.txt` with only `requirements.txt` copied first, so a source change no longer reinstalls dependencies; pip's own cache is mounted with `--mount=type=cache,target=/root/.cache/pip` under the `# syntax=docker/dockerfile:1` directive the repository's other samples already use. The `runtime` stage starts from the same base, installs only `curl` for the health check, creates the `nonroot` user and log directory exactly as before, copies the venv from the builder with `COPY --from=builder --chown=nonroot:nonroot`, then copies `app.py` and `wsgi.py`. The no-op `export` line goes, `EXPOSE` becomes 8000 to match the port gunicorn binds, and `CMD` becomes the gunicorn command so the image runs correctly without Compose, while `compose.yaml` keeps its own `command` unchanged. It also adds a `.dockerignore` next to the Dockerfile so `__pycache__` and the `.git` directory stay out of the build context.

The nginx image has no build step, so the agent leaves it single-stage and says why in the pull request, rather than inventing a stage for symmetry. In the sandbox, which has no Docker preinstalled, the agent installs it with `sudo apt-get install -y docker.io`, starts `dockerd`, and uses `docker-compose` v1 from the same package set, since Compose v2 is not in that package. It runs `docker-compose build`, then `docker-compose up -d`, waits for both health checks to report healthy with `docker-compose ps`, and requests `http://localhost/`, `/info`, `/cache-me` and `/health-check` through the proxy with `curl` to show the app answers behind nginx as before. It compares `docker image ls` before and after for the Flask image so the pull request can quote the size change it measured rather than an estimate.

Last, it updates the sample's `README.md` where it describes the Flask image, and runs `hadolint` on both Dockerfiles, noting any warning it chose to keep, such as an unpinned `apk add curl`, with a reason. The pull request pastes the build log, the health check output, the curl responses and the two image sizes.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Convert the single-stage Dockerfiles in this Docker Compose project to multi-stage builds and open a pull request. Read compose.yaml and every Dockerfile, requirements file and start script first. For each image that installs dependencies or builds assets, add a builder stage that installs them with the lockfile or requirements copied first and a cache mount, and a runtime stage that copies only the built output or virtual environment, keeps the existing non-root user, health check tooling and ports, and sets CMD to the command the service actually runs. Leave images with no build step single-stage and say why. Add a .dockerignore per build context. The sandbox has no Docker: install docker.io, start dockerd and use docker-compose. Build the stack, bring it up, wait for the health checks, curl each route through the proxy, and record the image sizes before and after. Run hadolint on the Dockerfiles. Quote all of that output and update the README where it describes the images.",
  "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 that rewrites `flask/Dockerfile` as a `builder` and `runtime` pair, adds `flask/.dockerignore`, touches the paragraph in `README.md` that describes the Flask image, and leaves `nginx/Dockerfile`, `compose.yaml`, `app.py`, `wsgi.py` and `requirements.txt` unchanged. The `nonroot` user, the log directory and the `curl` health check survive the rewrite.

The description quotes the `docker-compose build` log with both stages, the `docker-compose ps` output showing `flask-app` and `nginx-proxy` healthy, the `curl` responses for `/`, `/info`, `/cache-me` and `/health-check` through the proxy, the `docker image ls` lines for the Flask image before and after, and the `hadolint` result with a sentence on each kept warning. It explains why the nginx image stays single-stage.

Before merging, a reviewer checks that the `EXPOSE` and `CMD` changes match how they run the image outside Compose, that nothing the app reads at runtime was left in the builder stage, and that the `.dockerignore` does not exclude a file the app needs. Then they rebuild locally once with `docker compose build --no-cache` to see the same two stages.

## Run it on every Compose project with single-stage images

A platform team with many Compose projects sends one `POST /o/{org}/sessions` per repository with this prompt and the repository in `resources`. `GET /o/{org}/github` lists the repositories the Rush GitHub App installation reaches, so a script can grep each clone's Dockerfiles for a single `FROM` and start a run only where it finds one. Each run reads that project's own base images, package manager and health checks, so a Node image gets an `npm ci --omit=dev` runtime stage and a Go image gets a static binary copied onto a distroless base.

Set a webhook URL on the API key and Rush POSTs `run.completed` or `run.failed` when each turn ends, with `session_url` to read the pull request link. Send a fresh UUID as `request_id` with each request so a retried request returns the run already started.

## Why run it on Rush?

A multi-stage rewrite is only as good as the run that proves it: the image has to build, the container has to pass its health check, and the routes have to answer through the proxy as before. In its own sandbox the agent installs Docker, builds and starts the real stack from `compose.yaml`, measures the images, and keeps every command and its output in the run's record, so the size change in the pull request is a number it read and not a guess.

Nothing changes on a laptop and no stale image is left in a local daemon. The same request runs across every Compose repository a team owns at once, each in its own sandbox, each opening a pull request with its own measured before-and-after.

## Frequently asked questions

### Will the containers still run as the non-root user?

Yes. The `runtime` stage recreates the `nonroot` user and the log directory exactly as the single-stage file did, and copies the venv and source with `--chown=nonroot:nonroot`. The agent checks `docker-compose exec flask-app id` in the sandbox and quotes it.

### Why did the nginx image stay single-stage?

Because it installs nothing that a build stage could leave behind: it copies a config and a start script onto the official `nginx` image. A second stage would add lines without removing anything from the final image, and the pull request says so rather than adding one for symmetry.

### Does it change the ports or commands Compose uses?

No. `compose.yaml` keeps its `command` and port mappings. The Dockerfile's `EXPOSE` and `CMD` are changed to match what the service actually runs, so the image behaves the same when started without Compose, which is also what a hosted container platform will do with it.

### How does the agent run Docker if the sandbox has none?

It installs `docker.io` with `apt-get`, starts `dockerd`, and uses `docker-compose` v1, which that package set provides; Compose v2 is not in it. The build, the health checks and the curl checks all run against that daemon inside the sandbox, and the commands are in the run's record.

## More Docker Compose jobs

- [Run Docker Compose Services as a Non-Root User](https://getrush.ai/run/add-non-root-user/docker-compose/)
- [Add a Production Override to a Docker Compose Project](https://getrush.ai/run/add-production-compose-override/docker-compose/)
- [Add Renovate to Keep Docker Compose Image Tags Current](https://getrush.ai/run/add-renovate/docker-compose/)

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

- [Add Mutation Testing to a PHP Library with Infection](https://getrush.ai/run/add-mutation-testing/php/)
- [Add Constraint Naming Conventions to Alembic Migrations](https://getrush.ai/run/add-naming-conventions/alembic/)
- [Add a Native Menu to a Tauri App](https://getrush.ai/run/add-native-menu/tauri/)

## 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/)
