# Write a Dockerfile for a Reflex App

Yes. An agent writes a two-stage Dockerfile for your Reflex app that exports the frontend at build time, serves both halves on one port, probes it and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-dockerfile/reflex/). 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 configured and run before it writes an image for it. In a repository laid out like reflex-dev/reflex-examples, each of the 26 apps is a directory with its own `rxconfig.py`, `requirements.txt` and `assets/` folder, and none of them has a `Dockerfile`, a `.dockerignore` or a compose file. The `basic_crud` app declares `rx.Config(app_name="basic_crud", db_url="sqlite:///reflex.db", plugins=[rx.plugins.RadixThemesPlugin()])`, depends on `reflex[db]>=0.9.2` and `fastapi`, defines a `Product` SQLModel table in `basic_crud/model.py` and a product router in `basic_crud/api.py` that opens `rx.session()` per request, and its `README.md` says to run `reflex db init` and `reflex db migrate` before `reflex init` and `reflex run`. The root `.gitignore` drops `.web`, `*.db`, `.states`, `frontend.zip`, `backend.zip` and `assets/external/`, and `.github/workflows/check_export.yml` is the only build the repository has: for every app it creates a venv, installs the requirements with `uv pip`, sets `REFLEX_TELEMETRY_ENABLED` to false, runs `reflex init` then `reflex export`, and fails if either zip is unreadable or the log mentions a `DeprecationWarning`.

Reflex's own deployment guide is the second thing the agent reads, because a Reflex app is two processes. `reflex run --env prod` serves the frontend and backend together on port 3000; split, the backend takes `--backend-only --backend-port 8000` and the frontend needs `REFLEX_API_URL` to find it. The project's `docker-example/production` image avoids running a Node frontend at all: a `python:3.13-slim` builder copies `uv` and `bun` in, installs `requirements.txt` into a venv, and runs `reflex export --frontend-only --no-zip` with `REFLEX_API_URL` set, which leaves the static frontend in `.web/build/client/`. The final stage copies that directory to `/srv`, the venv and `.web/backend` into `/app`, installs `redis-server` and the `caddy` binary from `caddy:2`, adds a non-root `reflex` user whose home is `/app` so the backend can create `.states` there, and a `Caddyfile` on `:{$PORT}` proxies `/_event/*`, `/ping`, `/_health` and `/_upload` to `localhost:8000` and serves everything else from `/srv` with the pre-compressed `.gz` copies the export wrote. Its `CMD` runs `reflex db migrate` when an `alembic` directory exists, starts Caddy and Redis, then `exec reflex run --env prod --backend-only`.

