# Add a Dockerfile to an AdonisJS App

Yes. An agent writes a multi-stage Dockerfile for your AdonisJS app that builds with node ace build, migrates on start, runs the image, and opens a PR.

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

## What the agent does

The agent reads how the app is built and started before writing an image for it, because an AdonisJS app is not run from its TypeScript sources in production. In an app started from the `api` kit in adonisjs/starter-kits, `package.json` has `build` as `node ace build`, `start` as `node bin/server.js`, `dev` as `node ace serve --hmr` and `test` as `node ace test`, with `@adonisjs/core` ^7.5.2, `@adonisjs/lucid` ^22.4.2 and `better-sqlite3`, a native module, among the dependencies, and `typescript`, `@adonisjs/assembler` and `hot-hook` among the dev ones. `tsconfig.json` sets `outDir` to `./build`. `config/database.ts` uses the `sqlite` connection with the file at `app.tmpPath('db.sqlite3')`, and `.gitignore` keeps `tmp/*` and `build` out of Git. `start/env.ts` requires `NODE_ENV`, `PORT`, `HOST`, `LOG_LEVEL`, `APP_KEY`, `APP_URL` and `SESSION_DRIVER`, and `.env.example` sets `HOST=localhost` and `PORT=3333`. `bin/server.ts` listens for `SIGTERM` and calls `app.terminate()`. `start/routes.ts` answers `GET /` with `{ hello: 'world' }` and mounts signup, login, profile and logout under `/api/v1`. No lockfile is committed, and there is no Dockerfile or `.dockerignore`.

The Dockerfile follows the shape the AdonisJS deployment guide gives, in three stages from `node:lts-bookworm-slim`, with the kit's specifics filled in. A `deps` stage copies `package.json` and the lockfile and runs `npm ci`; because the kit commits no lockfile and `npm ci` refuses to run without one, the agent runs `npm install` once in the sandbox and commits the `package-lock.json` it produces, saying so in the pull request. A `build` stage copies the source and runs `node ace build`, which compiles to `build/`, writes `ace.js` there and copies `package.json` and the lockfile into it. The `production` stage copies `build/` alone, runs `npm ci --omit=dev` inside it so dev dependencies and TypeScript never reach the image, sets `NODE_ENV=production`, `HOST=0.0.0.0`, `PORT=3333` and `TZ=UTC` because the `.env.example` value of `localhost` would bind a port nothing outside the container can reach, declares `EXPOSE 3333`, switches to the `node` user the image ships, and ends with `CMD ["node", "bin/server.js"]`. `APP_KEY` and `APP_URL` are never written into the image; the README section the agent adds shows passing them with `--env-file` or `-e`, and a key made with `node ace generate:key`.

Two things in the kit need decisions the guide leaves open. Migrations are off in production unless forced, so the agent adds the guide's `docker-entrypoint.js` at the project root, copied into the image, which runs `node ace migration:run --force` when `MIGRATE=true` and then imports `bin/server.js`, with a single `CMD` pointing at it. The SQLite file lives under `tmp/` inside the build directory, so it would vanish with the container; the agent declares a `VOLUME` for `/app/tmp`, documents mounting it, and notes that switching to the commented-out `pg` connection in `config/database.ts` is the move for anything beyond a single instance. A `HEALTHCHECK` runs a short Node script that fetches `http://127.0.0.1:3333/` and exits by the status, since the root route answers JSON with no database access. `.dockerignore` lists `node_modules`, `build`, `tmp`, `.env` and every `.env.*`, and `.git`.

The sandbox has no Docker, so the agent installs `docker.io`, starts `dockerd`, builds the image, and runs it with `MIGRATE=true`, a generated `APP_KEY`, `SESSION_DRIVER=cookie` and a mounted `tmp` directory. It requests `GET /` and posts a signup to `/api/v1/auth/signup` to show the migrated SQLite database accepting a row, sends `docker stop` and shows the server terminating on `SIGTERM` rather than being killed, and pastes `docker image ls` for the final stage. It adds `.github/workflows/docker.yml` that builds the image with `docker/build-push-action` on pull requests without pushing, so a broken Dockerfile fails before merge, validates it with `actionlint`, and opens the pull request.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Write a Dockerfile for this AdonisJS app. Read package.json, tsconfig.json, adonisrc.ts, bin/server.ts, start/env.ts, start/routes.ts, config/database.ts, .env.example, .gitignore and README.md first. Use three stages from node:lts-bookworm-slim as the AdonisJS deployment guide does: deps runs npm ci, build runs node ace build, production copies build alone and runs npm ci --omit=dev. No lockfile is committed and npm ci needs one, so run npm install once and commit package-lock.json, and say so in the pull request. In the production stage set NODE_ENV production, HOST 0.0.0.0, PORT 3333 and TZ UTC, expose 3333, run as the node user, add a HEALTHCHECK that fetches GET / with node, and never put APP_KEY in the image. Add docker-entrypoint.js at the project root that runs node ace migration:run --force when MIGRATE is true and then imports bin/server.js, and make it the single CMD. Declare a VOLUME for /app/tmp because the SQLite file lives there, and document it. Add a .dockerignore for node_modules, build, tmp, .env files and .git. Docker is not installed here: install docker.io, start dockerd, build the image, run it with MIGRATE=true, an APP_KEY from node ace generate:key, SESSION_DRIVER cookie and a mounted tmp directory, request GET / and post a signup to /api/v1/auth/signup, then docker stop it and show the server ending on SIGTERM. Add a GitHub Actions workflow that builds the image on pull requests without pushing and validate it with actionlint. Add a README section on building and running, and open a pull request that pastes the build output, the two requests and the image size line.",
  "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 adds `Dockerfile`, `.dockerignore`, `docker-entrypoint.js`, `package-lock.json` and `.github/workflows/docker.yml`, and adds a section to `README.md`. The description pastes the `docker build` output with the three stages, the `GET /` response, the signup response from the migrated database, the server's shutdown lines after `docker stop`, and the `docker image ls` line for the final image.

