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
|
||||
/install/offline#offline-docs /install/airgap#airgap-docs 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
|
||||
|
||||
- **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
|
||||
- [Docker (Devcontainer)](https://registry.coder.com/templates/docker-devcontainer) - Envbuilder containers with dev container support
|
||||
- [Kubernetes (Devcontainer)](https://registry.coder.com/templates/kubernetes-devcontainer) - Envbuilder pods on Kubernetes
|
||||
- [AWS EC2 (Devcontainer)](https://registry.coder.com/templates/aws-devcontainer) - AWS EC2 VMs with Envbuilder
|
||||
- [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) - Kubernetes pods with Envbuilder
|
||||
- [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
|
||||
- [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)
|
||||
|
||||
- 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
|
||||
dev containers). It is generally stored in VCS alongside associated source
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
@@ -36,7 +38,7 @@ 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"
|
||||
source = "registry.coder.com/coder/devcontainers-cli/coder"
|
||||
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
|
||||
> 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
|
||||
|
||||
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.
|
||||
|
||||
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
|
||||
- Look for `.devcontainer/devcontainer.json` or `.devcontainer.json` files
|
||||
- Surface discovered Dev Containers automatically in the Coder UI
|
||||
- Respect `.gitignore` patterns during discovery
|
||||
For each repository found, the agent looks for `devcontainer.json` files in the
|
||||
[standard locations](../../../user-guides/devcontainers/index.md#add-a-devcontainerjson)
|
||||
and surfaces discovered Dev Containers in the Coder UI. Discovery respects
|
||||
`.gitignore` patterns.
|
||||
|
||||
You can disable automatic discovery by setting this to `false` if you prefer to
|
||||
use only the `coder_devcontainer` resource for explicit configuration.
|
||||
Set to `false` if you prefer explicit configuration via `coder_devcontainer`.
|
||||
|
||||
### CODER_AGENT_DEVCONTAINERS_DISCOVERY_AUTOSTART_ENABLE
|
||||
|
||||
@@ -142,67 +150,33 @@ always auto-start regardless of this setting.
|
||||
|
||||
## Per-Container Customizations
|
||||
|
||||
Individual Dev Containers can be customized using the `customizations.coder` block
|
||||
in your `devcontainer.json` file. These customizations allow you to control
|
||||
container-specific behavior without modifying your template.
|
||||
> [!NOTE]
|
||||
>
|
||||
> 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
|
||||
{
|
||||
"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
|
||||
For the full reference, see
|
||||
[Customizing dev containers](../../../user-guides/devcontainers/customizing-dev-containers.md).
|
||||
|
||||
## Complete Template Example
|
||||
|
||||
@@ -232,7 +206,7 @@ resource "coder_agent" "dev" {
|
||||
|
||||
module "devcontainers-cli" {
|
||||
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
|
||||
}
|
||||
|
||||
@@ -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
|
||||
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 are automatically started (via the env var)
|
||||
- The `coder_devcontainer` resource is **not** required
|
||||
- Discovered containers automatically build and start during workspace
|
||||
initialization
|
||||
- The `coder_devcontainer` resource is not required
|
||||
- Developers can work with multiple projects seamlessly
|
||||
|
||||
> [!NOTE]
|
||||
@@ -273,8 +248,16 @@ With this configuration:
|
||||
> When using project discovery, you still need to install the devcontainers CLI
|
||||
> 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
|
||||
|
||||
- [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)
|
||||
- [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
|
||||
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).
|
||||
- [Dev Containers integration](./extending-templates/devcontainers.md): Enable
|
||||
native dev containers support using `@devcontainers/cli` and Docker.
|
||||
- [Envbuilder](./managing-templates/envbuilder/index.md): Alternative approach
|
||||
for environments without Docker access.
|
||||
- [Template hardening](./extending-templates/resource-persistence.md#-bulletproofing):
|
||||
Configure your template to prevent certain resources from being destroyed
|
||||
(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
|
||||
(Envbuilder). This allows the template to prompt for the developer for their dev
|
||||
container repository's URL as a
|
||||
[parameter](../../extending-templates/parameters.md) when they create their
|
||||
workspace. Envbuilder clones the repo and builds a container from the
|
||||
A Coder administrator adds an Envbuilder-compatible template to Coder. This
|
||||
allows the template to prompt the developer for their dev container repository's
|
||||
URL as a [parameter](../../extending-templates/parameters.md) when they create
|
||||
their workspace. Envbuilder clones the repo and builds a container from the
|
||||
`devcontainer.json` specified in the repo.
|
||||
|
||||
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
|
||||
|
||||
- [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
|
||||
|
||||
+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
|
||||
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
|
||||
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
|
||||
from relevant infrastructure team(s).
|
||||
@@ -62,5 +62,5 @@ You may also wish to consult a
|
||||
|
||||
## 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)
|
||||
+15
-6
@@ -1,9 +1,18 @@
|
||||
# Dev containers
|
||||
# Envbuilder
|
||||
|
||||
A Development Container is an
|
||||
[open-source specification](https://containers.dev/implementors/spec/) for
|
||||
defining containerized development environments which are also called
|
||||
development containers (dev containers).
|
||||
Envbuilder is an open-source tool that builds development environments from
|
||||
[dev container](https://containers.dev/implementors/spec/) configuration files.
|
||||
Unlike the [native Dev Containers integration](../../extending-templates/devcontainers.md),
|
||||
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
|
||||
Coder cloud development environments.
|
||||
@@ -119,4 +128,4 @@ of the Coder control plane and even run within a CI/CD pipeline.
|
||||
|
||||
## 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
|
||||
`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
|
||||
|
||||
- [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)
|
||||
|
||||
+17
-12
@@ -331,6 +331,11 @@
|
||||
"description": "Access dev containers via SSH, your IDE, or web terminal.",
|
||||
"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",
|
||||
"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"
|
||||
},
|
||||
{
|
||||
"title": "Dev containers",
|
||||
"description": "Learn about using development containers in templates",
|
||||
"path": "./admin/templates/managing-templates/devcontainers/index.md",
|
||||
"title": "Envbuilder",
|
||||
"description": "Build dev containers using Envbuilder for environments without Docker",
|
||||
"path": "./admin/templates/managing-templates/envbuilder/index.md",
|
||||
"children": [
|
||||
{
|
||||
"title": "Add a dev container template",
|
||||
"description": "How to add a dev container template to Coder",
|
||||
"path": "./admin/templates/managing-templates/devcontainers/add-devcontainer.md"
|
||||
"title": "Add an Envbuilder template",
|
||||
"description": "How to add an Envbuilder dev container template to Coder",
|
||||
"path": "./admin/templates/managing-templates/envbuilder/add-envbuilder.md"
|
||||
},
|
||||
{
|
||||
"title": "Dev container security and caching",
|
||||
"description": "Configure dev container authentication and caching",
|
||||
"path": "./admin/templates/managing-templates/devcontainers/devcontainer-security-caching.md"
|
||||
"title": "Envbuilder security and caching",
|
||||
"description": "Configure Envbuilder authentication and caching",
|
||||
"path": "./admin/templates/managing-templates/envbuilder/envbuilder-security-caching.md"
|
||||
},
|
||||
{
|
||||
"title": "Dev container releases and known issues",
|
||||
"description": "Dev container releases and known issues",
|
||||
"path": "./admin/templates/managing-templates/devcontainers/devcontainer-releases-known-issues.md"
|
||||
"title": "Envbuilder releases and known issues",
|
||||
"description": "Envbuilder releases and known issues",
|
||||
"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
|
||||
|
||||
The Dev Containers integration enables seamless creation and management of Dev
|
||||
Containers in Coder workspaces. This feature leverages the
|
||||
The Dev Containers integration 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.24.0 or later
|
||||
- Coder CLI version 2.24.0 or later
|
||||
- **Linux or macOS workspace**, Dev Containers are not supported on Windows
|
||||
- A template with:
|
||||
- Dev Containers integration enabled
|
||||
- A Docker-compatible workspace image
|
||||
- Appropriate permissions to execute Docker commands inside your workspace
|
||||
- Docker available inside your workspace
|
||||
- The `@devcontainers/cli` installed in 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.
|
||||
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](../../admin/templates/extending-templates/devcontainers.md)
|
||||
for setup details.
|
||||
|
||||
## 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
|
||||
- Seamless Dev Container startup during workspace initialization
|
||||
- Dev Container change detection and dirty state indicators
|
||||
- On-demand Dev Container recreation via rebuild button
|
||||
- Integrated IDE experience in Dev Containers with VS Code
|
||||
- Direct service access in Dev Containers
|
||||
- SSH access to Dev Containers
|
||||
- Automatic port detection for container ports
|
||||
## 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](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
|
||||
|
||||
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**
|
||||
- Changes to the `devcontainer.json` file require manual container recreation
|
||||
using the rebuild button
|
||||
- Some Dev Container features may not work as expected
|
||||
> [!NOTE]
|
||||
> If your template uses Envbuilder rather than Docker-based dev containers, see
|
||||
> the [Envbuilder documentation](../../admin/templates/managing-templates/envbuilder/index.md).
|
||||
|
||||
## Comparison with Envbuilder-based Dev Containers
|
||||
## Next steps
|
||||
|
||||
| Feature | Dev Containers Integration | 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 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
|
||||
- [Working with dev containers](./working-with-dev-containers.md) — SSH, IDE
|
||||
integration, and port forwarding
|
||||
- [Customizing dev containers](./customizing-dev-containers.md) — Custom agent
|
||||
names, apps, and display options
|
||||
- [Troubleshooting dev containers](./troubleshooting-dev-containers.md) —
|
||||
Diagnose common issues
|
||||
- [Dev Container specification](https://containers.dev/) — Advanced
|
||||
configuration options
|
||||
- [Dev Container features](https://containers.dev/features) — Enhance your
|
||||
environment with pre-built tools
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Troubleshooting dev containers
|
||||
|
||||
## Dev Container Not Starting
|
||||
## Dev container not starting
|
||||
|
||||
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-script-[script_id].log`
|
||||
|
||||
1. Verify that Docker is running in your workspace.
|
||||
1. Ensure the `devcontainer.json` file is valid.
|
||||
1. Verify Docker is available in your workspace (see below).
|
||||
1. Ensure the `devcontainer.json` file is valid JSON.
|
||||
1. Check that the repository has been cloned correctly.
|
||||
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
|
||||
coder ssh --container keen_dijkstra my-workspace
|
||||
coder ssh <workspace>.<agent>
|
||||
```
|
||||
|
||||
> [!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`.
|
||||
For example, to connect to a dev container with agent name `my-project` in
|
||||
workspace `my-workspace`:
|
||||
|
||||
## 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
|
||||
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:
|
||||
|
||||
1. Selecting "Open in VS Code Desktop" from the Coder web interface
|
||||
2. Using the Coder CLI with the container flag:
|
||||
1. Selecting **Open in VS Code Desktop** from the dev container agent in the
|
||||
Coder web interface.
|
||||
1. Using the Coder CLI:
|
||||
|
||||
```console
|
||||
coder open vscode --container keen_dijkstra my-workspace
|
||||
```
|
||||
```console
|
||||
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.
|
||||
|
||||
## 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)
|
||||
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:
|
||||
property in your `devcontainer.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
|
||||
coder port-forward my-workspace --tcp 8080,4000
|
||||
```
|
||||
## Dev container features
|
||||
|
||||
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
|
||||
You can use standard [dev container features](https://containers.dev/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`:
|
||||
For example, the
|
||||
[code-server](https://github.com/coder/devcontainer-features/blob/main/src/code-server)
|
||||
feature from the [Coder features repository](https://github.com/coder/devcontainer-features):
|
||||
|
||||
```json
|
||||
{
|
||||
"features": {
|
||||
"ghcr.io/coder/devcontainer-features/code-server:1": {
|
||||
"port": 13337,
|
||||
"host": "0.0.0.0"
|
||||
}
|
||||
},
|
||||
"appPort": ["13337:13337"]
|
||||
"features": {
|
||||
"ghcr.io/coder/devcontainer-features/code-server:1": {
|
||||
"port": 13337,
|
||||
"host": "0.0.0.0"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> [!NOTE]
|
||||
>
|
||||
> Remember to include the port in the `appPort` section to ensure proper port
|
||||
> forwarding.
|
||||
## Rebuilding dev containers
|
||||
|
||||
When you modify your `devcontainer.json`, you need to rebuild the container for
|
||||
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
|
||||
[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).
|
||||
Check out [Dev Containers integration](./devcontainers/index.md) for running
|
||||
containerized development environments in your Coder workspace.
|
||||
|
||||
<children></children>
|
||||
|
||||
Reference in New Issue
Block a user