# Add a Dockerfile to a Medusa Backend

Yes. An agent writes a multi-stage Dockerfile for a Medusa v2 backend in a pnpm monorepo, wires worker mode and migrations, builds and runs it, and opens a PR.

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

## What the agent does

Medusa v2 builds into a directory of its own, so the agent reads the build and the monorepo layout before writing any Docker instruction. In a project laid out like medusajs/dtc-starter, the root `package.json` sets `packageManager` to `pnpm@10.11.1` and `engines.node` to `>=22.23.4`, `pnpm-workspace.yaml` includes `apps/**` but excludes `apps/backend/.medusa/**`, and `turbo.json` declares `build`, `start`, `dev`, `lint`, `test` and `seed` tasks. The backend is `apps/backend`, package `@dtc/backend`, on `@medusajs/medusa`, `@medusajs/framework` and `@medusajs/cli` at `2.22.1`, with scripts `build` (`medusa build`), `start` (`medusa start`), `dev` (`medusa develop`) and three `jest` test modes switched by `TEST_TYPE`. Its `medusa-config.ts` reads `DATABASE_URL`, `STORE_CORS`, `ADMIN_CORS`, `AUTH_CORS`, `JWT_SECRET` and `COOKIE_SECRET` and nothing else; `.env.template` lists those plus `REDIS_URL` and `DB_NAME`. The backend's `.gitignore` already ignores `.medusa`, `/dist`, `/uploads` and `.env`. There is no Dockerfile, no `.dockerignore` and no compose file anywhere; the only workflow is `update.yaml`, which runs Medusa's update action.

Medusa's own deployment guide says `medusa build` writes a standalone server to `.medusa/server`, and that a host runs `npm install`, `npm run predeploy` and `npm run start` inside it, with `predeploy` defined as `medusa db:migrate`. It also says a production app runs as two instances of the same image, one with `MEDUSA_WORKER_MODE=server` that serves the API and the admin, and one with `MEDUSA_WORKER_MODE=worker` and `DISABLE_MEDUSA_ADMIN=true` that runs scheduled jobs and subscribers, and that `medusa-config.ts` has to read those variables into `projectConfig.workerMode`, `projectConfig.redisUrl`, `admin.disable` and `admin.backendUrl`. This config reads none of them yet, so the agent adds those four lines, keeps every default the same when the variables are unset, and adds the `predeploy` script to the backend's `package.json` so the built server carries it.

The `Dockerfile` goes in `apps/backend` with the monorepo root as its build context, in three stages on `node:22-bookworm-slim`. The `deps` stage enables `corepack` for the pinned pnpm, copies `package.json`, `pnpm-lock.yaml`, `pnpm-workspace.yaml`, `turbo.json` and `apps/backend/package.json`, and runs `pnpm install --frozen-lockfile --filter @dtc/backend...` so the storefront's Next.js dependencies never enter the image. The `build` stage copies the backend source and runs `pnpm --filter @dtc/backend build`, producing `.medusa/server`. The `runtime` stage copies only `.medusa/server`, runs `npm install --omit=dev` there as the guide prescribes, sets `PORT=9000`, `NODE_ENV=production` and a non-root user, exposes `9000`, and starts with a small `docker-entrypoint.sh` that runs `npm run predeploy` only when `RUN_MIGRATIONS=true`, so the server instance migrates and the worker instance does not. A `.dockerignore` at the root excludes `node_modules`, `.medusa`, `.turbo`, `.git`, `**/.env` and `apps/storefront`. A `docker-compose.yml` for local use adds `postgres:15` and `redis:7`, both versions the README names as minimums or defaults, a `backend` service in server mode with `RUN_MIGRATIONS=true`, and a `worker` service sharing the image.

The sandbox has no Docker, so the agent installs it first with `sudo apt-get install -y docker.io` and starts `dockerd`, then runs `docker build -f apps/backend/Dockerfile -t backend .` and reads the layer sizes. Compose v2 is not in that package, so it starts PostgreSQL and Redis with `docker run` and the backend with the image, `DATABASE_URL` and `REDIS_URL` pointing at them and `MEDUSA_WORKER_MODE=server`, waits for the migration log lines, and checks `curl localhost:9000/health` answers `OK` as the guide says a healthy server does and that `/app` serves the admin. It starts a second container in worker mode with the admin disabled and reads its log to confirm it registers jobs and serves no HTTP admin. It runs `pnpm --filter @dtc/backend test:unit` once outside Docker to show the suite still passes with the config change, and includes every command and the final `docker images` line in the pull request.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add a Dockerfile for the Medusa backend in this pnpm monorepo. Read package.json, pnpm-workspace.yaml, pnpm-lock.yaml headers, turbo.json, apps/backend/package.json, apps/backend/medusa-config.ts, apps/backend/.env.template, apps/backend/.gitignore, apps/backend/jest.config.js, the root and backend README files and .github/workflows first. Follow Medusa's deployment guide: build with medusa build, run npm install, predeploy and start inside .medusa/server, and support MEDUSA_WORKER_MODE server and worker with DISABLE_MEDUSA_ADMIN and MEDUSA_BACKEND_URL read in medusa-config.ts alongside REDIS_URL. Write a three-stage Dockerfile on node 22 that installs only the backend's dependencies with pnpm filters, a .dockerignore, an entrypoint that runs migrations only when RUN_MIGRATIONS is true, and a docker-compose.yml with postgres 15, redis 7, a server and a worker. Install Docker in the sandbox, build the image, run PostgreSQL, Redis, a server and a worker container, check /health and /app, run the unit tests, and open a pull request with the output.",
  "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

