# Write a Dockerfile for a Litestar App

Yes. An agent writes a two-stage Dockerfile for your Litestar app that installs from pdm.lock and runs as a non-root user, builds and probes it, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-dockerfile/litestar/). 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 project is installed and started before it writes an image for it. In an app like litestar-org/litestar-hello-world, `app.py` defines `/sync` and `/async` handlers and builds `app = Litestar(route_handlers=[...])`. `pyproject.toml` depends on `litestar[standard]>=2.4.1`, requires Python `>=3.8,<4.0`, builds with `hatchling`, declares an `app` console script pointing at `litestar.__main__:run_cli`, and keeps `ruff`, `mypy`, `pytest` and `pytest-cov` in PDM dev groups named `lint` and `test`. `pdm.lock` pins `litestar` 2.4.1 and `uvicorn` 0.24.0.post1 with its `standard` extra. `.pre-commit-config.yaml` sets `default_language_version` to Python 3.12 and runs `pdm-lock-check`, so the lock is kept in step with the manifest. `Makefile` creates an in-project `.venv` through `pdm config venv.in_project true` and `pdm install -G:all`; `README.md` starts the app with `litestar run --reload` or `pdm run uvicorn app:app --reload`; `.github/workflows/ci.yaml` tests Python 3.8 through 3.11 with `pdm-project/setup-pdm`. There is no `Dockerfile`, no `.dockerignore` and no container job, and `.gitignore` already excludes `.venv/`.

The Dockerfile has two stages so the image carries the virtual environment and not PDM. The builder starts from `python:3.11-slim`, the newest interpreter the CI matrix tests, installs `pdm` with pip, copies `pyproject.toml` and `pdm.lock` alone, and runs `pdm install --prod --no-self --frozen-lockfile` with `venv.in_project` on, so the resolved production dependencies land in `/app/.venv` from the lock file and nothing else: `--prod` leaves out the `lint` and `test` groups, `--no-self` skips installing the project itself, which has no package to build, and `--frozen-lockfile` refuses to re-resolve. The runtime stage starts from the same base, creates an unprivileged user, copies `/app/.venv` and `app.py`, puts `/app/.venv/bin` first on `PATH`, sets `PYTHONDONTWRITEBYTECODE` and `PYTHONUNBUFFERED`, exposes port 8000 and ends with `CMD ["litestar", "--app", "app:app", "run", "--host", "0.0.0.0", "--port", "8000"]`. The CLI would also find `app.py` on its own, since `app` is one of the module names it searches for a `Litestar` instance, but the explicit `--app` makes the entry point readable in the file. A `.dockerignore` keeps `.git`, `.venv`, `tests`, `.github`, `__pycache__` and the cache directories `.gitignore` lists out of the build context.

The sandbox has no Docker, so the agent installs it (`sudo apt-get install -y docker.io`, then starts `dockerd`), builds the image, runs it with port 8000 published, and requests `/sync` and `/async`, expecting `{"hello": "world"}` from both as `tests/test_app.py` does through `TestClient`. It checks that the process inside the container runs as the unprivileged user, reads the image size from `docker image ls` for the pull request, and runs `hadolint` over the Dockerfile. The app has no dedicated health route, so the `HEALTHCHECK` it adds requests `/sync` with Python's `urllib` rather than `curl`, which the slim image does not have, and the pull request says that a real service wants a health route of its own.

To keep the image building after the merge, the agent adds a `docker` job to `.github/workflows/ci.yaml` that runs `docker build .` on `ubuntu-latest`, which has Docker, and starts the container to curl `/sync` once, beside the existing `validate` and `test` jobs. It also adds a short section to `README.md` with the build and run commands and a `make docker-build` target in the project's `Makefile` style. It runs `pdm install` and `pdm run pytest` once in the sandbox to show the test suite is untouched, and `pre-commit run --all-files` so `pdm-lock-check` and `ruff` pass on the changed tree.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Write a Dockerfile for this Litestar application. Read pyproject.toml, pdm.lock, app.py, Makefile, README.md, .gitignore, .pre-commit-config.yaml, tests/test_app.py and the workflows under .github/workflows first. Write a two-stage Dockerfile: a builder on a python slim image within the version range the CI matrix tests that installs pdm and runs pdm install --prod --no-self --frozen-lockfile from pyproject.toml and pdm.lock into an in-project .venv, and a runtime stage on the same base that copies the .venv and the application code, runs as a non-root user, exposes port 8000 and starts the app with the litestar CLI bound to 0.0.0.0. Add a .dockerignore and a HEALTHCHECK that uses Python rather than curl. Install Docker in the sandbox, build the image, run it, request /sync and /async and confirm both answer, check the running user and the image size, and run hadolint. Add a docker job to the CI workflow that builds the image and probes it, document the build and run commands in the README, run pytest and pre-commit, 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 adds `Dockerfile` and `.dockerignore`, changes `.github/workflows/ci.yaml`, `Makefile` and `README.md`, and touches nothing in `app.py` or `pyproject.toml`. The description shows the `docker build` output, the two JSON responses from the running container, the user the process runs as, the image size as `docker image ls` printed it, and the `hadolint` result.

