All jobs

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 RushOpens 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 with this body:

{
  "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.

The use case this job follows, with its automation and trigger: Hand off a long task.

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

The same job on other stacks

Keep reading