The pull request adds `apps/backend/Dockerfile`, `apps/backend/docker-entrypoint.sh`, `.dockerignore` and `docker-compose.yml`, and changes `apps/backend/medusa-config.ts` and `apps/backend/package.json`. Its description pastes the `docker build` stage summary, the `docker images` line for the final image, the migration lines from the server container's log, the `curl localhost:9000/health` answer, the worker container's startup log and the `jest` unit test summary.

The run's record keeps the Docker install, every `docker run` and the HTTP checks, so a reviewer can see the server and the worker come up from the same image with different variables. The repository's only workflow does not build images; the pull request proposes a `docker/build-push-action` workflow as a separate change.

Before merging, a reviewer chooses the registry and tag scheme, confirms the production `DATABASE_URL` and `REDIS_URL`, replaces the `supersecret` defaults in `.env.template` with generated `JWT_SECRET` and `COOKIE_SECRET` values, and decides whether migrations run from the server container or from a one-off job. The storefront and the backend source are untouched.

## Run it on every Medusa backend without a container image

An agency that hosts several Medusa stores starts one run per repository from its own server: a `POST /o/{org}/sessions` each, with the repository in `resources` and a `request_id` that is a UUID v5 of the repository's full name, so a retried call returns the run already started. Each run reads its own layout, so a single-package backend on Yarn gets a two-stage Dockerfile with `yarn install --immutable`, and a repository that already has a Dockerfile gets a report of what differs from the deployment guide and no pull request.

To keep the image current, an automation in the Project with a `github` trigger on `pull_request.opened` and the prompt "if this pull request changes apps/backend/package.json or medusa-config.ts, rebuild the Docker image, start it against PostgreSQL and Redis, check /health, and leave a comment with the result" checks each change. The trigger adds the pull request after the prompt and fires only for work by owners, members and collaborators; that run installs Docker in its own sandbox the same way.

## Why run it on Rush?

A Medusa image is easy to get almost right: copy the whole monorepo and the storefront's dependencies double the image, skip `.medusa/server` and `medusa start` runs the source tree instead of the build, run migrations from every replica and two containers race on the same schema. The agent reads the deployment guide and the real workspace, builds the image in its sandbox, and starts a server and a worker from it against a real database before the pull request exists.

Every command stays with the run, from `apt-get install docker.io` to the `/health` check, and the pull request quotes them. Several stores get the same image shape at once, each built and started on its own machine with its own pull request.

## Frequently asked questions

### Why install only the backend's dependencies?

Because `pnpm-workspace.yaml` includes `apps/**`, so a plain `pnpm install` pulls the Next.js storefront's dependencies into the image. The `--filter @dtc/backend...` selector installs the backend and anything it depends on inside the workspace, and the final stage copies only `.medusa/server`, so neither the storefront nor the build tools ship.

### Where do migrations run?

In the entrypoint, only when `RUN_MIGRATIONS=true`, which the compose file sets on the server service and not on the worker. That follows the guide, which puts `predeploy` on the server instance alone. A team that prefers a one-off job can drop the variable and run `npm run predeploy` from a job container with the same image.

### Does the sandbox really build and run the image?

Yes. The sandbox has no Docker preinstalled, so the agent installs `docker.io`, starts `dockerd` and then builds and runs the image, with PostgreSQL and Redis as sibling containers started with `docker run`. Compose v2 is not in that package, so the compose file is checked by starting the same services by hand and is there for the reader's laptop.

### Why does the worker container disable the admin?

Because the guide says the admin dashboard is served by the server instance and the worker runs jobs and subscribers only. `DISABLE_MEDUSA_ADMIN=true` on the worker, read through the new `admin.disable` line in `medusa-config.ts`, keeps it from serving `/app` a second time.

## More Medusa jobs

- [Add GitHub Actions CI to a Medusa Monorepo](https://getrush.ai/run/add-github-actions-ci/medusa/)
- [Add OpenTelemetry Tracing to a Medusa Backend](https://getrush.ai/run/add-opentelemetry/medusa/)
- [Send an Order Confirmation Email from a Medusa Backend](https://getrush.ai/run/add-order-confirmation-email/medusa/)

## The same job on other stacks

- [Write a Dockerfile for a Reflex App](https://getrush.ai/run/add-dockerfile/reflex/)
- [Add a Dockerfile to a Rocket App](https://getrush.ai/run/add-dockerfile/rocket/)
- [Add a Dockerfile to a Sequelize App](https://getrush.ai/run/add-dockerfile/sequelize/)

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