Deploying Rust Projects

Zeabur supports most types of Rust applications - by default, it finds and runs the executable file automatically; however, you can also specify which executable file to run in the "Service Name" field.

If you don't currently have a Rust project and want to try it, feel free to fork zeabur/axum-template (opens in a new tab) to your GitHub account and deploy it on Zeabur.

Supported project types

  • Single-executable projects: Rust project with just one src/ entry point. Zeabur finds the only executable artifact in the target/release directory. Also, it is acceptable to fill in the "Service Name" field with the artifact filename to execute to ensure Zeabur runs what you want.
  • Multi-executable projects: Rust project with two or more entry points, including src/ and other files in src/bin. You may need to fill in the "Service Name" field with the artifact filename to execute.
  • Cargo Workspace mono-repo: Rust project with multiple crates. You may need to fill in the "Service Name" field with the artifact filename to execute.

When the executable filename you wrote did not hit, Zeabur will try to find the executable file automatically. Zeabur scans all the files in target/release and runs the first executable file it found. Since this pattern is easy to guess wrong in complex scenarios (such as Multi-executable projects and Cargo Workspace mono-repo), it is recommended that you fill in the correct "Service Name". Refer to "Find artifact filename" for more information.

Find artifact filename

The artifact can be found in the directory target/release of your project. To do this:

  1. You need the Rust toolchain to compile the project. Download it on (opens in a new tab).

  2. Clone the project you want to deploy and change to the project directory.

  3. Run cargo build --release to compile the project.

    $ cargo run --release
    Compiling zeabur v0.1.0 (/project)
      Finished release [optimized] target(s) in 0.65s
      Running `target/release/zeabur`
  4. Find the line starting with "Running", and we pick the base (trailing) name of the following path (target/release/zeabur). For this case, it is zeabur.

  5. Fill zeabur to the "Service Name" field.

Copy other files

If your application depends on other files or directories in the source code repository in addition to the executable file. For example:

|`-- public <-- Your application depends on this folder
|``-- src
|``-- Cargo.toml
|``-- Cargo.lock
`-- config.toml <-- Your application depends on this file

Zeabur allows you preserving them with the file .zeabur-preserve. Fill the file and directories you want to preserve to this file. The directories can optionally end with /. An example is as follows:


Technical details and considerations

  • The Rust image is based on Multi-Stage Build, and the runtime uses as the base image. Some dynamic libraries may not work properly in the runtime due to the lack of some specific packages. For this case, please open a ticket about adding support for this package.
    • We currently install openssl in the runtime environment.
  • No root at runtime. Bring your Dockerfile if you need it.
  • We use lld to speed up compilation. If your project does not support lld, we recommend that you specify config.toml in your project to call the standard ld. If you want to use a non-built-in linker such as mold, you need to write your own Dockerfile.
  • We use cargo-chef to maximize the cache of build layers. If you encounter any incompatible problems, please report them to Zeabur or upstream LukeMathWalker/cargo-chef (opens in a new tab).

Serverless Deployment

Unlike other PaaS platforms that typically package your Rust application in Docker containers for execution, Zeabur also supports deploying Rust serverlessly. This allows your Rust application to only start when it receives a request, rather than continuously running like a container, wasting resources.

If you want to deploy your Rust application serverlessly, please add ZBPACK_SERVERLESS=1 to your environment variables.