mirror of
https://github.com/coder/coder.git
synced 2026-06-02 20:48:20 +00:00
docs: rewrite dev containers documentation for GA (#21080)
docs: rewrite dev containers documentation for GA Corrects inaccuracies in SSH examples (deprecated `--container` flag), port forwarding (native sub-agent forwarding is primary), and prerequisites (dev containers are on by default). Fixes template descriptions: docker-devcontainer uses native Dev Containers while AWS/Kubernetes templates use Envbuilder. Renames admin docs folder from `devcontainers/` to `envbuilder/` to reflect actual content. Adds customization guide documenting agent naming, display apps, custom apps, and variable interpolation. Documents multi-repo workspace support and adds note about Terraform module limitations with sub-agents. Fixes module registry URLs. Refs #18907
This commit is contained in:
Mathias Fredriksson
committed by
GitHub
GitHub
parent
b4be5bcfed
commit
61beb7bfa8
@@ -0,0 +1,3 @@
|
|||||||
|
{
|
||||||
|
"ignores": ["PLAN.md"],
|
||||||
|
}
|
||||||
@@ -4,3 +4,10 @@
|
|||||||
# Redirect old offline anchor fragments to new airgap anchors
|
# Redirect old offline anchor fragments to new airgap anchors
|
||||||
/install/offline#offline-docs /install/airgap#airgap-docs 301
|
/install/offline#offline-docs /install/airgap#airgap-docs 301
|
||||||
/install/offline#offline-container-images /install/airgap#airgap-container-images 301
|
/install/offline#offline-container-images /install/airgap#airgap-container-images 301
|
||||||
|
|
||||||
|
# Redirect old devcontainers folder to envbuilder
|
||||||
|
/admin/templates/managing-templates/devcontainers /admin/templates/managing-templates/envbuilder 301
|
||||||
|
/admin/templates/managing-templates/devcontainers/index /admin/templates/managing-templates/envbuilder 301
|
||||||
|
/admin/templates/managing-templates/devcontainers/add-devcontainer /admin/templates/managing-templates/envbuilder/add-envbuilder 301
|
||||||
|
/admin/templates/managing-templates/devcontainers/devcontainer-security-caching /admin/templates/managing-templates/envbuilder/envbuilder-security-caching 301
|
||||||
|
/admin/templates/managing-templates/devcontainers/devcontainer-releases-known-issues /admin/templates/managing-templates/envbuilder/envbuilder-releases-known-issues 301
|
||||||
|
|||||||
@@ -510,9 +510,9 @@ resource "kubernetes_pod" "workspace" {
|
|||||||
## Get help
|
## Get help
|
||||||
|
|
||||||
- **Examples**: Review real-world examples from the [official Coder templates](https://registry.coder.com/contributors/coder?tab=templates):
|
- **Examples**: Review real-world examples from the [official Coder templates](https://registry.coder.com/contributors/coder?tab=templates):
|
||||||
- [AWS EC2 (Devcontainer)](https://registry.coder.com/templates/aws-devcontainer) - AWS EC2 VMs with devcontainer support
|
- [AWS EC2 (Devcontainer)](https://registry.coder.com/templates/aws-devcontainer) - AWS EC2 VMs with Envbuilder
|
||||||
- [Docker (Devcontainer)](https://registry.coder.com/templates/docker-devcontainer) - Envbuilder containers with dev container support
|
- [Docker (Devcontainer)](https://registry.coder.com/templates/docker-devcontainer) - Docker-in-Docker with Dev Containers integration
|
||||||
- [Kubernetes (Devcontainer)](https://registry.coder.com/templates/kubernetes-devcontainer) - Envbuilder pods on Kubernetes
|
- [Kubernetes (Devcontainer)](https://registry.coder.com/templates/kubernetes-devcontainer) - Kubernetes pods with Envbuilder
|
||||||
- [Docker Containers](https://registry.coder.com/templates/docker) - Basic Docker container workspaces
|
- [Docker Containers](https://registry.coder.com/templates/docker) - Basic Docker container workspaces
|
||||||
- [AWS EC2 (Linux)](https://registry.coder.com/templates/aws-linux) - AWS EC2 VMs for Linux development
|
- [AWS EC2 (Linux)](https://registry.coder.com/templates/aws-linux) - AWS EC2 VMs for Linux development
|
||||||
- [Google Compute Engine (Linux)](https://registry.coder.com/templates/gcp-vm-container) - GCP VM instances
|
- [Google Compute Engine (Linux)](https://registry.coder.com/templates/gcp-vm-container) - GCP VM instances
|
||||||
|
|||||||
+1
-1
@@ -52,7 +52,7 @@ For any information not strictly contained in these sections, check out our
|
|||||||
### Development containers (dev containers)
|
### Development containers (dev containers)
|
||||||
|
|
||||||
- A
|
- A
|
||||||
[Development Container](./templates/managing-templates/devcontainers/index.md)
|
[Development Container](./templates/extending-templates/devcontainers.md)
|
||||||
is an open-source specification for defining development environments (called
|
is an open-source specification for defining development environments (called
|
||||||
dev containers). It is generally stored in VCS alongside associated source
|
dev containers). It is generally stored in VCS alongside associated source
|
||||||
code. It can reference an existing base image, or a custom Dockerfile that
|
code. It can reference an existing base image, or a custom Dockerfile that
|
||||||
|
|||||||
@@ -25,7 +25,9 @@ This is the recommended approach for most use cases.
|
|||||||
|
|
||||||
### Project Discovery
|
### Project Discovery
|
||||||
|
|
||||||
Enable automatic discovery of Dev Containers in Git repositories. Project discovery automatically scans Git repositories for `.devcontainer/devcontainer.json` or `.devcontainer.json` files and surfaces them in the Coder UI. See the [Environment Variables](#environment-variables) section for detailed configuration options.
|
Alternatively, enable automatic discovery of Dev Containers in Git repositories.
|
||||||
|
The agent scans for `devcontainer.json` files and surfaces them in the Coder UI.
|
||||||
|
See [Environment Variables](#environment-variables) for configuration options.
|
||||||
|
|
||||||
## Install the Dev Containers CLI
|
## Install the Dev Containers CLI
|
||||||
|
|
||||||
@@ -36,7 +38,7 @@ to ensure the `@devcontainers/cli` is installed in your workspace:
|
|||||||
```terraform
|
```terraform
|
||||||
module "devcontainers-cli" {
|
module "devcontainers-cli" {
|
||||||
count = data.coder_workspace.me.start_count
|
count = data.coder_workspace.me.start_count
|
||||||
source = "dev.registry.coder.com/modules/devcontainers-cli/coder"
|
source = "registry.coder.com/coder/devcontainers-cli/coder"
|
||||||
agent_id = coder_agent.dev.id
|
agent_id = coder_agent.dev.id
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
@@ -72,6 +74,10 @@ resource "coder_devcontainer" "my-repository" {
|
|||||||
> module to ensure your repository is cloned into the workspace folder and ready
|
> module to ensure your repository is cloned into the workspace folder and ready
|
||||||
> for automatic startup.
|
> for automatic startup.
|
||||||
|
|
||||||
|
For multi-repo workspaces, define multiple `coder_devcontainer` resources, each
|
||||||
|
pointing to a different repository. Each one runs as a separate sub-agent with
|
||||||
|
its own terminal and apps in the dashboard.
|
||||||
|
|
||||||
## Enable Dev Containers Integration
|
## Enable Dev Containers Integration
|
||||||
|
|
||||||
Dev Containers integration is **enabled by default** in Coder 2.24.0 and later.
|
Dev Containers integration is **enabled by default** in Coder 2.24.0 and later.
|
||||||
@@ -119,15 +125,17 @@ by setting this to `false`.
|
|||||||
|
|
||||||
Enables automatic discovery of Dev Containers in Git repositories.
|
Enables automatic discovery of Dev Containers in Git repositories.
|
||||||
|
|
||||||
When enabled, the agent will:
|
When enabled, the agent scans the configured working directory (set via the
|
||||||
|
`directory` attribute in `coder_agent`, typically the user's home directory) for
|
||||||
|
Git repositories. If the directory itself is a Git repository, it searches that
|
||||||
|
project. Otherwise, it searches immediate subdirectories for Git repositories.
|
||||||
|
|
||||||
- Scan the agent directory for Git repositories
|
For each repository found, the agent looks for `devcontainer.json` files in the
|
||||||
- Look for `.devcontainer/devcontainer.json` or `.devcontainer.json` files
|
[standard locations](../../../user-guides/devcontainers/index.md#add-a-devcontainerjson)
|
||||||
- Surface discovered Dev Containers automatically in the Coder UI
|
and surfaces discovered Dev Containers in the Coder UI. Discovery respects
|
||||||
- Respect `.gitignore` patterns during discovery
|
`.gitignore` patterns.
|
||||||
|
|
||||||
You can disable automatic discovery by setting this to `false` if you prefer to
|
Set to `false` if you prefer explicit configuration via `coder_devcontainer`.
|
||||||
use only the `coder_devcontainer` resource for explicit configuration.
|
|
||||||
|
|
||||||
### CODER_AGENT_DEVCONTAINERS_DISCOVERY_AUTOSTART_ENABLE
|
### CODER_AGENT_DEVCONTAINERS_DISCOVERY_AUTOSTART_ENABLE
|
||||||
|
|
||||||
@@ -142,67 +150,33 @@ always auto-start regardless of this setting.
|
|||||||
|
|
||||||
## Per-Container Customizations
|
## Per-Container Customizations
|
||||||
|
|
||||||
Individual Dev Containers can be customized using the `customizations.coder` block
|
> [!NOTE]
|
||||||
in your `devcontainer.json` file. These customizations allow you to control
|
>
|
||||||
container-specific behavior without modifying your template.
|
> Dev container sub-agents are created dynamically after workspace provisioning,
|
||||||
|
> so Terraform resources like
|
||||||
|
> [`coder_script`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/script)
|
||||||
|
> and [`coder_app`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/app)
|
||||||
|
> cannot currently be attached to them. Modules from the
|
||||||
|
> [Coder registry](https://registry.coder.com) that depend on these resources
|
||||||
|
> are also not currently supported for sub-agents.
|
||||||
|
>
|
||||||
|
> To add tools to dev containers, use
|
||||||
|
> [dev container features](../../../user-guides/devcontainers/working-with-dev-containers.md#dev-container-features).
|
||||||
|
> For Coder-specific apps, use the
|
||||||
|
> [`apps` customization](../../../user-guides/devcontainers/customizing-dev-containers.md#custom-apps).
|
||||||
|
|
||||||
### Ignore Specific Containers
|
Developers can customize individual dev containers using the `customizations.coder`
|
||||||
|
block in their `devcontainer.json` file. Available options include:
|
||||||
|
|
||||||
Use the `ignore` option to hide a Dev Container from Coder completely:
|
- `ignore` — Hide a dev container from Coder completely
|
||||||
|
- `autoStart` — Control whether the container starts automatically (requires
|
||||||
|
`CODER_AGENT_DEVCONTAINERS_DISCOVERY_AUTOSTART_ENABLE` to be enabled)
|
||||||
|
- `name` — Set a custom agent name
|
||||||
|
- `displayApps` — Control which built-in apps appear
|
||||||
|
- `apps` — Define custom applications
|
||||||
|
|
||||||
```json
|
For the full reference, see
|
||||||
{
|
[Customizing dev containers](../../../user-guides/devcontainers/customizing-dev-containers.md).
|
||||||
"name": "My Dev Container",
|
|
||||||
"image": "mcr.microsoft.com/devcontainers/base:ubuntu",
|
|
||||||
"customizations": {
|
|
||||||
"coder": {
|
|
||||||
"ignore": true
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
When `ignore` is set to `true`:
|
|
||||||
|
|
||||||
- The Dev Container won't appear in the Coder UI
|
|
||||||
- Coder won't manage or monitor the container
|
|
||||||
|
|
||||||
This is useful when you have Dev Containers in your repository that you don't
|
|
||||||
want Coder to manage.
|
|
||||||
|
|
||||||
### Per-Container Auto-Start
|
|
||||||
|
|
||||||
Control whether individual Dev Containers should auto-start using the
|
|
||||||
`autoStart` option:
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"name": "My Dev Container",
|
|
||||||
"image": "mcr.microsoft.com/devcontainers/base:ubuntu",
|
|
||||||
"customizations": {
|
|
||||||
"coder": {
|
|
||||||
"autoStart": true
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
**Important**: The `autoStart` option only applies when global auto-start is
|
|
||||||
enabled via `CODER_AGENT_DEVCONTAINERS_DISCOVERY_AUTOSTART_ENABLE=true`. If
|
|
||||||
the global setting is disabled, containers won't auto-start regardless of this
|
|
||||||
setting.
|
|
||||||
|
|
||||||
When `autoStart` is set to `true`:
|
|
||||||
|
|
||||||
- The Dev Container automatically builds and starts during workspace
|
|
||||||
initialization
|
|
||||||
- Works on a per-container basis (you can enable it for some containers but not
|
|
||||||
others)
|
|
||||||
|
|
||||||
When `autoStart` is set to `false` or omitted:
|
|
||||||
|
|
||||||
- The Dev Container is discovered and shown in the UI
|
|
||||||
- Users must manually start it via the UI
|
|
||||||
|
|
||||||
## Complete Template Example
|
## Complete Template Example
|
||||||
|
|
||||||
@@ -232,7 +206,7 @@ resource "coder_agent" "dev" {
|
|||||||
|
|
||||||
module "devcontainers-cli" {
|
module "devcontainers-cli" {
|
||||||
count = data.coder_workspace.me.start_count
|
count = data.coder_workspace.me.start_count
|
||||||
source = "dev.registry.coder.com/modules/devcontainers-cli/coder"
|
source = "registry.coder.com/coder/devcontainers-cli/coder"
|
||||||
agent_id = coder_agent.dev.id
|
agent_id = coder_agent.dev.id
|
||||||
}
|
}
|
||||||
|
|
||||||
@@ -243,9 +217,10 @@ resource "coder_devcontainer" "my-repository" {
|
|||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
### Alternative: Project Discovery Mode
|
### Alternative: Project Discovery with Autostart
|
||||||
|
|
||||||
You can enable automatic starting of discovered Dev Containers:
|
By default, discovered containers appear in the dashboard but developers must
|
||||||
|
manually start them. To have them start automatically, enable autostart:
|
||||||
|
|
||||||
```terraform
|
```terraform
|
||||||
resource "docker_container" "workspace" {
|
resource "docker_container" "workspace" {
|
||||||
@@ -261,11 +236,11 @@ resource "docker_container" "workspace" {
|
|||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
With this configuration:
|
With autostart enabled:
|
||||||
|
|
||||||
- Project discovery is enabled (default behavior)
|
- Discovered containers automatically build and start during workspace
|
||||||
- Discovered containers are automatically started (via the env var)
|
initialization
|
||||||
- The `coder_devcontainer` resource is **not** required
|
- The `coder_devcontainer` resource is not required
|
||||||
- Developers can work with multiple projects seamlessly
|
- Developers can work with multiple projects seamlessly
|
||||||
|
|
||||||
> [!NOTE]
|
> [!NOTE]
|
||||||
@@ -273,8 +248,16 @@ With this configuration:
|
|||||||
> When using project discovery, you still need to install the devcontainers CLI
|
> When using project discovery, you still need to install the devcontainers CLI
|
||||||
> using the module or in your base image.
|
> using the module or in your base image.
|
||||||
|
|
||||||
|
## Example Template
|
||||||
|
|
||||||
|
The [Docker (Dev Containers)](https://github.com/coder/coder/tree/main/examples/templates/docker-devcontainer)
|
||||||
|
starter template demonstrates Dev Containers integration using Docker-in-Docker.
|
||||||
|
It includes the `devcontainers-cli` module, `git-clone` module, and the
|
||||||
|
`coder_devcontainer` resource.
|
||||||
|
|
||||||
## Next Steps
|
## Next Steps
|
||||||
|
|
||||||
- [Dev Containers Integration](../../../user-guides/devcontainers/index.md)
|
- [Dev Containers Integration](../../../user-guides/devcontainers/index.md)
|
||||||
|
- [Customizing Dev Containers](../../../user-guides/devcontainers/customizing-dev-containers.md)
|
||||||
- [Working with Dev Containers](../../../user-guides/devcontainers/working-with-dev-containers.md)
|
- [Working with Dev Containers](../../../user-guides/devcontainers/working-with-dev-containers.md)
|
||||||
- [Troubleshooting Dev Containers](../../../user-guides/devcontainers/troubleshooting-dev-containers.md)
|
- [Troubleshooting Dev Containers](../../../user-guides/devcontainers/troubleshooting-dev-containers.md)
|
||||||
|
|||||||
@@ -48,11 +48,10 @@ needs of different teams.
|
|||||||
|
|
||||||
- [Image management](./managing-templates/image-management.md): Learn how to
|
- [Image management](./managing-templates/image-management.md): Learn how to
|
||||||
create and publish images for use within Coder workspaces & templates.
|
create and publish images for use within Coder workspaces & templates.
|
||||||
- [Dev Container support](./managing-templates/devcontainers/index.md): Enable
|
- [Dev Containers integration](./extending-templates/devcontainers.md): Enable
|
||||||
dev containers to allow teams to bring their own tools into Coder workspaces.
|
native dev containers support using `@devcontainers/cli` and Docker.
|
||||||
- [Early Access Dev Containers](../../user-guides/devcontainers/index.md): Try our
|
- [Envbuilder](./managing-templates/envbuilder/index.md): Alternative approach
|
||||||
new direct devcontainers integration (distinct from Envbuilder-based
|
for environments without Docker access.
|
||||||
approach).
|
|
||||||
- [Template hardening](./extending-templates/resource-persistence.md#-bulletproofing):
|
- [Template hardening](./extending-templates/resource-persistence.md#-bulletproofing):
|
||||||
Configure your template to prevent certain resources from being destroyed
|
Configure your template to prevent certain resources from being destroyed
|
||||||
(e.g. user disks).
|
(e.g. user disks).
|
||||||
|
|||||||
+6
-7
@@ -1,10 +1,9 @@
|
|||||||
# Add a dev container template to Coder
|
# Add an Envbuilder template
|
||||||
|
|
||||||
A Coder administrator adds a dev container-compatible template to Coder
|
A Coder administrator adds an Envbuilder-compatible template to Coder. This
|
||||||
(Envbuilder). This allows the template to prompt for the developer for their dev
|
allows the template to prompt the developer for their dev container repository's
|
||||||
container repository's URL as a
|
URL as a [parameter](../../extending-templates/parameters.md) when they create
|
||||||
[parameter](../../extending-templates/parameters.md) when they create their
|
their workspace. Envbuilder clones the repo and builds a container from the
|
||||||
workspace. Envbuilder clones the repo and builds a container from the
|
|
||||||
`devcontainer.json` specified in the repo.
|
`devcontainer.json` specified in the repo.
|
||||||
|
|
||||||
You can create template files through the Coder dashboard, CLI, or you can
|
You can create template files through the Coder dashboard, CLI, or you can
|
||||||
@@ -143,4 +142,4 @@ Lifecycle scripts are managed by project developers.
|
|||||||
|
|
||||||
## Next steps
|
## Next steps
|
||||||
|
|
||||||
- [Dev container security and caching](./devcontainer-security-caching.md)
|
- [Envbuilder security and caching](./envbuilder-security-caching.md)
|
||||||
+1
-1
@@ -1,4 +1,4 @@
|
|||||||
# Dev container releases and known issues
|
# Envbuilder releases and known issues
|
||||||
|
|
||||||
## Release channels
|
## Release channels
|
||||||
|
|
||||||
+3
-3
@@ -1,4 +1,4 @@
|
|||||||
# Dev container security and caching
|
# Envbuilder security and caching
|
||||||
|
|
||||||
Ensure Envbuilder can only pull pre-approved images and artifacts by configuring
|
Ensure Envbuilder can only pull pre-approved images and artifacts by configuring
|
||||||
it with your existing HTTP proxies, firewalls, and artifact managers.
|
it with your existing HTTP proxies, firewalls, and artifact managers.
|
||||||
@@ -26,7 +26,7 @@ of caching:
|
|||||||
|
|
||||||
- Caches the entire image, skipping the build process completely (except for
|
- Caches the entire image, skipping the build process completely (except for
|
||||||
post-build
|
post-build
|
||||||
[lifecycle scripts](./add-devcontainer.md#dev-container-lifecycle-scripts)).
|
[lifecycle scripts](./add-envbuilder.md#dev-container-lifecycle-scripts)).
|
||||||
|
|
||||||
Note that caching requires push access to a registry, and may require approval
|
Note that caching requires push access to a registry, and may require approval
|
||||||
from relevant infrastructure team(s).
|
from relevant infrastructure team(s).
|
||||||
@@ -62,5 +62,5 @@ You may also wish to consult a
|
|||||||
|
|
||||||
## Next steps
|
## Next steps
|
||||||
|
|
||||||
- [Dev container releases and known issues](./devcontainer-releases-known-issues.md)
|
- [Envbuilder releases and known issues](./envbuilder-releases-known-issues.md)
|
||||||
- [Dotfiles](../../../../user-guides/workspace-dotfiles.md)
|
- [Dotfiles](../../../../user-guides/workspace-dotfiles.md)
|
||||||
+15
-6
@@ -1,9 +1,18 @@
|
|||||||
# Dev containers
|
# Envbuilder
|
||||||
|
|
||||||
A Development Container is an
|
Envbuilder is an open-source tool that builds development environments from
|
||||||
[open-source specification](https://containers.dev/implementors/spec/) for
|
[dev container](https://containers.dev/implementors/spec/) configuration files.
|
||||||
defining containerized development environments which are also called
|
Unlike the [native Dev Containers integration](../../extending-templates/devcontainers.md),
|
||||||
development containers (dev containers).
|
Envbuilder transforms the workspace image itself rather than running containers
|
||||||
|
inside the workspace.
|
||||||
|
|
||||||
|
> [!NOTE]
|
||||||
|
>
|
||||||
|
> For most use cases, we recommend the
|
||||||
|
> [native Dev Containers integration](../../extending-templates/devcontainers.md),
|
||||||
|
> which uses the standard `@devcontainers/cli` and Docker. Envbuilder is an
|
||||||
|
> alternative for environments where Docker is not available or for
|
||||||
|
> administrator-controlled dev container workflows.
|
||||||
|
|
||||||
Dev containers provide developers with increased autonomy and control over their
|
Dev containers provide developers with increased autonomy and control over their
|
||||||
Coder cloud development environments.
|
Coder cloud development environments.
|
||||||
@@ -119,4 +128,4 @@ of the Coder control plane and even run within a CI/CD pipeline.
|
|||||||
|
|
||||||
## Next steps
|
## Next steps
|
||||||
|
|
||||||
- [Add a dev container template](./add-devcontainer.md)
|
- [Add an Envbuilder template](./add-envbuilder.md)
|
||||||
@@ -70,4 +70,5 @@ specific tooling for their projects. The [Dev Container](https://containers.dev)
|
|||||||
specification allows developers to define their projects dependencies within a
|
specification allows developers to define their projects dependencies within a
|
||||||
`devcontainer.json` in their Git repository.
|
`devcontainer.json` in their Git repository.
|
||||||
|
|
||||||
- [Learn how to integrate Dev Containers with Coder](./devcontainers/index.md)
|
- [Configure a template for Dev Containers](../extending-templates/devcontainers.md) (recommended)
|
||||||
|
- [Learn about Envbuilder](./envbuilder/index.md) (alternative for environments without Docker)
|
||||||
|
|||||||
@@ -96,5 +96,6 @@ coder templates delete <template-name>
|
|||||||
## Next steps
|
## Next steps
|
||||||
|
|
||||||
- [Image management](./image-management.md)
|
- [Image management](./image-management.md)
|
||||||
- [Devcontainer templates](./devcontainers/index.md)
|
- [Dev Containers integration](../extending-templates/devcontainers.md) (recommended)
|
||||||
|
- [Envbuilder](./envbuilder/index.md) (alternative for environments without Docker)
|
||||||
- [Change management](./change-management.md)
|
- [Change management](./change-management.md)
|
||||||
|
|||||||
+17
-12
@@ -331,6 +331,11 @@
|
|||||||
"description": "Access dev containers via SSH, your IDE, or web terminal.",
|
"description": "Access dev containers via SSH, your IDE, or web terminal.",
|
||||||
"path": "./user-guides/devcontainers/working-with-dev-containers.md"
|
"path": "./user-guides/devcontainers/working-with-dev-containers.md"
|
||||||
},
|
},
|
||||||
|
{
|
||||||
|
"title": "Customizing dev containers",
|
||||||
|
"description": "Configure custom agent names, apps, and display options in devcontainer.json.",
|
||||||
|
"path": "./user-guides/devcontainers/customizing-dev-containers.md"
|
||||||
|
},
|
||||||
{
|
{
|
||||||
"title": "Troubleshooting dev containers",
|
"title": "Troubleshooting dev containers",
|
||||||
"description": "Diagnose and resolve common issues with dev containers in your Coder workspace.",
|
"description": "Diagnose and resolve common issues with dev containers in your Coder workspace.",
|
||||||
@@ -527,24 +532,24 @@
|
|||||||
"path": "./admin/templates/managing-templates/change-management.md"
|
"path": "./admin/templates/managing-templates/change-management.md"
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"title": "Dev containers",
|
"title": "Envbuilder",
|
||||||
"description": "Learn about using development containers in templates",
|
"description": "Build dev containers using Envbuilder for environments without Docker",
|
||||||
"path": "./admin/templates/managing-templates/devcontainers/index.md",
|
"path": "./admin/templates/managing-templates/envbuilder/index.md",
|
||||||
"children": [
|
"children": [
|
||||||
{
|
{
|
||||||
"title": "Add a dev container template",
|
"title": "Add an Envbuilder template",
|
||||||
"description": "How to add a dev container template to Coder",
|
"description": "How to add an Envbuilder dev container template to Coder",
|
||||||
"path": "./admin/templates/managing-templates/devcontainers/add-devcontainer.md"
|
"path": "./admin/templates/managing-templates/envbuilder/add-envbuilder.md"
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"title": "Dev container security and caching",
|
"title": "Envbuilder security and caching",
|
||||||
"description": "Configure dev container authentication and caching",
|
"description": "Configure Envbuilder authentication and caching",
|
||||||
"path": "./admin/templates/managing-templates/devcontainers/devcontainer-security-caching.md"
|
"path": "./admin/templates/managing-templates/envbuilder/envbuilder-security-caching.md"
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"title": "Dev container releases and known issues",
|
"title": "Envbuilder releases and known issues",
|
||||||
"description": "Dev container releases and known issues",
|
"description": "Envbuilder releases and known issues",
|
||||||
"path": "./admin/templates/managing-templates/devcontainers/devcontainer-releases-known-issues.md"
|
"path": "./admin/templates/managing-templates/envbuilder/envbuilder-releases-known-issues.md"
|
||||||
}
|
}
|
||||||
]
|
]
|
||||||
},
|
},
|
||||||
|
|||||||
@@ -0,0 +1,309 @@
|
|||||||
|
# Customizing dev containers
|
||||||
|
|
||||||
|
Coder supports custom configuration in your `devcontainer.json` file through the
|
||||||
|
`customizations.coder` block. These options let you control how Coder interacts
|
||||||
|
with your dev container without requiring template changes.
|
||||||
|
|
||||||
|
## Ignore a dev container
|
||||||
|
|
||||||
|
Use the `ignore` option to hide a dev container from Coder completely:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"name": "My Dev Container",
|
||||||
|
"image": "mcr.microsoft.com/devcontainers/base:ubuntu",
|
||||||
|
"customizations": {
|
||||||
|
"coder": {
|
||||||
|
"ignore": true
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
When `ignore` is set to `true`:
|
||||||
|
|
||||||
|
- The dev container won't appear in the Coder UI
|
||||||
|
- Coder won't manage or monitor the container
|
||||||
|
|
||||||
|
This is useful for dev containers in your repository that you don't want Coder
|
||||||
|
to manage.
|
||||||
|
|
||||||
|
## Auto-start
|
||||||
|
|
||||||
|
Control whether your dev container should auto-start using the `autoStart`
|
||||||
|
option:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"name": "My Dev Container",
|
||||||
|
"image": "mcr.microsoft.com/devcontainers/base:ubuntu",
|
||||||
|
"customizations": {
|
||||||
|
"coder": {
|
||||||
|
"autoStart": true
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
When `autoStart` is set to `true`, the dev container automatically builds and
|
||||||
|
starts during workspace initialization.
|
||||||
|
|
||||||
|
When `autoStart` is set to `false` or omitted, the dev container is discovered
|
||||||
|
and shown in the UI, but users must manually start it.
|
||||||
|
|
||||||
|
> [!NOTE]
|
||||||
|
>
|
||||||
|
> The `autoStart` option only takes effect when your template administrator has
|
||||||
|
> enabled [`CODER_AGENT_DEVCONTAINERS_DISCOVERY_AUTOSTART_ENABLE`](../../admin/templates/extending-templates/devcontainers.md#coder_agent_devcontainers_discovery_autostart_enable).
|
||||||
|
> If this setting is disabled at the template level, containers won't auto-start
|
||||||
|
> regardless of this option.
|
||||||
|
|
||||||
|
## Custom agent name
|
||||||
|
|
||||||
|
Each dev container gets an agent name derived from the workspace folder path by
|
||||||
|
default. You can set a custom name using the `name` option:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"name": "My Dev Container",
|
||||||
|
"image": "mcr.microsoft.com/devcontainers/base:ubuntu",
|
||||||
|
"customizations": {
|
||||||
|
"coder": {
|
||||||
|
"name": "my-custom-agent"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
The name must contain only lowercase letters, numbers, and hyphens. This name
|
||||||
|
appears in `coder ssh` commands and the dashboard (e.g.,
|
||||||
|
`coder ssh my-workspace.my-custom-agent`).
|
||||||
|
|
||||||
|
## Display apps
|
||||||
|
|
||||||
|
Control which built-in Coder apps appear for your dev container using
|
||||||
|
`displayApps`:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"name": "My Dev Container",
|
||||||
|
"image": "mcr.microsoft.com/devcontainers/base:ubuntu",
|
||||||
|
"customizations": {
|
||||||
|
"coder": {
|
||||||
|
"displayApps": {
|
||||||
|
"web_terminal": true,
|
||||||
|
"ssh_helper": true,
|
||||||
|
"port_forwarding_helper": true,
|
||||||
|
"vscode": true,
|
||||||
|
"vscode_insiders": false
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Available display apps:
|
||||||
|
|
||||||
|
| App | Description | Default |
|
||||||
|
|--------------------------|------------------------------|---------|
|
||||||
|
| `web_terminal` | Web-based terminal access | `true` |
|
||||||
|
| `ssh_helper` | SSH connection helper | `true` |
|
||||||
|
| `port_forwarding_helper` | Port forwarding interface | `true` |
|
||||||
|
| `vscode` | VS Code Desktop integration | `true` |
|
||||||
|
| `vscode_insiders` | VS Code Insiders integration | `false` |
|
||||||
|
|
||||||
|
## Custom apps
|
||||||
|
|
||||||
|
Define custom applications for your dev container using the `apps` array:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"name": "My Dev Container",
|
||||||
|
"image": "mcr.microsoft.com/devcontainers/base:ubuntu",
|
||||||
|
"customizations": {
|
||||||
|
"coder": {
|
||||||
|
"apps": [
|
||||||
|
{
|
||||||
|
"slug": "zed",
|
||||||
|
"displayName": "Zed Editor",
|
||||||
|
"url": "zed://ssh/${localEnv:CODER_WORKSPACE_AGENT_NAME}.${localEnv:CODER_WORKSPACE_NAME}.${localEnv:CODER_WORKSPACE_OWNER_NAME}.coder${containerWorkspaceFolder}",
|
||||||
|
"external": true,
|
||||||
|
"icon": "/icon/zed.svg",
|
||||||
|
"order": 1
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
This example adds a Zed Editor button that opens the dev container directly in
|
||||||
|
the Zed desktop app via its SSH remote feature.
|
||||||
|
|
||||||
|
Each app supports the following properties:
|
||||||
|
|
||||||
|
| Property | Type | Description |
|
||||||
|
|---------------|---------|---------------------------------------------------------------|
|
||||||
|
| `slug` | string | Unique identifier for the app (required) |
|
||||||
|
| `displayName` | string | Human-readable name shown in the UI |
|
||||||
|
| `url` | string | URL to open (supports variable interpolation) |
|
||||||
|
| `command` | string | Command to run instead of opening a URL |
|
||||||
|
| `icon` | string | Path to an icon (e.g., `/icon/code.svg`) |
|
||||||
|
| `openIn` | string | `"tab"` or `"slim-window"` (default: `"slim-window"`) |
|
||||||
|
| `share` | string | `"owner"`, `"authenticated"`, `"organization"`, or `"public"` |
|
||||||
|
| `external` | boolean | Open as external URL (e.g., for desktop apps) |
|
||||||
|
| `group` | string | Group name for organizing apps in the UI |
|
||||||
|
| `order` | number | Sort order for display |
|
||||||
|
| `hidden` | boolean | Hide the app from the UI |
|
||||||
|
| `subdomain` | boolean | Use subdomain-based access |
|
||||||
|
| `healthCheck` | object | Health check configuration (see below) |
|
||||||
|
|
||||||
|
### Health checks
|
||||||
|
|
||||||
|
Configure health checks to monitor app availability:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"customizations": {
|
||||||
|
"coder": {
|
||||||
|
"apps": [
|
||||||
|
{
|
||||||
|
"slug": "web-server",
|
||||||
|
"displayName": "Web Server",
|
||||||
|
"url": "http://localhost:8080",
|
||||||
|
"healthCheck": {
|
||||||
|
"url": "http://localhost:8080/healthz",
|
||||||
|
"interval": 5,
|
||||||
|
"threshold": 2
|
||||||
|
}
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Health check properties:
|
||||||
|
|
||||||
|
| Property | Type | Description |
|
||||||
|
|-------------|--------|-------------------------------------------------|
|
||||||
|
| `url` | string | URL to check for health status |
|
||||||
|
| `interval` | number | Seconds between health checks |
|
||||||
|
| `threshold` | number | Number of failures before marking app unhealthy |
|
||||||
|
|
||||||
|
## Variable interpolation
|
||||||
|
|
||||||
|
App URLs and other string values support variable interpolation for dynamic
|
||||||
|
configuration.
|
||||||
|
|
||||||
|
### Environment variables
|
||||||
|
|
||||||
|
Use `${localEnv:VAR_NAME}` to reference environment variables, with optional
|
||||||
|
default values:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"customizations": {
|
||||||
|
"coder": {
|
||||||
|
"apps": [
|
||||||
|
{
|
||||||
|
"slug": "my-app",
|
||||||
|
"url": "http://${localEnv:HOST:127.0.0.1}:${localEnv:PORT:8080}"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Coder-provided variables
|
||||||
|
|
||||||
|
Coder provides these environment variables automatically:
|
||||||
|
|
||||||
|
| Variable | Description |
|
||||||
|
|-------------------------------------|------------------------------------|
|
||||||
|
| `CODER_WORKSPACE_NAME` | Name of the workspace |
|
||||||
|
| `CODER_WORKSPACE_OWNER_NAME` | Username of the workspace owner |
|
||||||
|
| `CODER_WORKSPACE_AGENT_NAME` | Name of the dev container agent |
|
||||||
|
| `CODER_WORKSPACE_PARENT_AGENT_NAME` | Name of the parent workspace agent |
|
||||||
|
| `CODER_URL` | URL of the Coder deployment |
|
||||||
|
| `CONTAINER_ID` | Docker container ID |
|
||||||
|
|
||||||
|
### Dev container variables
|
||||||
|
|
||||||
|
Standard dev container variables are also available:
|
||||||
|
|
||||||
|
| Variable | Description |
|
||||||
|
|-------------------------------|--------------------------------------------|
|
||||||
|
| `${containerWorkspaceFolder}` | Workspace folder path inside the container |
|
||||||
|
| `${localWorkspaceFolder}` | Workspace folder path on the host |
|
||||||
|
|
||||||
|
### Session token
|
||||||
|
|
||||||
|
Use `$SESSION_TOKEN` in external app URLs to include the user's session token:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"customizations": {
|
||||||
|
"coder": {
|
||||||
|
"apps": [
|
||||||
|
{
|
||||||
|
"slug": "custom-ide",
|
||||||
|
"displayName": "Custom IDE",
|
||||||
|
"url": "custom-ide://open?token=$SESSION_TOKEN&folder=${containerWorkspaceFolder}",
|
||||||
|
"external": true
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Feature options as environment variables
|
||||||
|
|
||||||
|
When your dev container uses features, Coder exposes feature options as
|
||||||
|
environment variables. The format is `FEATURE_<FEATURE_NAME>_OPTION_<OPTION_NAME>`.
|
||||||
|
|
||||||
|
For example, with this feature configuration:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"features": {
|
||||||
|
"ghcr.io/coder/devcontainer-features/code-server:1": {
|
||||||
|
"port": 9090
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Coder creates `FEATURE_CODE_SERVER_OPTION_PORT=9090`, which you can reference in
|
||||||
|
your apps:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"features": {
|
||||||
|
"ghcr.io/coder/devcontainer-features/code-server:1": {
|
||||||
|
"port": 9090
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"customizations": {
|
||||||
|
"coder": {
|
||||||
|
"apps": [
|
||||||
|
{
|
||||||
|
"slug": "code-server",
|
||||||
|
"displayName": "Code Server",
|
||||||
|
"url": "http://localhost:${localEnv:FEATURE_CODE_SERVER_OPTION_PORT:8080}",
|
||||||
|
"icon": "/icon/code.svg"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Next steps
|
||||||
|
|
||||||
|
- [Working with dev containers](./working-with-dev-containers.md) — SSH, IDE
|
||||||
|
integration, and port forwarding
|
||||||
|
- [Troubleshooting dev containers](./troubleshooting-dev-containers.md) —
|
||||||
|
Diagnose common issues
|
||||||
@@ -1,87 +1,137 @@
|
|||||||
# Dev Containers Integration
|
# Dev Containers Integration
|
||||||
|
|
||||||
The Dev Containers integration enables seamless creation and management of Dev
|
The Dev Containers integration enables seamless creation and management of dev
|
||||||
Containers in Coder workspaces. This feature leverages the
|
containers in Coder workspaces. This feature leverages the
|
||||||
[`@devcontainers/cli`](https://github.com/devcontainers/cli) and
|
[`@devcontainers/cli`](https://github.com/devcontainers/cli) and
|
||||||
[Docker](https://www.docker.com) to provide a streamlined development
|
[Docker](https://www.docker.com) to provide a streamlined development
|
||||||
experience.
|
experience.
|
||||||
|
|
||||||
This implementation is different from the existing
|
|
||||||
[Envbuilder-based Dev Containers](../../admin/templates/managing-templates/devcontainers/index.md)
|
|
||||||
offering.
|
|
||||||
|
|
||||||
## Prerequisites
|
## Prerequisites
|
||||||
|
|
||||||
- Coder version 2.24.0 or later
|
- Coder version 2.24.0 or later
|
||||||
- Coder CLI version 2.24.0 or later
|
- Docker available inside your workspace
|
||||||
- **Linux or macOS workspace**, Dev Containers are not supported on Windows
|
- The `@devcontainers/cli` installed in your workspace
|
||||||
- A template with:
|
|
||||||
- Dev Containers integration enabled
|
|
||||||
- A Docker-compatible workspace image
|
|
||||||
- Appropriate permissions to execute Docker commands inside your workspace
|
|
||||||
|
|
||||||
## How It Works
|
Dev Containers integration is enabled by default. Your workspace needs Docker
|
||||||
|
(via Docker-in-Docker or a mounted socket) and the devcontainers CLI. Most
|
||||||
The Dev Containers integration utilizes the `devcontainer` command from
|
templates with Dev Containers support include both—see
|
||||||
[`@devcontainers/cli`](https://github.com/devcontainers/cli) to manage Dev
|
[Configure a template for dev containers](../../admin/templates/extending-templates/devcontainers.md)
|
||||||
Containers within your Coder workspace.
|
for setup details.
|
||||||
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
|
## Features
|
||||||
|
|
||||||
### Available Now
|
- 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
|
||||||
|
|
||||||
- Automatic Dev Container detection from repositories
|
## Getting started
|
||||||
- Seamless Dev Container startup during workspace initialization
|
|
||||||
- Dev Container change detection and dirty state indicators
|
### Add a devcontainer.json
|
||||||
- On-demand Dev Container recreation via rebuild button
|
|
||||||
- Integrated IDE experience in Dev Containers with VS Code
|
Add a `devcontainer.json` file to your repository. This file defines your
|
||||||
- Direct service access in Dev Containers
|
development environment. You can place it in:
|
||||||
- SSH access to Dev Containers
|
|
||||||
- Automatic port detection for container ports
|
- `.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](https://containers.dev/implementors/spec/#devcontainerjson)
|
||||||
|
for details.
|
||||||
|
|
||||||
|
Here's a minimal example:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"name": "My Dev Container",
|
||||||
|
"image": "mcr.microsoft.com/devcontainers/base:ubuntu"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
For more configuration options, see the
|
||||||
|
[Dev Container specification](https://containers.dev/).
|
||||||
|
|
||||||
|
### 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](./working-with-dev-containers.md) for detailed
|
||||||
|
connection instructions.
|
||||||
|
|
||||||
|
## How it works
|
||||||
|
|
||||||
|
The Dev Containers integration uses the `devcontainer` command from
|
||||||
|
[`@devcontainers/cli`](https://github.com/devcontainers/cli) to manage
|
||||||
|
containers within your Coder workspace.
|
||||||
|
|
||||||
|
When a workspace with Dev Containers integration starts:
|
||||||
|
|
||||||
|
1. The workspace initializes the Docker environment.
|
||||||
|
1. The integration detects repositories with dev container configurations.
|
||||||
|
1. Detected dev containers appear in the Coder dashboard.
|
||||||
|
1. If auto-start is configured (via `coder_devcontainer` or autostart settings),
|
||||||
|
the integration builds and starts the dev container automatically.
|
||||||
|
1. 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](./customizing-dev-containers.md#custom-agent-name)
|
||||||
|
in your `devcontainer.json`.
|
||||||
|
|
||||||
## Limitations
|
## Limitations
|
||||||
|
|
||||||
The Dev Containers integration has the following 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
|
||||||
|
|
||||||
- **Not supported on Windows**
|
> [!NOTE]
|
||||||
- Changes to the `devcontainer.json` file require manual container recreation
|
> If your template uses Envbuilder rather than Docker-based dev containers, see
|
||||||
using the rebuild button
|
> the [Envbuilder documentation](../../admin/templates/managing-templates/envbuilder/index.md).
|
||||||
- Some Dev Container features may not work as expected
|
|
||||||
|
|
||||||
## Comparison with Envbuilder-based Dev Containers
|
## Next steps
|
||||||
|
|
||||||
| Feature | Dev Containers Integration | Envbuilder Dev Containers |
|
- [Working with dev containers](./working-with-dev-containers.md) — SSH, IDE
|
||||||
|----------------|----------------------------------------|----------------------------------------------|
|
integration, and port forwarding
|
||||||
| Implementation | Direct `@devcontainers/cli` and Docker | Coder's Envbuilder |
|
- [Customizing dev containers](./customizing-dev-containers.md) — Custom agent
|
||||||
| Target users | Individual developers | Platform teams and administrators |
|
names, apps, and display options
|
||||||
| Configuration | Standard `devcontainer.json` | Terraform templates with Envbuilder |
|
- [Troubleshooting dev containers](./troubleshooting-dev-containers.md) —
|
||||||
| Management | User-controlled | Admin-controlled |
|
Diagnose common issues
|
||||||
| Requirements | Docker access in workspace | Compatible with more restricted environments |
|
- [Dev Container specification](https://containers.dev/) — Advanced
|
||||||
|
configuration options
|
||||||
Choose the appropriate solution based on your team's needs and infrastructure
|
- [Dev Container features](https://containers.dev/features) — Enhance your
|
||||||
constraints. For additional details on Envbuilder's Dev Container support, see
|
environment with pre-built tools
|
||||||
the
|
|
||||||
[Envbuilder Dev Container 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
|
|
||||||
|
|||||||
@@ -1,6 +1,6 @@
|
|||||||
# Troubleshooting dev containers
|
# Troubleshooting dev containers
|
||||||
|
|
||||||
## Dev Container Not Starting
|
## Dev container not starting
|
||||||
|
|
||||||
If your dev container fails to start:
|
If your dev container fails to start:
|
||||||
|
|
||||||
@@ -10,7 +10,108 @@ If your dev container fails to start:
|
|||||||
- `/tmp/coder-startup-script.log`
|
- `/tmp/coder-startup-script.log`
|
||||||
- `/tmp/coder-script-[script_id].log`
|
- `/tmp/coder-script-[script_id].log`
|
||||||
|
|
||||||
1. Verify that Docker is running in your workspace.
|
1. Verify Docker is available in your workspace (see below).
|
||||||
1. Ensure the `devcontainer.json` file is valid.
|
1. Ensure the `devcontainer.json` file is valid JSON.
|
||||||
1. Check that the repository has been cloned correctly.
|
1. Check that the repository has been cloned correctly.
|
||||||
1. Verify the resource limits in your workspace are sufficient.
|
1. Verify the resource limits in your workspace are sufficient.
|
||||||
|
|
||||||
|
## Docker not available
|
||||||
|
|
||||||
|
Dev containers require Docker, either via a running daemon (Docker-in-Docker) or
|
||||||
|
a mounted socket from the host. Your template determines which approach is used.
|
||||||
|
|
||||||
|
**If using Docker-in-Docker**, check that the daemon is running:
|
||||||
|
|
||||||
|
```console
|
||||||
|
sudo service docker status
|
||||||
|
sudo service docker start # if not running
|
||||||
|
```
|
||||||
|
|
||||||
|
**If using a mounted socket**, verify the socket exists and is accessible:
|
||||||
|
|
||||||
|
```console
|
||||||
|
ls -la /var/run/docker.sock
|
||||||
|
docker ps # test access
|
||||||
|
```
|
||||||
|
|
||||||
|
If you get permission errors, your user may need to be in the `docker` group.
|
||||||
|
|
||||||
|
## Finding your dev container agent
|
||||||
|
|
||||||
|
Use `coder show` to list all agents in your workspace, including dev container
|
||||||
|
sub-agents:
|
||||||
|
|
||||||
|
```console
|
||||||
|
coder show <workspace>
|
||||||
|
```
|
||||||
|
|
||||||
|
The agent name is derived from the workspace folder path. For details on how
|
||||||
|
names are generated, see [Agent naming](./index.md#agent-naming).
|
||||||
|
|
||||||
|
## SSH connection issues
|
||||||
|
|
||||||
|
If `coder ssh <workspace>.<agent>` fails:
|
||||||
|
|
||||||
|
1. Verify the agent name using `coder show <workspace>`.
|
||||||
|
1. Check that the dev container is running:
|
||||||
|
|
||||||
|
```console
|
||||||
|
docker ps
|
||||||
|
```
|
||||||
|
|
||||||
|
1. Check the workspace agent logs for container-related errors:
|
||||||
|
|
||||||
|
```console
|
||||||
|
grep -i container /tmp/coder-agent.log
|
||||||
|
```
|
||||||
|
|
||||||
|
## VS Code connection issues
|
||||||
|
|
||||||
|
VS Code connects to dev containers through the Coder extension. The extension
|
||||||
|
uses the sub-agent information to route connections through the parent workspace
|
||||||
|
agent to the dev container. If VS Code fails to connect:
|
||||||
|
|
||||||
|
1. Ensure you have the latest Coder VS Code extension.
|
||||||
|
1. Verify the dev container is running in the Coder dashboard.
|
||||||
|
1. Check the parent workspace agent is healthy.
|
||||||
|
1. Try restarting the dev container from the dashboard.
|
||||||
|
|
||||||
|
## Dev container features not working
|
||||||
|
|
||||||
|
If features from your `devcontainer.json` aren't being applied:
|
||||||
|
|
||||||
|
1. Rebuild the container to ensure features are installed fresh.
|
||||||
|
1. Check the container build output for feature installation errors.
|
||||||
|
1. Verify the feature reference format is correct:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"features": {
|
||||||
|
"ghcr.io/devcontainers/features/node:1": {}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Slow container startup
|
||||||
|
|
||||||
|
If your dev container takes a long time to start:
|
||||||
|
|
||||||
|
1. **Use a pre-built image** instead of building from a Dockerfile. This avoids
|
||||||
|
the image build step, though features and lifecycle scripts still run.
|
||||||
|
1. **Minimize features**. Each feature executes as a separate Docker layer
|
||||||
|
during the image build, which is typically the slowest part. Changing
|
||||||
|
`devcontainer.json` invalidates the layer cache, causing features to
|
||||||
|
reinstall on rebuild.
|
||||||
|
1. **Check lifecycle scripts**. Commands in `postStartCommand` run on every
|
||||||
|
container start. Commands in `postCreateCommand` run once per build, so
|
||||||
|
they execute again after each rebuild.
|
||||||
|
|
||||||
|
## Getting more help
|
||||||
|
|
||||||
|
If you continue to experience issues:
|
||||||
|
|
||||||
|
1. Collect logs from `/tmp/coder-agent.log` (both workspace and container).
|
||||||
|
1. Note the exact error messages.
|
||||||
|
1. Check [Coder GitHub issues](https://github.com/coder/coder/issues) for
|
||||||
|
similar problems.
|
||||||
|
1. Contact your Coder administrator for template-specific issues.
|
||||||
|
|||||||
@@ -5,93 +5,151 @@ visual representation of the running environment:
|
|||||||
|
|
||||||
|
|
||||||
|
|
||||||
## SSH Access
|
## SSH access
|
||||||
|
|
||||||
You can SSH into your dev container directly using the Coder CLI:
|
Each dev container has its own agent name, derived from the workspace folder
|
||||||
|
(e.g., `/home/coder/my-project` becomes `my-project`). You can find agent names
|
||||||
|
in your workspace dashboard, or see
|
||||||
|
[Agent naming](./index.md#agent-naming) for details on how names are generated.
|
||||||
|
|
||||||
|
### Using the Coder CLI
|
||||||
|
|
||||||
|
The simplest way to SSH into a dev container is using `coder ssh` with the
|
||||||
|
workspace and agent name:
|
||||||
|
|
||||||
```console
|
```console
|
||||||
coder ssh --container keen_dijkstra my-workspace
|
coder ssh <workspace>.<agent>
|
||||||
```
|
```
|
||||||
|
|
||||||
> [!NOTE]
|
For example, to connect to a dev container with agent name `my-project` in
|
||||||
>
|
workspace `my-workspace`:
|
||||||
> 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
|
```console
|
||||||
|
coder ssh my-workspace.my-project
|
||||||
|
```
|
||||||
|
|
||||||
|
To SSH into the main workspace agent instead of the dev container:
|
||||||
|
|
||||||
|
```console
|
||||||
|
coder ssh my-workspace
|
||||||
|
```
|
||||||
|
|
||||||
|
### Using OpenSSH (config-ssh)
|
||||||
|
|
||||||
|
You can also use standard OpenSSH tools after generating SSH config entries with
|
||||||
|
`coder config-ssh`:
|
||||||
|
|
||||||
|
```console
|
||||||
|
coder config-ssh
|
||||||
|
```
|
||||||
|
|
||||||
|
This creates a wildcard SSH host entry that matches all your workspaces and
|
||||||
|
their agents, including dev container sub-agents. You can then connect using:
|
||||||
|
|
||||||
|
```console
|
||||||
|
ssh my-project.my-workspace.me.coder
|
||||||
|
```
|
||||||
|
|
||||||
|
The default hostname suffix is `.coder`. If your organization uses a different
|
||||||
|
suffix, adjust the hostname accordingly. The suffix can be configured via
|
||||||
|
[`coder config-ssh --hostname-suffix`](../../reference/cli/config-ssh.md) or
|
||||||
|
by your deployment administrator.
|
||||||
|
|
||||||
|
This method works with any SSH client, IDE remote extensions, `rsync`, `scp`,
|
||||||
|
and other tools that use SSH.
|
||||||
|
|
||||||
|
## Web terminal access
|
||||||
|
|
||||||
Once your workspace and dev container are running, you can use the web terminal
|
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.
|
in the Coder interface to execute commands directly inside the dev container.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
## IDE Integration (VS Code)
|
## IDE integration (VS Code)
|
||||||
|
|
||||||
You can open your dev container directly in VS Code by:
|
You can open your dev container directly in VS Code by:
|
||||||
|
|
||||||
1. Selecting "Open in VS Code Desktop" from the Coder web interface
|
1. Selecting **Open in VS Code Desktop** from the dev container agent in the
|
||||||
2. Using the Coder CLI with the container flag:
|
Coder web interface.
|
||||||
|
1. Using the Coder CLI:
|
||||||
|
|
||||||
```console
|
```console
|
||||||
coder open vscode --container keen_dijkstra my-workspace
|
coder open vscode <workspace>.<agent>
|
||||||
```
|
```
|
||||||
|
|
||||||
While optimized for VS Code, other IDEs with dev containers support may also
|
For example:
|
||||||
|
|
||||||
|
```console
|
||||||
|
coder open vscode my-workspace.my-project
|
||||||
|
```
|
||||||
|
|
||||||
|
VS Code will automatically detect the dev container environment and connect
|
||||||
|
appropriately.
|
||||||
|
|
||||||
|
While optimized for VS Code, other IDEs with dev container support may also
|
||||||
work.
|
work.
|
||||||
|
|
||||||
## Port Forwarding
|
## Port forwarding
|
||||||
|
|
||||||
During the early access phase, port forwarding is limited to ports defined via
|
Since dev containers run as sub-agents, you can forward ports directly to them
|
||||||
|
using standard Coder port forwarding:
|
||||||
|
|
||||||
|
```console
|
||||||
|
coder port-forward <workspace>.<agent> --tcp 8080
|
||||||
|
```
|
||||||
|
|
||||||
|
For example, to forward port 8080 from a dev container with agent name
|
||||||
|
`my-project`:
|
||||||
|
|
||||||
|
```console
|
||||||
|
coder port-forward my-workspace.my-project --tcp 8080
|
||||||
|
```
|
||||||
|
|
||||||
|
This forwards port 8080 on your local machine directly to port 8080 in the dev
|
||||||
|
container. Coder also automatically detects ports opened inside the container.
|
||||||
|
|
||||||
|
### Exposing ports on the parent workspace
|
||||||
|
|
||||||
|
If you need to expose dev container ports through the parent workspace agent
|
||||||
|
(rather than the sub-agent), you can use the
|
||||||
[`appPort`](https://containers.dev/implementors/json_reference/#image-specific)
|
[`appPort`](https://containers.dev/implementors/json_reference/#image-specific)
|
||||||
in your `devcontainer.json` file.
|
property in your `devcontainer.json`:
|
||||||
|
|
||||||
> [!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
|
```json
|
||||||
{
|
{
|
||||||
"appPort": ["8080:8080", "4000:3000"]
|
"appPort": ["8080:8080", "4000:3000"]
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
You can forward these ports to your local machine using:
|
This maps container ports to the parent workspace, which can then be forwarded
|
||||||
|
using the main workspace agent.
|
||||||
|
|
||||||
```console
|
## Dev container features
|
||||||
coder port-forward my-workspace --tcp 8080,4000
|
|
||||||
```
|
|
||||||
|
|
||||||
This forwards port 8080 (local) -> 8080 (agent) -> 8080 (dev container) and port
|
You can use standard [dev container features](https://containers.dev/features)
|
||||||
4000 (local) -> 4000 (agent) -> 3000 (dev container).
|
in your `devcontainer.json` file. Coder also maintains a
|
||||||
|
|
||||||
## 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
|
[repository of features](https://github.com/coder/devcontainer-features) to
|
||||||
enhance your development experience.
|
enhance your development experience.
|
||||||
|
|
||||||
Currently available features include [code-server](https://github.com/coder/devcontainer-features/blob/main/src/code-server).
|
For example, the
|
||||||
|
[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`:
|
feature from the [Coder features repository](https://github.com/coder/devcontainer-features):
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"features": {
|
"features": {
|
||||||
"ghcr.io/coder/devcontainer-features/code-server:1": {
|
"ghcr.io/coder/devcontainer-features/code-server:1": {
|
||||||
"port": 13337,
|
"port": 13337,
|
||||||
"host": "0.0.0.0"
|
"host": "0.0.0.0"
|
||||||
}
|
}
|
||||||
},
|
}
|
||||||
"appPort": ["13337:13337"]
|
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
> [!NOTE]
|
## Rebuilding dev containers
|
||||||
>
|
|
||||||
> Remember to include the port in the `appPort` section to ensure proper port
|
When you modify your `devcontainer.json`, you need to rebuild the container for
|
||||||
> forwarding.
|
changes to take effect. Coder detects changes and shows an **Outdated** status
|
||||||
|
next to the dev container.
|
||||||
|
|
||||||
|
Click **Rebuild** to recreate your dev container with the updated configuration.
|
||||||
|
|||||||
@@ -7,7 +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
|
refer to our docs on configuring [templates](../admin/index.md) or the
|
||||||
[control plane](../admin/index.md).
|
[control plane](../admin/index.md).
|
||||||
|
|
||||||
Check out our [early access features](../install/releases/feature-stages.md) for upcoming
|
Check out [Dev Containers integration](./devcontainers/index.md) for running
|
||||||
functionality, including [Dev Containers integration](../user-guides/devcontainers/index.md).
|
containerized development environments in your Coder workspace.
|
||||||
|
|
||||||
<children></children>
|
<children></children>
|
||||||
|
|||||||
Reference in New Issue
Block a user