The run's record holds the Docker install, the build, the container start and the probes, plus the `pytest` and `pre-commit` runs, so a reviewer can see each step's output instead of reproducing it.

Before merging, a reviewer decides whether to pin the base image by digest as well as tag, whether the `litestar run` command should take `--wc` for more than one worker in the deployment, and whether the health check should wait for a dedicated route once one exists. The pull request leaves those as named choices with the line to change for each.

## Run it on every Python service without an image

A team with several Litestar or other ASGI services to containerise runs this once per repository from its own server: one `POST /o/{org}/sessions` per repository, 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 instead of opening a second pull request. Each run installs Docker in its own sandbox and reads that service's own lock file and start command, so a project on Poetry or uv gets the installer it uses.

To keep the image honest 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 pyproject.toml, pdm.lock or the Dockerfile, build the image, run it, request /sync and comment with the result and the image size" reads each new pull request. The trigger puts 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 written without reading the project tends to install from a `requirements.txt` the project does not have, ship the dev dependencies, run as root and start the wrong module. The agent starts from the lock file and the console script the project already defines, so the image installs exactly what `pdm.lock` pins and starts the app the way the README does, bound to an address a container can be reached on.

On Rush the build and the probes run in the run's own sandbox, Docker included, and their output is kept with the run, so the pull request carries the responses and the image size it claims. Several services can be containerised at once, each as its own run and its own pull request.

## Frequently asked questions

### Why install with PDM inside the image rather than exporting requirements.txt?

Because `pdm.lock` is the project's source of truth and `pdm-lock-check` in pre-commit keeps it that way. `pdm install --frozen-lockfile` installs exactly the pinned set with no second resolver. `pdm export` to a requirements file works too and drops PDM from the builder; the pull request names it as the alternative if the team prefers a plain `pip install -r`.

### Why the litestar CLI and not uvicorn directly?

The CLI is what the project's README and its `app` console script already use, it runs uvicorn underneath because `litestar[standard]` is installed, and it adds `--wc` for workers and `--reload` for development without a second command to learn. `uvicorn app:app --host 0.0.0.0 --port 8000` is the equivalent one-liner, and the pull request shows it for anyone who wants the bare server.

### Why Python 3.11 when pre-commit says 3.12?

The pre-commit setting only picks the interpreter that runs the hooks. The CI matrix in `ci.yaml` tests 3.8 through 3.11, so 3.11 is the newest version the test suite is known to pass on; running the image on 3.12 would ship something CI never ran. The pull request notes that adding 3.12 to the matrix is the step that lets the base image move.

### Does the image contain the test and lint tools?

No. `--prod` excludes the `lint` and `test` dev groups, so `pytest`, `ruff`, `mypy` and their dependencies stay out, and `--no-self` skips the project itself, which is a single module with nothing to package. The runtime stage copies only the virtual environment and `app.py`; `.dockerignore` keeps `tests/` and the caches out of the build context.

## More Litestar jobs

- [Add Graceful Shutdown to a Litestar App](https://getrush.ai/run/add-graceful-shutdown/litestar/)
- [Add a Health Check Endpoint to a Litestar App](https://getrush.ai/run/add-health-checks/litestar/)
- [Add JWT Authentication to a Litestar App](https://getrush.ai/run/add-jwt-authentication/litestar/)

## The same job on other stacks

- [Write a Dockerfile for a Maven Spring Boot App](https://getrush.ai/run/add-dockerfile/maven/)
- [Add a Dockerfile to a Medusa Backend](https://getrush.ai/run/add-dockerfile/medusa/)
- [Write a Dockerfile for a Reflex App](https://getrush.ai/run/add-dockerfile/reflex/)

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