Core Code
Core Code Modern Dev Handbook
RUST Contents
Rust Foundations for Production
Toolchain and Cargo Basics Project Layout Conventions Dependency Management Basics Configuration and Environment Basics Logging First Steps
Ownership, Borrowing, Lifetimes
Ownership Model Explained Borrowing Rules Lifetimes in Practice Smart Pointers: Box, Rc, Arc Interior Mutability
Types, Traits, and APIs
Traits and Generics Newtype Pattern API Design with Result and Option Serde Derive Basics Module Visibility Patterns
Error Handling & Reliability
Error Types with anyhow and thiserror Error Context and Chaining Retries and Timeouts Basics Idempotency Basics Input Validation Basics
Testing & Quality Gates
Unit and Integration Tests Mocking Strategies Coverage and Quality Gates CI Basics Contract Tests Basics
Concurrency & Shared State
Threads and Channels Mutex and RwLock Arc and Shared Ownership Deadlocks and Debugging Send and Sync Traits
Async Rust in Production
Async Runtime with Tokio Async Cancellation Async Timeouts Async Backpressure Basics Async Common Pitfalls
Web Services Basics
HTTP Server with Axum Routing and Middleware Basics JSON Errors and Problem Details Request IDs and Correlation Graceful Shutdown
Database & Migrations Basics
Choosing SQLx or Diesel Connection Pooling Migrations Basics Transactions Basics Query Timeouts
Observability Basics
Tracing Basics Metrics Basics Health Checks and Readiness Structured Logging Production Debugging Basics
Build, Release, Deployment Intro
Cross Compilation Basics Dockerizing Rust Services Configuration and Secrets Basics Release Profiles Rollback Strategies Basics
Security & Hardening Basics
Input Sanitization Deserialization Hardening SSRF and Egress Basics TLS Basics Dependency Vulnerability Scanning

Dockerizing Rust Services

Package your Rust service into a minimal, secure container using multi-stage builds, non-root runtime, and predictable configuration. A good Docker image is reproducible, small, and operationally friendly during deployments and incidents.
On this page

Why containerization is a production concern

Containers are not only a distribution format. In production, the container image is your runtime environment: the exact libraries, the exact binary, and the exact entrypoint behavior that will run in staging and production. A good image reduces drift and makes rollouts predictable. A bad image creates hidden differences, slow deploys, and security risk.

Production goals at this level

  • Reproducible builds: same commit produces the same image.
  • Small runtime image: fewer packages means smaller attack surface and faster pull time.
  • Non-root runtime: reduce blast radius if the service is compromised.
  • Predictable config: configuration comes from environment variables or mounted files, not baked into the image.
  • Correct signals: the process handles SIGTERM so graceful shutdown works during rollouts.
  • Debuggable enough: keep a strategy for troubleshooting without turning the runtime into a full OS.

Multi-stage builds: build image vs runtime image

The core Docker production pattern is multi-stage builds:

  • Builder stage: contains Rust toolchain and compiles the binary.
  • Runtime stage: contains only what is needed to run the binary.

This keeps the final image small and avoids shipping compilers and build tooling.

Choosing a runtime base image

There are three common approaches:

  • Distroless: very small and secure, but debugging is harder.
  • Debian slim: good balance for early production; easier to debug, still small.
  • Scratch with static binary: smallest option, requires static linking (often musl) and careful setup.

At this stage, a Debian slim runtime is a safe baseline. Later you can move to distroless or scratch if needed.

Baseline Dockerfile: multi-stage, non-root, minimal runtime

This Dockerfile compiles a release binary and runs it as a non-root user. It assumes a typical Axum service listening on port 3000 and exposing /healthz and /readyz.

# syntax=docker/dockerfile:1

# Builder stage
FROM rust:1.76 as builder
WORKDIR /app

# Better layer caching:
# 1) copy manifests first
COPY Cargo.toml Cargo.lock ./

# 2) create a dummy src to build dependencies
RUN mkdir -p src && echo "fn main() { println!(\"build\"); }" > src/main.rs
RUN cargo build --release