The agent follows that layout for `basic_crud` and writes the four files the image needs: `Dockerfile`, `Caddyfile`, `.dockerignore` that excludes `.web`, `venv`, `*.db`, `.states`, `__pycache__` and the two export zips, and a committed `alembic/` directory, because the repository has none and the container's `reflex db migrate` would otherwise have nothing to apply to the SQLite file. It runs `reflex db init` and `reflex db makemigrations` in the sandbox to create that directory, pins the `uv` and `bun` images by major version as the example does, keeps `PORT` as a build argument with 8080 as its default, and sets `REFLEX_TELEMETRY_ENABLED=false` in the image as the export workflow already does. Because the app keeps its data in `reflex.db` beside the code, the Dockerfile declares `/app/data` as the place for it, the `db_url` moves to `sqlite:////app/data/reflex.db` through an environment variable with the old path as default, and the pull request says to mount a volume there or the products vanish with the container.

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 -t basic-crud .` and `docker run -p 8080:8080` with a mounted data directory. It checks `GET /ping` on the backend route, loads the frontend at `/`, sends the `POST /products` and `GET /products/1` requests from `basic_crud/test.http` through the proxied port, confirms the row survives a container restart with the volume and disappears without it, and reads `docker image ls` for the final size. The `check_export.yml` matrix is left alone: it lists every top-level directory, and a `Dockerfile` in `basic_crud/` is not a directory, so the job still passes.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Write a Dockerfile for the basic_crud Reflex app in this repository. Read basic_crud/rxconfig.py, basic_crud/requirements.txt, basic_crud/README.md, basic_crud/basic_crud/model.py, basic_crud/basic_crud/api.py, basic_crud/basic_crud/test.http, the root .gitignore and .github/workflows/check_export.yml first, then Reflex's production docker example. Write basic_crud/Dockerfile as a two-stage build: a python slim builder that installs the requirements into a venv with uv and runs reflex export --frontend-only --no-zip with REFLEX_API_URL set from a PORT build argument, and a final stage with Caddy and Redis that serves the exported frontend from /srv, proxies /_event, /ping, /_health and /_upload to the backend on 8000, runs as a non-root user and starts with reflex db migrate followed by reflex run --env prod --backend-only. Add a Caddyfile, a .dockerignore, run reflex db init and reflex db makemigrations and commit the alembic directory so the migration step has something to apply, and move the SQLite file to a /app/data directory configurable through an environment variable. Install Docker in your sandbox, build the image, run it with a volume on /app/data, check /ping and the product routes from test.http, confirm the data survives a restart, and open a pull request with the build output, the responses and the image size. Do not change check_export.yml or any other app.",
  "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 `basic_crud/Dockerfile`, `basic_crud/Caddyfile`, `basic_crud/.dockerignore` and the generated `basic_crud/alembic/` directory with its first revision, and changes one line of `basic_crud/rxconfig.py` so `db_url` reads an environment variable with the old relative path as its default. Its description pastes the `docker build` output, the `/ping` response, the product created through the proxied port and read back after a restart, the user the backend runs as, and the image size as `docker image ls` printed it.

Nothing else in the repository changes: the other 25 apps, `check_export.yml` and the app's own Python modules are untouched, and the `README.md` of `basic_crud` gains a short section with the build and run commands and the volume the data needs.

Before merging, a reviewer decides whether the SQLite volume is what they want or whether `db_url` should point at Postgres, whether the local Redis in the image should become an external one through `REFLEX_REDIS_URL`, and whether the pinned `uv` and `bun` majors are the ones their other images use.

## Run it on every Reflex app without an image

A team with several Reflex apps to containerise sends this body 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 reads its own `rxconfig.py`: an app with no `db_url` gets no migration step or data volume, one on Postgres gets the URL passed through unchanged, and one that already commits `reflex.lock/` gets that directory copied into the builder as the Reflex docker guide asks.

For a repository of many apps like this one, the same prompt with the app name changed starts one run per app, and each run installs its own Docker in its own sandbox, so the builds do not share a daemon or a port.

## Why run it on Rush?

A Reflex image written from memory tends to run `reflex run` in dev mode, ship Node and `node_modules` in the final layer, bind the frontend to one port and the backend to another with nothing routing between them, and forget that the SQLite file lives in the working directory. The agent starts from the project's own export workflow and Reflex's production example, so the frontend is static, the backend is the only Python process, and the data path is explicit.

The build, the probes and the restart test run in the agent's own sandbox with Docker installed there, and their output is in the pull request. A reviewer reads a build log and three HTTP responses rather than a Dockerfile that looks plausible, and the same run can be started for every app in the repository at once.

## Frequently asked questions

### Why export the frontend at build time instead of running `reflex run --env prod` for both?

`reflex run --env prod` serves both halves on one port, but the final image then needs Node or Bun to serve the frontend. Exporting with `--frontend-only --no-zip` during the build leaves plain HTML, JavaScript and CSS in `.web/build/client/`, which Caddy serves from `/srv`, and the final stage carries only the Python venv. That is the layout Reflex's own production example uses.

### Why does the pull request add an `alembic` directory?

The example `CMD` runs `reflex db migrate` only when an `alembic` directory exists, and this repository has none; `basic_crud/README.md` tells a developer to run `reflex db init` by hand first. The agent runs `reflex db init` and `reflex db makemigrations` once in the sandbox and commits the result, so a fresh container creates the `product` table before the backend starts.

### What happens to the products when the container is replaced?

They are in a SQLite file, so they go with the container unless the file is on a volume. The Dockerfile moves it to `/app/data` and the pull request shows one run where a product survives a restart with a volume mounted and one where it does not. Pointing `db_url` at Postgres through the new environment variable is the alternative the description names.

### Does this change the export workflow?

No. `check_export.yml` builds its matrix from the top-level directories and runs `reflex export` in each, and the new files inside `basic_crud/` do not change that list. The agent runs that export step itself in the sandbox to confirm the app still exports without a deprecation warning.

### Why Caddy and Redis inside the image?

Caddy is the one process that serves the static frontend and proxies the websocket, upload and health routes to the backend, so one port is enough for a platform that exposes one. Redis holds the backend's state, and Reflex's example runs a local one so the container works alone; `REFLEX_REDIS_URL` is set in the image, so pointing it at a shared Redis is one environment variable.

## More Reflex jobs

- [Add File Uploads to a Reflex Chat App](https://getrush.ai/run/add-file-uploads/reflex/)
- [Add Pre-commit Hooks to a Reflex App](https://getrush.ai/run/add-pre-commit-hooks/reflex/)
- [Add a SQLite Database to a Reflex App](https://getrush.ai/run/add-sqlite-database/reflex/)

## The same job on other stacks

- [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/)
- [Write a Dockerfile for a Bolt for JavaScript Slack App](https://getrush.ai/run/add-dockerfile/slack-bolt/)

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