The container contract
You clone a Rust repository from a friend. You run cargo build. The terminal screams about missing system libraries. You install pkg-config. It screams about libssl. You install that. The build finally starts, but it crawls for twenty minutes because your laptop is compiling OpenSSL from source. Meanwhile, your friend's machine finished in four seconds. You spent half the afternoon fighting your environment instead of writing code.
The fix isn't a better laptop. It's a container. GitHub Codespaces and Gitpod give you a pre-configured development environment in the cloud. You open a browser, and you have a fully loaded IDE with Rust, tools, and dependencies ready to go. No local setup. No "works on my machine" excuses. The environment lives in a file in your repo. Anyone who clones the repo gets the exact same setup.
Stop fighting your laptop. Let the cloud handle the setup.
The container contract
Containerized development turns your development environment into code. Instead of documenting a list of installation steps that drift over time, you define the environment in a configuration file. The platform reads that file and builds a container image. That image contains the operating system, system libraries, the Rust toolchain, and editor extensions.
When you open the repository, the platform spins up a container from that image. It mounts your code into the container. You get a terminal where rustc --version works immediately. You get an editor with syntax highlighting and type inference. The whole process takes seconds, not hours.
The environment is code. Treat it like code.
Minimal setup
The entry point for GitHub Codespaces is .devcontainer/devcontainer.json. This file tells the platform which base image to use and what customizations to apply. For Rust, the Microsoft-hosted devcontainer images are the standard choice. They come with rustup, cargo, and common system dependencies pre-installed.
{
// Use a Microsoft-hosted image that comes with Rust pre-installed.
// This saves the container from downloading and compiling Rust from scratch.
"image": "mcr.microsoft.com/devcontainers/rust:1-1.90",
// Add Docker-in-Docker if you need to build containers inside the dev container.
// Useful for testing CI pipelines or deploying microservices.
"features": {
"ghcr.io/devcontainers/features/docker-in-docker:2": {}
},
// Configure VS Code extensions to load automatically.
// rust-analyzer is the standard LSP for Rust; it provides autocomplete and error checking.
"customizations": {
"vscode": {
"extensions": ["rust-lang.rust-analyzer"]
}
}
}
For Gitpod, you use gitpod.yml. The structure is similar but the syntax differs. Gitpod reads this file to configure the workspace.
# gitpod.yml
# Define the workspace image.
# Using the same Rust image ensures consistency with Codespaces.
image:
file: .devcontainer/Dockerfile
# Prebuild tasks to run before the workspace starts.
# This fetches dependencies so the first cargo build is instant.
tasks:
- init: |
cargo fetch
cargo build --release
# VS Code extensions for Gitpod.
# Gitpod supports the same extension IDs as VS Code.
vscode:
extensions:
- rust-lang.rust-analyzer
Convention aside: The Rust community moved to rust-analyzer years ago. You might see old tutorials mentioning rls (Rust Language Server). That project is abandoned. Always use rust-analyzer. It's faster, more accurate, and actively developed by the Rust team.
What happens under the hood
When you open the repository in Codespaces or Gitpod, the platform reads the configuration file. It pulls the base image from the registry. The image already contains the Rust toolchain, cargo, and common system dependencies. The platform applies the features you listed, like Docker-in-Docker. It installs the VS Code extensions. Finally, it mounts your repository code into the container.
The container runs a Linux distribution, usually Ubuntu-based. The Rust toolchain is installed via rustup. The rust-analyzer extension connects to the rust-analyzer binary inside the container. When you edit code, the editor sends requests to the language server. The language server analyzes the code, checks types, and returns diagnostics. You get real-time feedback without running cargo check manually.
Persistence matters. Codespaces persists the container filesystem. If you install a tool or download a dependency, it stays there when you restart the workspace. Gitpod persists specific volumes, like /workspace and /home/gitpod/.cargo. You need to configure Gitpod to persist the cargo cache if you want fast builds across restarts.
Real-world configuration
A minimal setup works for simple projects. Real projects often need system libraries, custom toolchains, and caching strategies. You extend the base image with a Dockerfile to add these requirements.
# .devcontainer/Dockerfile
# Start from the official Rust image.
FROM mcr.microsoft.com/devcontainers/rust:1-1.90
# Install system dependencies required by your project.
# Many Rust crates bind to C libraries that need these packages.
RUN apt-get update && apt-get install -y \
libssl-dev \
pkg-config \
&& rm -rf /var/lib/apt/lists/*
# Configure cargo to use a shared cache directory.
# This speeds up builds across container restarts.
ENV CARGO_HOME=/usr/local/cargo
ENV CARGO_TARGET_DIR=/workspace/.cargo-target
# Add rust-src component for rust-analyzer.
# This enables go-to-definition on standard library types.
RUN rustup component add rust-src
You also need to pin your Rust version. The devcontainer image provides a base version, but your project might require a specific channel or version. Use rust-toolchain.toml to lock the version. rustup respects this file automatically.
# rust-toolchain.toml
# Pin the Rust version for the project.
# rustup respects this file automatically in devcontainers.
[toolchain]
channel = "1.90.0"
components = ["rustfmt", "clippy", "rust-src"]
Convention aside: Always use rust-toolchain.toml. It ensures every developer and every CI runner uses the exact same compiler version. The devcontainer image provides the base, but the toolchain file locks the version. This prevents subtle bugs caused by compiler differences.
Convention aside: Setting CARGO_TARGET_DIR to a specific path helps with container caching strategies. If you mount a persistent volume to that path, your build artifacts survive container restarts. This turns a five-minute build into a two-second incremental compile.
Pitfalls and gotchas
Containerized development solves many problems, but it introduces new ones. Watch out for these common issues.
Image drift is a silent killer. The base image stops updating. Security patches pile up. Dependencies become incompatible. Check your image date regularly. Pin to a specific version tag, not latest. Update the tag when you need a new Rust version.
Missing system libraries cause linker errors. If you forget libssl-dev, the compiler says error: linking with cc failed: exit status: 1. The linker can't find -lssl. You also get E0463 (could not find crate) if a crate fails to build because of missing headers. Install system dependencies in the Dockerfile, not in the post-create command. This ensures the image is self-contained.
rust-analyzer needs rust-src. Without it, clicking on Vec or String takes you nowhere. The language server can't provide definitions for standard library types. Add rustup component add rust-src to your Dockerfile or post-create command.
Caching failures waste time. If the cargo registry isn't cached, every new container downloads the entire crate registry. This takes minutes. Configure the platform to persist the cargo cache. In Codespaces, the container persists automatically. In Gitpod, you need to add the cache directory to the persistent volumes.
Check your image date. An old image is a ticking time bomb of missing patches.
Decision matrix
Choose the right tool for your workflow. Not every project needs a container. Not every container needs the same configuration.
Use GitHub Codespaces when your team already lives in GitHub and you want zero-config setup. The integration is seamless; you click a button on the repo page and get a workspace.
Use Gitpod when you need more control over the prebuild pipeline or want to support multiple IDEs beyond VS Code. Gitpod's prebuilds run on every push, keeping workspaces fresh.
Use a local development environment when you are working offline, dealing with hardware-specific debugging, or optimizing for minimal latency. Containers add network overhead that can hurt performance for tight loops.
Use a custom Dockerfile extension when your project requires system libraries not included in the base image. The base image covers common needs, but niche crates often need apt-get packages.
Pick the tool that matches your team's workflow, not the one with the flashiest demo.