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