# 3) now copy real source and rebuild
COPY . .
RUN cargo build --release

# Runtime stage
FROM debian:bookworm-slim
WORKDIR /app

# Add only needed runtime packages:
# - ca-certificates for HTTPS outbound calls
# - tzdata optional if you need local time formatting
RUN apt-get update 
 && apt-get install -y --no-install-recommends ca-certificates 
 && rm -rf /var/lib/apt/lists/*

# Create a non-root user
RUN useradd -m -u 10001 appuser

# Copy the built binary
COPY --from=builder /app/target/release/your_binary /app/your_binary

# Use non-root user
USER 10001

# Expose port
EXPOSE 3000

# Environment-driven config (example)
ENV RUST_LOG=info
ENV PORT=3000

# Entrypoint
CMD ["/app/your_binary"]

Why the caching steps matter

Container builds can become slow if every change rebuilds all dependencies. Copying Cargo.toml and Cargo.lock first allows Docker to cache dependency compilation. This reduces build time in CI and accelerates iteration without changing the runtime artifact behavior.

Environment configuration: do not bake config into images

Production images should be environment-agnostic. Configuration belongs in environment variables or mounted config files. A typical baseline:

  • DATABASE_URL from environment
  • RUST_LOG from environment
  • PORT from environment

This prevents one of the most common mistakes: rebuilding images per environment.

Health checks: how containers integrate with platforms

Many platforms rely on health endpoints to manage rollouts. Keep /healthz and /readyz enabled and fast. In Kubernetes, probes are configured externally. In plain Docker, you can also use a Docker HEALTHCHECK as a minimal local check.

# Optional Docker HEALTHCHECK (useful for local or simple deployments)
HEALTHCHECK --interval=10s --timeout=2s --start-period=10s --retries=3 
  CMD wget -q -O - http://localhost:3000/healthz || exit 1

Note: if you use wget or curl in HEALTHCHECK, the runtime image must include it. Many production images avoid this to keep the image small. In orchestrated environments, rely on platform probes instead.

Signals and graceful shutdown

During deployments, containers receive SIGTERM. Your Rust service must handle SIGTERM and drain traffic. Two key points:

  • Use your graceful shutdown implementation in the server.
  • Avoid wrapper scripts that swallow signals. Prefer running the binary directly as PID 1.

If you must use a shell entrypoint, ensure it forwards signals properly. The simplest approach is not using a shell at all.

Non-root runtime: why it matters

Running as root inside a container increases risk. If the service is compromised, the attacker gains more capabilities. Running as a dedicated low-privilege user reduces blast radius. You should still apply least privilege on volumes and network policies, but non-root is a strong baseline habit.

Debuggability strategy without bloating runtime

Minimal images are good, but incidents require visibility. A practical approach:

  • Keep production image minimal.
  • Use separate debug tooling images or ephemeral debug containers when needed.
  • Rely on logs, metrics, and tracing first before needing shell access.

This aligns with production mindset: debugging should not depend on installing tools on the runtime instance.

Common mistakes

  • Shipping the Rust toolchain in the runtime image.
  • Running as root by default.
  • Baking environment-specific config into the image.
  • Using entrypoint scripts that do not forward SIGTERM.
  • Adding many packages for convenience and forgetting to remove them.

Operational checklist

  • Image builds are reproducible and happen in CI.
  • Runtime image contains only required packages.
  • Service runs as non-root.
  • Config is environment-driven.
  • Graceful shutdown works on SIGTERM.

Minimal verification commands

# Build
docker build -t rust-service:dev .

# Run with env config
docker run --rm -p 3000:3000 
  -e RUST_LOG=info 
  -e DATABASE_URL=mysql://user:pass@host:3306/db 
  rust-service:dev

# Check health
curl -i http://localhost:3000/healthz
curl -i http://localhost:3000/readyz

What comes next

Once the service runs reliably in a container, configuration and secrets handling become the next production requirement. Next we will cover a minimal config and secrets strategy that works locally, in CI, and in production without leaking sensitive data.

Configuration and Secrets Basics →