mirror of https://github.com/coder/coder.git synced 2026-09-21 12:44:32 +08:00

Files

T

Mathias Fredriksson 97bc7eb9e5 docs: restructure dev container documentation (#21157 )

Dev container admin docs were scattered across two locations: the Docker-based
integration under extending-templates/ and Envbuilder under managing-templates/.
There was no landing page explaining that two approaches exist or helping admins
choose between them.

This moves everything under admin/integrations/devcontainers/ with a decision
guide at the top. Dev containers are an integration with the dev container
specification, so integrations/ is a natural fit alongside JFrog, Vault, etc.

Stub pages remain at the original locations for discoverability.

New structure:

  admin/integrations/devcontainers/
  ├── index.md                                # Landing page + decision guide
  ├── integration.md                          # Docker-based dev containers
  └── envbuilder/
      ├── index.md
      ├── add-envbuilder.md
      ├── envbuilder-security-caching.md
      └── envbuilder-releases-known-issues.md

Refs #21080

2025-12-09 13:03:02 +02:00

5.1 KiB

Raw Blame History

Dev Containers Integration

The Dev Containers integration enables seamless creation and management of dev containers in Coder workspaces. This feature leverages the @devcontainers/cli and Docker to provide a streamlined development experience.

Note

This guide covers the Dev Containers Integration, which uses Docker. For environments without Docker, administrators can configure Envbuilder as an alternative.

Prerequisites

Coder version 2.24.0 or later
Docker available inside your workspace
The @devcontainers/cli installed in your workspace

Dev Containers integration is enabled by default. Your workspace needs Docker (via Docker-in-Docker or a mounted socket) and the devcontainers CLI. Most templates with Dev Containers support include both—see Configure a template for dev containers for setup details.

Features

Automatic dev container detection from repositories
Seamless container startup during workspace initialization
Change detection with outdated status indicator
On-demand container rebuild via dashboard button
Integrated IDE experience with VS Code
Direct SSH access to containers
Automatic port detection

Getting started

Add a devcontainer.json

Add a devcontainer.json file to your repository. This file defines your development environment. You can place it in:

.devcontainer/devcontainer.json (recommended)
.devcontainer.json (root of repository)
.devcontainer/<folder>/devcontainer.json (for multiple configurations)

The third option allows monorepos to define multiple dev container configurations in separate sub-folders. See the Dev Container specification for details.

Here's a minimal example:

{
  "name": "My Dev Container",
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu"
}

For more configuration options, see the Dev Container specification.

Start your dev container

Coder automatically discovers dev container configurations in your repositories and displays them in your workspace dashboard. From there, you can start a dev container with a single click.

If your template administrator has configured automatic startup (via the coder_devcontainer Terraform resource or autostart settings), your dev container will build and start automatically when the workspace starts.

Connect to your dev container

Once running, your dev container appears as a sub-agent in your workspace dashboard. You can connect via:

Web terminal in the Coder dashboard
SSH using coder ssh <workspace>.<agent>
VS Code using the "Open in VS Code Desktop" button

See Working with dev containers for detailed connection instructions.

How it works

The Dev Containers integration uses the devcontainer command from @devcontainers/cli to manage containers within your Coder workspace.

When a workspace with Dev Containers integration starts:

The workspace initializes the Docker environment.
The integration detects repositories with dev container configurations.
Detected dev containers appear in the Coder dashboard.
If auto-start is configured (via coder_devcontainer or autostart settings), the integration builds and starts the dev container automatically.
Coder creates a sub-agent for the running container, enabling direct access.

Without auto-start, users can manually start discovered dev containers from the dashboard.

Agent naming

Each dev container gets its own agent name, derived from the workspace folder path. For example, a dev container with workspace folder /home/coder/my-app will have an agent named my-app.

Agent names are sanitized to contain only lowercase alphanumeric characters and hyphens. You can also set a custom agent name in your devcontainer.json.

Limitations

Linux and macOS only — Dev Containers are not supported on Windows workspaces
Changes to devcontainer.json require manual rebuild using the dashboard button
The forwardPorts property in devcontainer.json with host:port syntax (e.g., "db:5432") for Docker Compose sidecar containers is not yet supported. For single-container dev containers, use coder port-forward to access ports directly on the sub-agent.
Some advanced dev container features may have limited support

Next steps

Working with dev containers — SSH, IDE integration, and port forwarding
Customizing dev containers — Custom agent names, apps, and display options
Troubleshooting dev containers — Diagnose common issues
Dev Container specification — Advanced configuration options
Dev Container features — Enhance your environment with pre-built tools

5.1 KiB Raw Blame History