The run's record holds the Docker install, the build, the container run with the mounted volume, both requests and the stop. The application code and its configuration files are unchanged; the only source change is the committed lockfile, which the pull request explains.

Before merging, a reviewer decides whether to pin the base image to a specific Node release rather than `lts`, whether migrations should run from the entrypoint or from a separate step in the deployment platform as the guide prefers, and whether to move from SQLite to the Postgres connection before this image serves more than one instance.

## Run it on every new AdonisJS service

A team with several AdonisJS services starts one run per repository from its own server: one `POST /o/{org}/sessions` each, with that 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 rather than a second pull request. Each run reads that service's own `config/database.ts`, `adonisrc.ts` and `metaFiles`, so a service with Edge views or Vite assets gets them copied into the build stage and a service on Postgres gets no volume.

Afterwards, an automation on the Project with a `github` trigger on `pull_request.opened` and `pull_request.synchronize` and the prompt "if this pull request changes package.json, adonisrc.ts, start/env.ts or the Dockerfile, build the image and run it with placeholder variables, and comment with whether GET / answers" catches a new required environment variable or a new native module before the image reaches a registry. The trigger adds the pull request after the prompt; only work by an owner, member or collaborator fires it, never a fork's.

## Why run it on Rush?

A Dockerfile for an AdonisJS app has to get four things right that only a real build and run reveal: the build directory is the application root, dev dependencies must be dropped after the build, the host must not be `localhost`, and migrations and the SQLite file need a home. The agent installs Docker in its own sandbox, builds the image, runs it, migrates, writes a row and stops it cleanly, so each of those is shown rather than described.

The sandbox keeps the build log, the container output and the requests with the run, and the pull request cites them. For a team with many AdonisJS services, each gets its own run and its own pull request with an image built from that service's own configuration.

## Frequently asked questions

### Why commit a lockfile?

Because the `deps` stage uses `npm ci`, which refuses to run without `package-lock.json`, and reproducible builds are the point of the image. The kit ships none, so the agent generates one with `npm install` in the sandbox and commits it, and the pull request says so. A team on pnpm or Yarn can swap the stage and the lockfile; the Dockerfile comments show where.

### Why is HOST set to 0.0.0.0 in the image?

`.env.example` sets `HOST=localhost`, which binds the loopback address inside the container, so nothing outside it can connect and the published port answers nothing. The image sets `HOST=0.0.0.0` and `PORT=3333` as defaults that `--env-file` can still override.

### Where does the SQLite database live?

At `tmp/db.sqlite3` under the application root, which inside the image is `/app/tmp`. The Dockerfile declares it a `VOLUME` and the README shows mounting a host directory there, so the data survives a container replacement. For more than one instance the pull request points at the Postgres connection already sketched in `config/database.ts`.

### Does the app stop cleanly on docker stop?

Yes. `bin/server.ts` listens for `SIGTERM` and calls `app.terminate()`, and the image runs `node` directly as PID 1 through the entrypoint script, so the signal reaches it. The agent shows the shutdown lines after `docker stop` in the pull request.

## More AdonisJS jobs

- [Add Email Verification to an AdonisJS App](https://getrush.ai/run/add-email-verification/adonisjs/)
- [Add File Uploads to an AdonisJS App](https://getrush.ai/run/add-file-uploads/adonisjs/)
- [Set Up GitHub Actions CI for an AdonisJS App](https://getrush.ai/run/add-github-actions-ci/adonisjs/)

## The same job on other stacks

- [Add a Dockerfile to an aiohttp App](https://getrush.ai/run/add-dockerfile/aiohttp/)
- [Add a Dockerfile to a Blazor Web App](https://getrush.ai/run/add-dockerfile/blazor/)
- [Write a Dockerfile for a CodeIgniter 4 App](https://getrush.ai/run/add-dockerfile/codeigniter/)

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