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 with this body:
{
"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"
}
]
}- 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.
- 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.
- 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.
The use case this job follows, with its automation and trigger: Hand off a long task.
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
The same job on other stacks
- Write a Dockerfile for a Reflex App (Reflex)
- Add a Dockerfile to a Rocket App (Rocket)
- Add a Dockerfile to a Sequelize App (Sequelize)