shishantbiswas/coder
1
0
Fork 0
mirror of https://github.com/coder/coder.git synced 2026-06-02 20:48:20 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: add early access dev container docs (#17613)

Browse Source 
This change documents the early access dev containers integration and
how to enable it, what features are available and what limitations exist
at the time of writing.

---------

Co-authored-by: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com>
This commit is contained in:
Mathias Fredriksson
2025-05-02 01:45:02 +03:00
committed by GitHub
parent ef11d4f769
commit a226a75b32
9 changed files with 363 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/admin/templates/extending-templates/devcontainers.md
+124
View File
@@ -0,0 +1,124 @@
# Configure a template for dev containers
To enable dev containers in workspaces, configure your template with the dev containers
modules and configurations outlined in this doc.
## Install the Dev Containers CLI
Use the
[devcontainers-cli](https://registry.coder.com/modules/devcontainers-cli) module
to ensure the `@devcontainers/cli` is installed in your workspace:
```terraform
module "devcontainers-cli" {
count = data.coder_workspace.me.start_count
source = "dev.registry.coder.com/modules/devcontainers-cli/coder"
agent_id = coder_agent.dev.id
}
```
Alternatively, install the devcontainer CLI manually in your base image.
## Configure Automatic Dev Container Startup
The
[`coder_devcontainer`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/devcontainer)
resource automatically starts a dev container in your workspace, ensuring it's
ready when you access the workspace:
```terraform
resource "coder_devcontainer" "my-repository" {
count = data.coder_workspace.me.start_count
agent_id = coder_agent.dev.id
workspace_folder = "/home/coder/my-repository"
}
```
> [!NOTE]
>
> The `workspace_folder` attribute must specify the location of the dev
> container's workspace and should point to a valid project folder containing a
> `devcontainer.json` file.
<!-- nolint:MD028/no-blanks-blockquote -->
> [!TIP]
>
> Consider using the [`git-clone`](https://registry.coder.com/modules/git-clone)
> module to ensure your repository is cloned into the workspace folder and ready
> for automatic startup.
## Enable Dev Containers Integration
To enable the dev containers integration in your workspace, you must set the
`CODER_AGENT_DEVCONTAINERS_ENABLE` environment variable to `true` in your
workspace container:
```terraform
resource "docker_container" "workspace" {
count = data.coder_workspace.me.start_count
image = "codercom/oss-dogfood:latest"
env = [
"CODER_AGENT_DEVCONTAINERS_ENABLE=true",
# ... Other environment variables.
]
# ... Other container configuration.
}
```
This environment variable is required for the Coder agent to detect and manage
dev containers. Without it, the agent will not attempt to start or connect to
dev containers even if the `coder_devcontainer` resource is defined.
## Complete Template Example
Here's a simplified template example that enables the dev containers
integration:
```terraform
terraform {
required_providers {
coder = { source = "coder/coder" }
docker = { source = "kreuzwerker/docker" }
}
}
provider "coder" {}
data "coder_workspace" "me" {}
data "coder_workspace_owner" "me" {}
resource "coder_agent" "dev" {
arch = "amd64"
os = "linux"
startup_script_behavior = "blocking"
startup_script = "sudo service docker start"
shutdown_script = "sudo service docker stop"
# ...
}
module "devcontainers-cli" {
count = data.coder_workspace.me.start_count
source = "dev.registry.coder.com/modules/devcontainers-cli/coder"
agent_id = coder_agent.dev.id
}
resource "coder_devcontainer" "my-repository" {
count = data.coder_workspace.me.start_count
agent_id = coder_agent.dev.id
workspace_folder = "/home/coder/my-repository"
}
resource "docker_container" "workspace" {
count = data.coder_workspace.me.start_count
image = "codercom/oss-dogfood:latest"
env = [
"CODER_AGENT_DEVCONTAINERS_ENABLE=true",
# ... Other environment variables.
]
# ... Other container configuration.
}
```
## Next Steps
- [Dev Containers Integration](../../../user-guides/devcontainers/index.md)
docs/admin/templates/index.md
+3
View File
@@ -50,6 +50,9 @@ needs of different teams.
create and publish images for use within Coder workspaces & templates.
- [Dev Container support](./managing-templates/devcontainers/index.md): Enable
dev containers to allow teams to bring their own tools into Coder workspaces.
- [Early Access Dev Containers](../../user-guides/devcontainers/index.md): Try our
new direct devcontainers integration (distinct from Envbuilder-based
approach).
- [Template hardening](./extending-templates/resource-persistence.md#-bulletproofing):
Configure your template to prevent certain resources from being destroyed
(e.g. user disks).
docs/images/user-guides/devcontainers/devcontainer-agent-ports.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 133 KiB

docs/images/user-guides/devcontainers/devcontainer-web-terminal.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 50 KiB

docs/manifest.json
+21
View File
@@ -213,6 +213,27 @@
"path": "./user-guides/workspace-lifecycle.md",
"icon_path": "./images/icons/circle-dot.svg"
},
{
"title": "Dev Containers Integration",
"description": "Run containerized development environments in your Coder workspace using the dev containers specification.",
"path": "./user-guides/devcontainers/index.md",
"icon_path": "./images/icons/container.svg",
"state": ["early access"],
"children": [
{
"title": "Working with dev containers",
"description": "Access dev containers via SSH, your IDE, or web terminal.",
"path": "./user-guides/devcontainers/working-with-dev-containers.md",
"state": ["early access"]
},
{
"title": "Troubleshooting dev containers",
"description": "Diagnose and resolve common issues with dev containers in your Coder workspace.",
"path": "./user-guides/devcontainers/troubleshooting-dev-containers.md",
"state": ["early access"]
}
]
},
{
"title": "Dotfiles",
"description": "Personalize your environment with dotfiles",
docs/user-guides/devcontainers/index.md
+99
View File
@@ -0,0 +1,99 @@
# Dev Containers Integration
> [!NOTE]
>
> The Coder dev containers integration is an [early access](../../install/releases/feature-stages.md) feature.
>
> While functional for testing and feedback, it may change significantly before general availability.
The dev containers integration is an early access feature that enables seamless
creation and management of dev containers in Coder workspaces. This feature
leverages the [`@devcontainers/cli`](https://github.com/devcontainers/cli) and
[Docker](https://www.docker.com) to provide a streamlined development
experience.
This implementation is different from the existing
[Envbuilder-based dev containers](../../admin/templates/managing-templates/devcontainers/index.md)
offering.
## Prerequisites
- Coder version 2.22.0 or later
- Coder CLI version 2.22.0 or later
- A template with:
- Dev containers integration enabled
- A Docker-compatible workspace image
- Appropriate permissions to execute Docker commands inside your workspace
## How It Works
The dev containers integration utilizes the `devcontainer` command from
[`@devcontainers/cli`](https://github.com/devcontainers/cli) to manage dev
containers within your Coder workspace.
This command provides comprehensive functionality for creating, starting, and managing dev containers.
Dev environments are configured through a standard `devcontainer.json` file,
which allows for extensive customization of your development setup.
When a workspace with the dev containers integration starts:
1. The workspace initializes the Docker environment.
1. The integration detects repositories with a `.devcontainer` directory or a
`devcontainer.json` file.
1. The integration builds and starts the dev container based on the
configuration.
1. Your workspace automatically detects the running dev container.
## Features
### Available Now
- Automatic dev container detection from repositories
- Seamless dev container startup during workspace initialization
- Integrated IDE experience in dev containers with VS Code
- Direct service access in dev containers
- Limited SSH access to dev containers
### Coming Soon
- Dev container change detection
- On-demand dev container recreation
- Support for automatic port forwarding inside the container
- Full native SSH support to dev containers
## Limitations during Early Access
During the early access phase, the dev containers integration has the following
limitations:
- Changes to the `devcontainer.json` file require manual container recreation
- Automatic port forwarding only works for ports specified in `appPort`
- SSH access requires using the `--container` flag
- Some devcontainer features may not work as expected
These limitations will be addressed in future updates as the feature matures.
## Comparison with Envbuilder-based Dev Containers
| Feature | Dev Containers (Early Access) | Envbuilder Dev Containers |
|----------------|----------------------------------------|----------------------------------------------|
| Implementation | Direct `@devcontainers/cli` and Docker | Coder's Envbuilder |
| Target users | Individual developers | Platform teams and administrators |
| Configuration | Standard `devcontainer.json` | Terraform templates with Envbuilder |
| Management | User-controlled | Admin-controlled |
| Requirements | Docker access in workspace | Compatible with more restricted environments |
Choose the appropriate solution based on your team's needs and infrastructure
constraints. For additional details on Envbuilder's dev container support, see
the
[Envbuilder devcontainer spec support documentation](https://github.com/coder/envbuilder/blob/main/docs/devcontainer-spec-support.md).
## Next Steps
- Explore the [dev container specification](https://containers.dev/) to learn
more about advanced configuration options
- Read about [dev container features](https://containers.dev/features) to
enhance your development environment
- Check the
[VS Code dev containers documentation](https://code.visualstudio.com/docs/devcontainers/containers)
for IDE-specific features
docs/user-guides/devcontainers/troubleshooting-dev-containers.md
+16
View File
@@ -0,0 +1,16 @@
# Troubleshooting dev containers
## Dev Container Not Starting
If your dev container fails to start:
1. Check the agent logs for error messages:
- `/tmp/coder-agent.log`
- `/tmp/coder-startup-script.log`
- `/tmp/coder-script-[script_id].log`
1. Verify that Docker is running in your workspace.
1. Ensure the `devcontainer.json` file is valid.
1. Check that the repository has been cloned correctly.
1. Verify the resource limits in your workspace are sufficient.
docs/user-guides/devcontainers/working-with-dev-containers.md
+97
View File
@@ -0,0 +1,97 @@
# Working with Dev Containers
The dev container integration appears in your Coder dashboard, providing a
visual representation of the running environment:
![Dev container integration in Coder dashboard](../../images/user-guides/devcontainers/devcontainer-agent-ports.png)
## SSH Access
You can SSH into your dev container directly using the Coder CLI:
```console
coder ssh --container keen_dijkstra my-workspace
```
> [!NOTE]
>
> SSH access is not yet compatible with the `coder config-ssh` command for use
> with OpenSSH. You would need to manually modify your SSH config to include the
> `--container` flag in the `ProxyCommand`.
## Web Terminal Access
Once your workspace and dev container are running, you can use the web terminal
in the Coder interface to execute commands directly inside the dev container.
![Coder web terminal with dev container](../../images/user-guides/devcontainers/devcontainer-web-terminal.png)
## IDE Integration (VS Code)
You can open your dev container directly in VS Code by:
1. Selecting "Open in VS Code Desktop" from the Coder web interface
2. Using the Coder CLI with the container flag:
```console
coder open vscode --container keen_dijkstra my-workspace
```
While optimized for VS Code, other IDEs with dev containers support may also
work.
## Port Forwarding
During the early access phase, port forwarding is limited to ports defined via
[`appPort`](https://containers.dev/implementors/json_reference/#image-specific)
in your `devcontainer.json` file.
> [!NOTE]
>
> Support for automatic port forwarding via the `forwardPorts` property in
> `devcontainer.json` is planned for a future release.
For example, with this `devcontainer.json` configuration:
```json
{
"appPort": ["8080:8080", "4000:3000"]
}
```
You can forward these ports to your local machine using:
```console
coder port-forward my-workspace --tcp 8080,4000
```
This forwards port 8080 (local) -> 8080 (agent) -> 8080 (dev container) and port
4000 (local) -> 4000 (agent) -> 3000 (dev container).
## Dev Container Features
You can use standard dev container features in your `devcontainer.json` file.
Coder also maintains a
[repository of features](https://github.com/coder/devcontainer-features) to
enhance your development experience.
Currently available features include [code-server](https://github.com/coder/devcontainer-features/blob/main/src/code-server).
To use the code-server feature, add the following to your `devcontainer.json`:
```json
{
"features": {
"ghcr.io/coder/devcontainer-features/code-server:1": {
"port": 13337,
"host": "0.0.0.0"
}
},
"appPort": ["13337:13337"]
}
```
> [!NOTE]
>
> Remember to include the port in the `appPort` section to ensure proper port
> forwarding.
docs/user-guides/index.md
+3
View File
@@ -7,4 +7,7 @@ These are intended for end-user flows only. If you are an administrator, please
refer to our docs on configuring [templates](../admin/index.md) or the
[control plane](../admin/index.md).
Check out our [early access features](../install/releases/feature-stages.md) for upcoming
functionality, including [Dev Containers integration](../user-guides/devcontainers/index.md).
<children></children>