Rust with Cargo

🐳 Annotated Dockerfile for Rust with Cargo:

# Use Rust official image with debian bookworm (12) as base
FROM rust:1.86-slim-bookworm AS builder
 
# Set build arguments for customization
ARG APP_NAME=myapp
ARG PROFILE=release
 
# Create a new empty shell project
RUN USER=root cargo new --bin ${APP_NAME}
WORKDIR /usr/${APP_NAME}
 
# Copy manifests first for dependency caching
COPY Cargo.lock Cargo.toml ./
 
# Copy the source code
COPY src ./src/
 
# Build only the dependencies to cache them
RUN --mount=type=cache,target=/usr/local/cargo/registry \
    --mount=type=cache,target=/usr/${APP_NAME}/target \
    cargo build --profile ${PROFILE} && \
    rm -rf target/${PROFILE}/.fingerprint/${APP_NAME}-*
 
# Build the application and copy binary to a accessible location
RUN --mount=type=cache,target=/usr/${APP_NAME}/target \
    cargo build --profile ${PROFILE} && \
    mkdir -p /tmp/app && \
    find /usr/${APP_NAME}/target/${PROFILE} -type f -executable -name "rust-cargo-test" -exec cp {} /tmp/app/myapp \;
 
# --------------------------------------
# Stage 2: Final minimal runtime image
# --------------------------------------
# Use Debian slim for minimal runtime image
FROM debian:bookworm-slim
 
# Install only runtime dependencies
RUN apt-get update && apt-get install -y --no-install-recommends \
    ca-certificates \
    && rm -rf /var/lib/apt/lists/*
 
# Create a non-root user and group for running the application
RUN groupadd -r appuser && useradd -r -g appuser appuser
 
# Create app directory
WORKDIR /app
 
# Copy the built binary from the temp location
COPY --from=builder /tmp/app/myapp /app/myapp
 
# Set ownership
RUN chown appuser:appuser /app/myapp
 
# Switch to non-root user
USER appuser
 
# Expose application port
EXPOSE 8080
 
# Set the entrypoint to the binary
ENTRYPOINT ["/app/myapp"]

🔍 Why these are best practices:

✅ Multi-stage builds

Dramatically reduces final image size from ~1.5GB to ~100MB.
Eliminates all build dependencies, toolchains, and intermediate artifacts.
Keeps only the compiled binary in the final image for enhanced security.

✅ Cargo registry caching

Uses Docker's build cache efficiently by caching the Cargo registry.
Speeds up build times dramatically on iterative builds.
Avoids re-downloading dependencies when only source code changes.

✅ Dependency layering optimization

Builds dependencies first, separately from the application code.
Leverages Docker's layer caching for faster rebuilds when only the app code changes.
Only re-compiles what's necessary on subsequent builds.

✅ Profile-based optimization

Uses Cargo's build profiles (release, dev) for different environments.
Release profile enables optimizations like LTO (Link Time Optimization).
Configurable via build arguments for flexibility.

✅ Minimal runtime container

Uses debian:slim or distroless as the final image for minimal attack surface.
Includes only what's needed to run the binary, not build tools.
Rust's static linking minimizes runtime dependencies.

🚀 Additional Dockerfile best practices you can adopt:

Use Alpine for even smaller images

If binary size is critical and your application doesn't rely on glibc:

FROM rust:1.86-alpine AS builder
 
# Install required build dependencies
RUN apk add --no-cache musl-dev
 
# ... (build steps) ...
 
FROM alpine:3.21
 
RUN apk add --no-cache ca-certificates
 
# ... (final stage) ...

Cross-compilation for different architectures

For multi-architecture builds:

FROM rust:1.86-slim-bookworm AS builder
 
# Install cross-compilation tooling
RUN apt-get update && apt-get install -y --no-install-recommends \
    gcc-aarch64-linux-gnu libc6-dev-arm64-cross && \
    rustup target add aarch64-unknown-linux-gnu
 
# Build for ARM64
RUN --mount=type=cache,target=/usr/local/cargo/registry \
    cargo build --release --target aarch64-unknown-linux-gnu

Use .dockerignore

Create a proper .dockerignore file to speed up builds by excluding unnecessary files:

.git
.gitignore
.github
.vscode
target
Dockerfile
README.md
*.md

Configure startup health checks

Ensure your container reports health correctly:

HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD curl -f http://localhost:8000/health || exit 1

Enable Cargo features selectively

For configurable container builds:

ARG FEATURES=default
 
# Then in the build command:
RUN cargo build --profile ${PROFILE} --features ${FEATURES}

Optimize binary size further

For the absolute smallest binaries, configure the release profile:

# In Cargo.toml
[profile.release]
opt-level = 'z'     # Optimize for size
lto = true          # Enable Link Time Optimization
codegen-units = 1   # Maximize size reduction optimizations
panic = 'abort'     # Remove backtrace support
strip = true        # Remove debug symbols

By following these practices, you'll create Docker images for your Rust applications that are secure, efficient, and optimized for production environments. Rust's strong compilation guarantees and performance characteristics pair perfectly with Docker's containerization benefits, resulting in robust and reliable deployments.

Rust with Cargo

On this page