Lorixen.
EN

Dev containers: a ready-to-code workspace for new developers

Short answer: A dev container is a Docker-based development environment described in a devcontainer.json file in your repository. When a developer opens the project in a supporting editor or a cloud workspace, it builds a container with the right language version, tools, extensions and services, so they can start coding the same day instead of spending days installing things. Keep the file small, pin versions, run setup commands automatically and treat it like code that needs maintaining.

The onboarding problem it fixes

On a small team or an agency juggling several client projects, setup is where time disappears. One project needs an older Node.js version, another a specific PHP extension, a third a command-line tool nobody remembers installing. New developers follow a README that was accurate two years ago, and existing developers break one project while fixing another.

Dev containers put the environment in the repository. Anyone who opens the project gets the same tools at the same versions, isolated from everything else on their machine.

How it works

The Development Containers specification, published at containers.dev, defines devcontainer.json. Tools that support it, including Visual Studio Code's Dev Containers extension, several other editors and cloud-hosted workspaces, read the file and create the container for you.

In VS Code, for example, the documentation describes opening a folder and using the Dev Containers: Reopen in Container command. The editor then runs inside the container, with your source code mounted in, so terminals, debuggers and extensions all use the container's tools.

A starting devcontainer.json

Keep the first version short. An illustrative file for a Node.js web app:

{
  "name": "shop-app",
  "image": "mcr.microsoft.com/devcontainers/javascript-node:22",
  "features": {
    "ghcr.io/devcontainers/features/github-cli:1": {}
  },
  "forwardPorts": [3000],
  "postCreateCommand": "npm ci",
  "customizations": {
    "vscode": {
      "extensions": ["dbaeumer.vscode-eslint"]
    }
  }
}

What each part does, according to the specification's reference:

  • image or a Dockerfile defines the base environment.
  • features add self-contained tools, such as a CLI or a language runtime, without writing install scripts.
  • forwardPorts lists ports to forward from the container, so localhost:3000 works on your machine.
  • postCreateCommand runs inside the container after it's created, which is the usual place to install dependencies.
  • customizations carry editor-specific settings, such as extensions to install.

Pin the image tag to the version your production app uses, not latest.

Adding a database and other services

Most business apps need a database. Dev containers can point at a Docker Compose file instead of a single image, so the development container runs alongside PostgreSQL, Redis or a mail catcher. You then set which service is the one the editor attaches to.

If the project already has a Compose file for local development, reuse it rather than describing the services twice.

Make setup fully automatic

The test of a good dev container is whether a new developer can go from clone to running app without asking anyone. Work towards that:

  1. Install dependencies in postCreateCommand.
  2. Create a local .env from .env.example if it doesn't exist.
  3. Run database migrations and load seed data.
  4. Print one line saying how to start the app.

Put longer steps in a script in the repository, such as scripts/setup.sh, and call that from postCreateCommand, so the JSON stays readable.

Things that trip teams up

  • Slow file access on some systems. Source mounted from the host can be slow on Mac and Windows for projects with huge dependency folders. Cloning into a container volume often helps; check your editor's documentation.
  • Secrets. Don't put API keys in devcontainer.json. Use local environment files that are ignored by Git, or your cloud workspace's secrets feature.
  • Drift. If someone installs a tool by hand inside the container and doesn't add it to the file, the next rebuild loses it. Make "add it to the config" the habit.
  • Heavy images. Every extra tool adds build time. Add what the project needs, not every tool someone might like.
  • Forgetting non-VS Code users. The specification is open, but support differs between editors. Check what your team uses.

Dev containers for client handover

For agencies, a dev container is also a good handover asset. When a client's in-house developer or another agency takes over, the environment comes with the code. That's far more reliable than a setup document, and it records exactly which versions the project was built with.

The same applies when you return to an old project after a year: rebuild the container, and the old Node.js or PHP version is there, without touching your machine.

Cloud workspaces

Several hosted services can build a cloud development environment from the same devcontainer.json, so a developer only needs a browser or a thin client. That's useful for short contracts, older laptops or demos. Compare their current pricing and usage limits before relying on them.

A worked example

Picture a hypothetical Cork web agency maintaining fifteen client sites across three PHP versions and two Node.js versions. Each new developer spent their first week fixing local setups, and switching projects regularly broke something. The agency added a dev container to each active repository, using Compose for the database, with a setup script for migrations and seed data. A new hire opened the first project and had it running before lunch, and moving between client projects became a matter of opening a different folder.

FAQ

Do dev containers replace Docker Compose?

No. They often use Compose underneath for services. The dev container adds the editor integration and the developer's tooling.

Is a dev container the same as the production image?

Usually not. It includes development tools production doesn't need. Keep the language version the same, though.

What if a developer doesn't want to use containers?

They can still follow the README. But make the dev container the supported path, so setup problems have one fix.

Do dev containers need a powerful computer?

They need Docker and some spare memory. Most current developer laptops cope; very large stacks benefit from a cloud workspace.

If onboarding developers onto your app or client projects takes too long, tell us about your setup and we'll draft a dev container.

Sources

WhatsAppBook a call