Rust MUSL Builder
Minimal multi-arch builder image for reproducible static Rust binaries
The rust-musl-builder
is a Docker image designed to build static Rust binaries with MUSL libc. This allows you to create fully static executables that run on any Linux system without external dependencies.
Feature | Details |
---|---|
🏋️ Targets | x86_64-unknown-linux-musl , aarch64-unknown-linux-musl |
🎯 Size | 32 MB compressed |
🔐 CVEs fixed | Automated nightly via GitHub Actions |
📦 Docker Hub | dockerbuildcom/rust-musl-builder |
🔗 Source | GitHub Repository |
Quick Start
Build a static Rust binary for x86_64:
docker run --rm -it -v $PWD:/src dockerbuildcom/rust-musl-builder \
cargo build --release --target x86_64-unknown-linux-musl
Why Use rust-musl-builder?
The rust-musl-builder
image simplifies the process of creating static Rust binaries by:
- Providing a ready-to-use environment with all required tools
- Supporting multiple architectures (x86_64 and aarch64)
- Including useful tools like cargo-chef for optimized builds
- Minimizing image size for faster downloads
- Regular security updates via automated builds
Static binaries built with MUSL are ideal for:
- Creating minimal Docker images (scratch or distroless)
- Distributing utilities that run on any Linux system
- Deploying to environments where you can't install dependencies
- Ensuring consistent runtime behavior across different Linux distributions
Dockerfile
Here's the Dockerfile that creates the rust-musl-builder
image:
# syntax=docker/dockerfile:1.7 <-- enables BuildKit features
ARG RUST_VERSION=1.77.0
FROM rust:${RUST_VERSION}-slim-bookworm AS base
# ---- Build dependencies ----
RUN apt-get update && apt-get install -y musl-tools pkg-config libssl-dev \
&& rustup target add x86_64-unknown-linux-musl aarch64-unknown-linux-musl \
&& cargo install cargo-chef --locked
# ---- Final minimal layer ----
FROM alpine:3.20
LABEL org.opencontainers.image.source="https://github.com/dockerbuildcom/rust-musl-builder"
COPY --from=base /usr/local/cargo /usr/local/cargo
ENV PATH="/usr/local/cargo/bin:$PATH"
ENTRYPOINT ["bash","-c","exec \"$@\"","--"]
This is a multi-stage build that:
- Starts with a slim Debian-based Rust image
- Installs MUSL toolchain and other dependencies
- Adds support for x86_64 and aarch64 MUSL targets
- Installs cargo-chef for optimized builds
- Creates a minimal Alpine-based final image with just the essentials
Building with GitHub Actions
The rust-musl-builder
image is built using GitHub Actions with the following workflow:
name: build-and-push
on:
push:
tags: ["*"] # build on every tag (v1.2.0, etc.)
workflow_dispatch:
jobs:
build:
runs-on: ubuntu-latest
permissions:
contents: read
packages: write
steps:
- uses: actions/checkout@v4
- name: Set up QEMU & Buildx
uses: docker/setup-buildx-action@v3
- name: Log in to Docker Hub
uses: docker/login-action@v3
with:
username: ${{ secrets.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }}
- name: Build & push
uses: docker/build-push-action@v5
with:
context: .
push: true
tags: |
dockerbuildcom/rust-musl-builder:latest
dockerbuildcom/rust-musl-builder:${{ github.ref_name }}
platforms: linux/amd64,linux/arm64
provenance: true # SBOM & provenance attestations
cache-from: type=gha
cache-to: type=gha,mode=max
This workflow:
- Triggers on tag pushes or manual dispatch
- Sets up Docker Buildx with QEMU for multi-architecture builds
- Logs in to Docker Hub using repository secrets
- Builds and pushes the image for both amd64 and arm64 platforms
- Generates Software Bill of Materials (SBOM) and provenance attestations
- Uses GitHub Actions cache for faster builds
Usage Examples
Building a Static Binary
To build a static Rust binary for x86_64:
docker run --rm -it -v $PWD:/src dockerbuildcom/rust-musl-builder \
cargo build --release --target x86_64-unknown-linux-musl
For aarch64:
docker run --rm -it -v $PWD:/src dockerbuildcom/rust-musl-builder \
cargo build --release --target aarch64-unknown-linux-musl
Using with cargo-chef for Faster Builds
The image includes cargo-chef, which can be used to optimize Docker build times:
# Create a recipe.json
docker run --rm -it -v $PWD:/src dockerbuildcom/rust-musl-builder \
cargo chef prepare --recipe-path recipe.json
# Build dependencies (this layer can be cached)
docker run --rm -it -v $PWD:/src dockerbuildcom/rust-musl-builder \
cargo chef cook --release --target x86_64-unknown-linux-musl --recipe-path recipe.json
# Build the project
docker run --rm -it -v $PWD:/src dockerbuildcom/rust-musl-builder \
cargo build --release --target x86_64-unknown-linux-musl
Using in a Multi-stage Dockerfile
Here's an example of how to use rust-musl-builder in a multi-stage Dockerfile:
# syntax=docker/dockerfile:1.7
FROM dockerbuildcom/rust-musl-builder AS builder
WORKDIR /src
COPY . .
RUN cargo build --release --target x86_64-unknown-linux-musl
# Use a scratch image for the smallest possible final image
FROM scratch
COPY --from=builder /src/target/x86_64-unknown-linux-musl/release/my-app /my-app
ENTRYPOINT ["/my-app"]
Local Build Instructions
If you want to build the image locally:
# Set up buildx (one-time)
docker buildx create --name multi --bootstrap --use
# Build and push the image for multiple architectures
docker buildx build --platform linux/amd64,linux/arm64 \
-t dockerbuildcom/rust-musl-builder:latest \
-t dockerbuildcom/rust-musl-builder:1.77.0 \
--provenance=builder --push .
Note
Building multi-architecture images locally requires Docker Buildx and QEMU.
Repository Structure
The rust-musl-builder
repository follows a simple structure:
rust-musl-builder/
├─ Dockerfile
├─ .dockerignore
├─ .github/
│ └─ workflows/
│ build.yml
└─ README.md