# Add HEALTHCHECK Instructions to Dockerfiles

Yes. An agent adds a health route where a service has none, a HEALTHCHECK to each Dockerfile, matching Compose and Kubernetes probes, builds the images, opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-healthcheck/docker/). 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 every Dockerfile and every file that already talks about health. In an application like dockersamples/example-voting-app there are three: `vote/Dockerfile` builds a Flask app on `python:3.11-slim` in `base`, `dev` and `final` stages, installs `curl` with the comment `Add curl for healthcheck`, and runs gunicorn on port 80; `result/Dockerfile` builds an Express and socket.io app on `node:18-slim`, installs `curl` and `tini`, and listens on `PORT=80`; `worker/Dockerfile` publishes a .NET 7 console program with no port at all. None of the three contains a `HEALTHCHECK` instruction. `docker-compose.yml` gives `vote` a `healthcheck` of `curl -f http://localhost` every 15 seconds with a 10 second `start_period`, gives `redis` and `db` script checks from `healthchecks/redis.sh` and `healthchecks/postgres.sh`, and gives `result` and `worker` nothing, so the `seed` service waits for `vote` only. The Deployments under `k8s-specifications/` have no probes, and `docker-stack.yml` has none either.

The agent adds the checks at the layer that knows the most. In `vote/app.py` the only route is `/`, which renders the template on GET and pushes to Redis on POST, so `curl -f http://localhost` proves the process answers but says nothing about Redis. The agent adds a `GET /healthz` that calls `get_redis().ping()` and answers 200, or 503 with a short body when the ping fails, and puts `HEALTHCHECK --interval=15s --timeout=5s --start-period=10s --retries=3 CMD curl -f http://localhost/healthz || exit 1` in the `final` stage, not the `dev` stage that bind-mounts the source. In `result/server.js` the `/` handler calls `path.resolve` without ever requiring `path`, which the agent notes and fixes with the one-line `require` since the new route lives next to it; `/healthz` runs `SELECT 1` through the existing `pg` `Pool` and answers 503 until the `async.retry` loop has logged `Connected to db`. Its Dockerfile gets the same `HEALTHCHECK` with the `curl` it already installs. The worker has no HTTP server, so the agent reads `Program.cs`, has the loop touch a heartbeat file each iteration, and checks the file's age in `HEALTHCHECK` with `find`, which the runtime image has.

Compose and Kubernetes then mirror the Dockerfiles: `docker-compose.yml` and `docker-compose.images.yml` get a `healthcheck` for `result` on `/healthz` and one for `worker` on the heartbeat, `vote`'s existing check moves to `/healthz`, and `seed` also waits for `result` with `condition: service_healthy`. In `k8s-specifications/vote-deployment.yaml` and `result-deployment.yaml` the containers get `readinessProbe` and `livenessProbe` entries with `httpGet` on `/healthz` port 80, with the same delays as the Dockerfile `start_period`; the worker Deployment gets an `exec` liveness probe on the heartbeat file.

The sandbox has no Docker, so the agent installs it first with `sudo apt-get install -y docker.io` and starts `dockerd`, then builds the three images with `docker build` (the vote image with `--target final`), starts `redis:alpine` and `postgres:15-alpine` on a user-defined network, runs each service image with `docker run -d`, and polls `docker inspect --format '{{.State.Health.Status}}'` until each reports `healthy`, then stops a dependency to show the status flip to `unhealthy`. It does not run `docker compose`, which the `docker.io` package does not include; the Compose files are checked with `docker-compose config` from the v1 package instead.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add health checks to every service in this repository. Read each Dockerfile, docker-compose.yml, docker-compose.images.yml, docker-stack.yml and the Deployments under k8s-specifications first. Give the vote and result services a GET /healthz route that checks their Redis or Postgres connection and answers 503 when it fails, and give the worker a heartbeat file its loop touches. Add a HEALTHCHECK to each Dockerfile with a 15 second interval, 5 second timeout, 10 second start period and 3 retries, using the curl the images already install for the HTTP services and a file-age check for the worker. Mirror the checks as Compose healthchecks, make seed wait for result as well as vote, and add readiness and liveness probes to the Kubernetes Deployments. Install Docker in the sandbox, build the images, run them against Redis and Postgres containers, show each one reach healthy with docker inspect, and open a pull request.",
  "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 changes `vote/app.py`, `vote/Dockerfile`, `result/server.js`, `result/Dockerfile`, `worker/Program.cs`, `worker/Dockerfile`, `docker-compose.yml`, `docker-compose.images.yml` and the three Deployments under `k8s-specifications/`. The description lists each check with its command and timings, pastes the `docker inspect` health status for the three containers as they went from `starting` to `healthy`, and calls out the missing `path` require in `result/server.js` as a fix it made along the way.

