Module 3: Dev Containers & Your Environment | AZD for Beginners

"Skip 'it works on my machine.' A dev container gives you a clean, identical, ready-to-go workspace — azd already installed — in one click."

Level: Beginner · Time: ~1 day · Prerequisites: Module 2

Learning Objectives

By the end of this module, you will be able to:

Explain what a dev container is and why it helps
Use a GitHub Codespace or local dev container with azd
Recognize what a .devcontainer folder does
Choose between local and container-based setups

Every developer's machine is slightly different — different OS, tool versions, and settings. That's why setup instructions so often fail on someone's laptop. A dev container solves this by packaging the whole development environment (tools, versions, extensions) into a container that runs the same everywhere.

Picture two teammates, one on the newest Node and one a couple of versions behind: the app runs for one and crashes for the other. Hours vanish chasing a bug that lives in the version mismatch, not the code — exactly the trap a dev container removes by pinning every tool to a known version.

Explain like I'm new: A dev container is a fully-stocked kitchen in a box. Instead of hoping your kitchen has the right pans and ingredients, you open the box and everything you need — including azd — is already there and arranged the same way for everyone.

2. Codespaces: The One-Click Option

Many azd templates include a GitHub Codespace button. Click it and GitHub spins up a cloud dev environment in your browser with azd, the Azure CLI, Bicep, and Git all pre-installed. You start coding and deploying immediately — nothing to install locally.

You launch one from a repository's green Code button: open the Codespaces tab, click Create, and about a minute later you're editing in a full browser-based VS Code. GitHub includes a monthly allowance of free Codespace hours, so trying one costs nothing to start.

Concept: A Codespace is a dev container running in the cloud. Same benefit as a local container (identical environment), but you don't even need Docker on your machine — it runs on GitHub's.

3. The `.devcontainer` Folder

How does the environment know what to include? A template ships a .devcontainer folder with a config file that lists the base image, tools to install (like azd), and editor extensions. When you open the project in a container, that config builds your workspace automatically.

jsonc

[object Object],
,[object Object],
  ,[object Object],[object Object], ,[object Object],[object Object],
  ,[object Object],[object Object], ,[object Object], ,[object Object],[object Object], ,[object Object],[object Object], ,[object Object],
,[object Object],

The features block is the clever part: each entry is a reusable install recipe. Adding azd is a single line, and the container build handles the download, the correct version, and wiring it onto your PATH.

Try this: Open any azd template on GitHub and look for a .devcontainer folder. Its presence is a promise: "click to get a ready-made environment with everything installed."

4. Local Dev Containers

Prefer to work locally? With Docker and VS Code's Dev Containers extension, you can open the same .devcontainer on your own machine. VS Code builds the container and drops you inside it — identical tools, but running on your hardware.

Option	Best when…
Codespace	You want zero local setup / are on a locked-down machine
Local dev container	You want the clean environment but prefer local speed
Local install (Module 2)	You want full control and use azd across many projects

5. Why It Matters for Teams

Dev containers make onboarding trivial and eliminate a whole class of "works on my machine" bugs. Everyone — and every CI server — builds against the same environment, so a template that deploys for one person deploys for all.

Real-world use case: A new hire clones the repo, clicks Create Codespace, and is running azd up within minutes — no day-one setup ticket, no chasing tool versions. Their environment is the exact one the rest of the team already uses.

Common mistake: Spending an afternoon debugging a teammate's broken local setup. If the project has a dev container, use it — the environment is already solved, and you can focus on the app instead of the tooling.

✅ Checkpoint

What problem does a dev container solve?
What's the difference between a Codespace and a local dev container?
What does the .devcontainer folder define?

Answers: 1) It gives everyone an identical, ready-to-go environment, ending "works on my machine." 2) A Codespace runs the container in the cloud (no local Docker needed); a local dev container runs it on your machine. 3) The environment: base image, tools to install (like azd), and editor extensions.

Key Takeaway: A dev container packages your whole workspace — azd and its tools included — so it runs identically everywhere. Templates often offer a one-click GitHub Codespace (cloud) or a local dev container (via Docker + VS Code), both driven by a .devcontainer config. This kills environment bugs and makes onboarding instant.

Further Learning

Part of "AZD for Beginners." Adapted from Microsoft's open AZD curriculum (MIT License).