Rust MUSL Builder

Minimal multi-arch builder image for reproducible static Rust binaries

Rust MUSL Static Binaries Multi-arch

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:

  1. Starts with a slim Debian-based Rust image
  2. Installs MUSL toolchain and other dependencies
  3. Adds support for x86_64 and aarch64 MUSL targets
  4. Installs cargo-chef for optimized builds
  5. 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

Docker Hub

Get the image from Docker Hub:

docker pull dockerbuildcom/rust-musl-builder
View on Docker Hub

Try Our Optimizer

Analyze your Dockerfile for optimization opportunities.

Dockerfile Optimizer