> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shuttle.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Builds

> Details about the environment your app is built in

Shuttle builds run on AWS CodeBuild, where we compile your Rust app and place it in a Shuttle `runtime` Debian-based Docker image.

## Build architecture

Shuttle builds and runs images for the Arm64 (aarch64) architecture by default. Pro+ users can reach out to Shuttle Support if they require the x86\_64 architecture.

## Builder image

The Rust builder image is based on [cargo-chef](https://github.com/LukeMathWalker/cargo-chef) to utilize Docker-layer caching of the build dependencies.

### Rust toolchain

The Rust version in the image is regularly updated to the latest `stable-aarch64-unknown-linux-gnu` toolchain (or `stable-x86_64-unknown-linux-gnu` depending on your project's build architecture).

By default, the `wasm32-unknown-unknown` target is installed, which enables compiling WASM frontends.

### External tools

Apart from what is already found in the Debian-based cargo-chef image [\[1\]](https://github.com/debuerreotype/docker-debian-artifacts/blob/bfa3d175e4153a23ffb4cf1b573d72408333b4e2/bookworm/rootfs.manifest) [\[2\]](https://github.com/docker-library/buildpack-deps/blob/fdfe65ea0743aa735b4a5f27cac8e281e43508f5/debian/bookworm/Dockerfile), these `apt` packages are also installed:

* `clang`
* `cmake`
* `llvm-dev`
* `libclang-dev`
* `mold`
* `protobuf-compiler`

Additionally, these tools are installed:

* `cargo-binstall` (latest)
* `trunk` (0.19.2)

> [!TIP]
>
> Some other build tool you think we should add? Let us know!

## Customize build process

### Feature flags

Use [the "shuttle" feature flag](https://docs.shuttle.dev/docs/project-configuration.md#cargo-feature-flags) for custom behavior when building on Shuttle.

### Environment variables

The `SHUTTLE=true` env var is set in the builder image.

If you have build flags or env variables that need to be set during compilation, you can add them in `.cargo/config.toml` ([docs](https://doc.rust-lang.org/cargo/reference/config.html)) and include it in your deployment. Below are some examples.

```toml .cargo/config.toml theme={null}
[build]
rustflags = ["--foo", "bar"]

[env]
MY_ENV_VAR = "Shuttle to the moon! 🚀🚀🚀"
```

## Runtime image

The runtime image that your built executable is placed in is a `bookworm-slim` (Debian 12) with `ca-certificates` and `curl` installed.

## (EXPERIMENTAL) Hook scripts

> [!WARNING]
>
> This feature is experimental and can change

There are three optional bash scripts that can be used to run custom commands during the build.
Create them at the root of your project.

* `shuttle_prebuild.sh`: Runs before `cargo build`. Can be used to install custom build dependencies.
* `shuttle_postbuild.sh`: Runs after `cargo build`.
* `shuttle_setup_container.sh`: Runs in the runtime image before build artifacts are copied into it. Can be used to install custom runtime dependencies.

### Example: Install a custom Rust toolchain

In this example, we install and switch to the `nightly` toolchain.

```sh shuttle_prebuild.sh theme={null}
rustup install nightly --profile minimal
rustup default nightly
```

### Example: Install a build dependency

```sh shuttle_prebuild.sh theme={null}
apt update
apt install -y libopus-dev
```

### Example: Build a WASM frontend

```sh shuttle_postbuild.sh theme={null}
cd frontend
trunk build --release
```

Note: To use the built static assets at runtime, use [build.assets](https://docs.shuttle.dev/docs/files.md#build-assets).

### Example: Install a runtime dependency

```sh shuttle_setup_container.sh theme={null}
apt update
apt install -y ffmpeg
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.