# Add a Dockerfile to a Leptos Axum App

Yes. An agent writes a two-stage Dockerfile for your Leptos Axum app: a cargo-leptos build, then the binary and site directory with the LEPTOS_* variables set.

[Run this on Rush](https://cloud.getrush.ai/run/add-dockerfile/leptos/). 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 builds before it writes a container for it. In an app generated from leptos-rs/start-axum, `Cargo.toml` declares a `cdylib` and `rlib` library, `leptos`, `leptos_router` and `leptos_meta` at 0.8, and two features: `hydrate`, which pulls `wasm-bindgen` and `console_error_panic_hook`, and `ssr`, which pulls `axum` 0.8, `tokio` with `rt-multi-thread` and `leptos_axum`. The `[package.metadata.leptos]` table sets `site-root` to `target/site`, `site-pkg-dir` to `pkg`, `style-file` to `style/main.scss`, `assets-dir` to `public`, `site-addr` to `127.0.0.1:3000`, `bin-features` to `ssr` and `lib-features` to `hydrate`, with a `wasm-release` profile for the WebAssembly bundle. `src/main.rs` reads that configuration with `get_configuration(None)`, builds an axum `Router` with `leptos_routes` and `file_and_error_handler`, and binds `tokio::net::TcpListener` to the configured address. `rust-toolchain.toml` pins `nightly`, and `cargo-generate.toml` drops that file when the template is generated without nightly features. `.gitignore` excludes `Cargo.lock`, with a comment telling binary authors to remove the line.

The README decides the build steps: `cargo install cargo-leptos --locked`, `rustup target add wasm32-unknown-unknown`, `cargo leptos build --release`, and a deploy section listing the files a server needs, the binary and the `target/site` directory, together with `LEPTOS_OUTPUT_NAME`, `LEPTOS_SITE_ROOT`, `LEPTOS_SITE_PKG_DIR`, `LEPTOS_SITE_ADDR` and `LEPTOS_RELOAD_PORT`. The agent writes a two-stage `Dockerfile`: a builder from the official Rust image, `nightly` when `rust-toolchain.toml` is present and stable otherwise, that adds the wasm target, installs `cargo-leptos` and runs the release build; and a runtime stage from a slim Debian image that copies the server binary and `target/site` into `/app`, sets `LEPTOS_SITE_ROOT=site`, `LEPTOS_SITE_PKG_DIR=pkg`, `LEPTOS_OUTPUT_NAME` to the crate name and `LEPTOS_SITE_ADDR=0.0.0.0:3000`, because the `127.0.0.1` in `Cargo.toml` is unreachable from outside a container, exposes 3000 and runs the binary as a non-root user. The README names the binary location twice with different paths, `target/release` and `target/server/release`, so the agent checks which one the installed `cargo-leptos` writes and copies from that.

Two files around the Dockerfile matter as much as it does. A `.dockerignore` excludes `target/`, `end2end/node_modules/` and `end2end/test-results/` so the build context is the source. And because `Cargo.lock` is gitignored, a `--locked` build in the container has nothing to lock to; the agent says so in the pull request, removes the `Cargo.lock` line from `.gitignore` as the comment there suggests for an executable, and commits the lockfile the build produced, so the image is reproducible. Dependency caching is a copy of `Cargo.toml` and the lockfile with a stub build before the source copy, in the usual two-step pattern, so a change to `src/app.rs` does not recompile `leptos` and `axum`.

The sandbox has no Docker, so the agent installs it with `sudo apt-get install -y docker.io`, starts `dockerd`, and runs `docker build -t app .` followed by `docker run -p 3000:3000 app`. It then requests `/` and checks for the `<title>` of `Welcome to Leptos` and the `<h1>` text `Welcome to Leptos!` that `end2end/tests/example.spec.ts` asserts, and requests `/pkg/<name>.js` and `/pkg/<name>.css` to confirm the site directory is served from `site-root`. The build output, the image size reported by `docker images`, and the two HTTP responses go into the pull request; the agent does not run the Playwright suite, since `end2end` needs `npm install` and browsers the image does not carry.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add a Dockerfile to this Leptos Axum app. Read Cargo.toml including the package.metadata.leptos table, src/main.rs, src/lib.rs, src/app.rs, rust-toolchain.toml if present, cargo-generate.toml, .gitignore, README.md and end2end/tests/example.spec.ts first. Write a two-stage Dockerfile: a builder on the official Rust image, nightly if rust-toolchain.toml pins it and stable otherwise, that adds the wasm32-unknown-unknown target, installs cargo-leptos, caches dependencies with a manifest-only stub build, and runs cargo leptos build --release; and a slim Debian runtime that copies the server binary from wherever cargo-leptos wrote it and the target/site directory into /app, sets LEPTOS_SITE_ROOT=site, LEPTOS_SITE_PKG_DIR=pkg, LEPTOS_OUTPUT_NAME to the crate name and LEPTOS_SITE_ADDR=0.0.0.0:3000, exposes 3000 and runs as a non-root user. Add a .dockerignore for target/ and end2end/node_modules/. Remove Cargo.lock from .gitignore and commit the lockfile. Install Docker in the sandbox with sudo apt-get install -y docker.io, start dockerd, build the image, run it, request / and check for the Welcome to Leptos title and heading from the Playwright test, and request a /pkg/ asset. Include the build log, the image size and the responses in a pull request that also documents the environment variables.",
  "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` and `Cargo.lock`, and changes `.gitignore` and `README.md` with a Docker section. No Rust source changes.

The description shows the `docker build` tail, the image size from `docker images`, the response headers and the matched title and heading from `/`, and the status for the `/pkg/` asset, plus the path `cargo-leptos` wrote the binary to. The transcript at `GET /o/{org}/sessions/{id}/messages` keeps every command, including the Docker installation.

Before merging, a reviewer decides whether to pin the Rust image to a date rather than a channel, whether the runtime should be a distroless image once the binary's shared-library needs are known, and whether `LEPTOS_SITE_ADDR` should come from the platform's `PORT` variable.

## Run it on every new project from the Leptos starter

A team that generates services with `cargo leptos new` runs this once per new 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 a second pull request.

To keep the image honest after that, 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 Cargo.toml, the leptos metadata or the Dockerfile, build the image, run it, check / and report the image size on this pull request" installs Docker in its sandbox the same way and comments. The trigger puts the pull request after the prompt; only pushes by an owner, member or collaborator fire it.

## Why run it on Rush?

A Leptos image fails for reasons the Dockerfile alone does not show: a binary path that differs between `cargo-leptos` versions, a listener bound to `127.0.0.1` inside the container, a `--locked` build with no lockfile in git, a site directory copied to the wrong place so `/pkg/` returns 404. The agent builds the image, runs it and asks it for the page and an asset on a clean machine of its own, so the pull request arrives with the responses rather than the intention.

Installing Docker, building a Rust release with a WebAssembly target and checking the result is slow on a laptop and leaves images behind; in a sandbox it runs to the end while you do something else, and the log stays with the run.

## Frequently asked questions

### Why two stages?

The builder needs the Rust toolchain, the wasm target and `cargo-leptos`, which are large; the runtime needs only the binary and `target/site`. Copying those two paths into a slim Debian image keeps the shipped image small and leaves no compiler in production.

### Does the template's nightly toolchain carry into the image?

Only when `rust-toolchain.toml` is in the repository, which `cargo-generate.toml` includes only if you chose nightly features. The agent reads that file and picks the matching Rust image, so a stable project builds on stable.

### Why commit Cargo.lock?

The template gitignores it for library use, and its own comment says to remove the line for an executable. Without a lockfile every image build resolves dependencies afresh, so two builds of the same commit can differ; committing it makes `--locked` meaningful.

### Does the agent run the Playwright end-to-end tests against the container?

No. It checks the title and heading those tests look for with plain HTTP requests, since `end2end` needs `npm install` and browsers. Say in the prompt if you want the suite run against the container and the agent installs them in its sandbox and points the test at the mapped port.

## More Leptos jobs

- [Add GitHub Actions CI to a Leptos App](https://getrush.ai/run/add-github-actions-ci/leptos/)
- [Add Graceful Shutdown to a Leptos Axum Server](https://getrush.ai/run/add-graceful-shutdown/leptos/)
- [Add Health Checks to a Leptos App](https://getrush.ai/run/add-health-checks/leptos/)

## The same job on other stacks

- [Write a Dockerfile for a Litestar App](https://getrush.ai/run/add-dockerfile/litestar/)
- [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/)

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