The run's record keeps the Docker installation, every `docker build` with its layers and every `docker inspect` poll, so a reviewer can see the exact command that reported `healthy` and the one that reported `unhealthy` after Redis was stopped.

Before merging, a reviewer confirms the timings suit production, where a cold Postgres can take longer than the 10 second start period, checks that the `/healthz` routes are not reachable through a public ingress or are harmless if they are, and decides whether the Swarm stack file should get the same checks, since the pull request leaves `docker-stack.yml` as it was.

## Run it on every new Dockerfile added to the repository

In the console, an automation in the Project that has the repository, with a `github` trigger on `pull_request.opened` and `pull_request.synchronize` and `branch_patterns` for your default branch, starts one run per pull request with the pull request as its context. The prompt tells the run to look for a Dockerfile in the diff without a `HEALTHCHECK`, add one that fits the service, mirror it in Compose and Kubernetes, and push to the pull request's branch.

From your own server, the same work is one `POST /o/{org}/sessions` per repository with this body and the repository in `resources`, with a `request_id` that is a UUID v5 of the repository name so a retried call returns the run already started. A webhook URL on the API key reports `run.completed` with the `session_url` to read the pull request link from.

## Why run it on Rush?

A health check that only proves the process is up is the one that stays green through an outage. Writing one that checks the dependency means reading how each service connects: Flask with a per-request Redis client in `g`, Express with a `pg` pool behind a retry loop, a .NET loop with no listener at all. The agent reads those files, writes a check per service, and proves each one in a real container before the pull request exists.

The sandbox is its own computer, so installing Docker, building three images and running five containers leaves nothing on a laptop, and every build and inspect command stays in the run's record with its output. Several repositories can get the same treatment at once, each in its own sandbox with its own pull request.

## Frequently asked questions

### Why not just use curl on / like the Compose file already does?

Because `/` on the vote service renders a template without touching Redis on a GET, so the container stays healthy while every vote fails to enqueue. The `/healthz` route pings Redis, and the result service's route runs `SELECT 1` on Postgres, so `healthy` means the service can do its job.

### What does the worker's check look like without an HTTP server?

The loop in `Program.cs` touches a file on each pass, and the `HEALTHCHECK` fails when that file is older than a few intervals, using `find -mmin` from the runtime image. The pull request shows the command and the age threshold so a reviewer can tune it to the loop's sleep.

### Does the run use docker compose?

No. The sandbox installs Docker from the `docker.io` package, which carries the engine but not the `docker compose` v2 plugin. The agent builds and runs containers with `docker build` and `docker run` on a user-defined network, and validates the Compose files with the v1 `docker-compose config` command.

### Will the health checks run in the existing CI?

The three `call-docker-build-*.yaml` workflows build and push images through a reusable workflow and never start a container, so they build the new `HEALTHCHECK` into the image but do not exercise it. The pull request suggests a smoke job that runs the image and polls `docker inspect`, as a follow-up rather than part of this change.

## More Docker jobs

- [Sign Docker Images with Cosign in CI](https://getrush.ai/run/add-image-signing/docker/)
- [Run Your Docker Images as a Non-Root User](https://getrush.ai/run/add-non-root-user/docker/)
- [Add a Trivy Image Scan to a Docker Build Workflow](https://getrush.ai/run/add-trivy-scan-to-ci/docker/)

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

- [Inflate a Helm Chart With Kustomize helmCharts](https://getrush.ai/run/add-helm-chart-inflation/kustomize/)
- [Generate a Helm Chart README With helm-docs and Fail CI When It Is Stale](https://getrush.ai/run/add-helm-docs/helm/)
- [Add a Horizontal Pod Autoscaler to a Helm Chart](https://getrush.ai/run/add-horizontal-pod-autoscaler/helm/)

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