diff --git a/docs/admin/templates/extending-templates/devcontainers.md b/docs/admin/templates/extending-templates/devcontainers.md new file mode 100644 index 0000000000000..4894a012476a1 --- /dev/null +++ b/docs/admin/templates/extending-templates/devcontainers.md @@ -0,0 +1,124 @@ +# Configure a template for dev containers + +To enable dev containers in workspaces, configure your template with the dev containers +modules and configurations outlined in this doc. + +## Install the Dev Containers CLI + +Use the +[devcontainers-cli](https://registry.coder.com/modules/devcontainers-cli) module +to ensure the `@devcontainers/cli` is installed in your workspace: + +```terraform +module "devcontainers-cli" { + count = data.coder_workspace.me.start_count + source = "dev.registry.coder.com/modules/devcontainers-cli/coder" + agent_id = coder_agent.dev.id +} +``` + +Alternatively, install the devcontainer CLI manually in your base image. + +## Configure Automatic Dev Container Startup + +The +[`coder_devcontainer`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/devcontainer) +resource automatically starts a dev container in your workspace, ensuring it's +ready when you access the workspace: + +```terraform +resource "coder_devcontainer" "my-repository" { + count = data.coder_workspace.me.start_count + agent_id = coder_agent.dev.id + workspace_folder = "/home/coder/my-repository" +} +``` + +> [!NOTE] +> +> The `workspace_folder` attribute must specify the location of the dev +> container's workspace and should point to a valid project folder containing a +> `devcontainer.json` file. + + + +> [!TIP] +> +> Consider using the [`git-clone`](https://registry.coder.com/modules/git-clone) +> module to ensure your repository is cloned into the workspace folder and ready +> for automatic startup. + +## Enable Dev Containers Integration + +To enable the dev containers integration in your workspace, you must set the +`CODER_AGENT_DEVCONTAINERS_ENABLE` environment variable to `true` in your +workspace container: + +```terraform +resource "docker_container" "workspace" { + count = data.coder_workspace.me.start_count + image = "codercom/oss-dogfood:latest" + env = [ + "CODER_AGENT_DEVCONTAINERS_ENABLE=true", + # ... Other environment variables. + ] + # ... Other container configuration. +} +``` + +This environment variable is required for the Coder agent to detect and manage +dev containers. Without it, the agent will not attempt to start or connect to +dev containers even if the `coder_devcontainer` resource is defined. + +## Complete Template Example + +Here's a simplified template example that enables the dev containers +integration: + +```terraform +terraform { + required_providers { + coder = { source = "coder/coder" } + docker = { source = "kreuzwerker/docker" } + } +} + +provider "coder" {} +data "coder_workspace" "me" {} +data "coder_workspace_owner" "me" {} + +resource "coder_agent" "dev" { + arch = "amd64" + os = "linux" + startup_script_behavior = "blocking" + startup_script = "sudo service docker start" + shutdown_script = "sudo service docker stop" + # ... +} + +module "devcontainers-cli" { + count = data.coder_workspace.me.start_count + source = "dev.registry.coder.com/modules/devcontainers-cli/coder" + agent_id = coder_agent.dev.id +} + +resource "coder_devcontainer" "my-repository" { + count = data.coder_workspace.me.start_count + agent_id = coder_agent.dev.id + workspace_folder = "/home/coder/my-repository" +} + +resource "docker_container" "workspace" { + count = data.coder_workspace.me.start_count + image = "codercom/oss-dogfood:latest" + env = [ + "CODER_AGENT_DEVCONTAINERS_ENABLE=true", + # ... Other environment variables. + ] + # ... Other container configuration. +} +``` + +## Next Steps + +- [Dev Containers Integration](../../../user-guides/devcontainers/index.md) diff --git a/docs/admin/templates/index.md b/docs/admin/templates/index.md index 85f2769e880bd..cc9a08cf26a25 100644 --- a/docs/admin/templates/index.md +++ b/docs/admin/templates/index.md @@ -50,6 +50,9 @@ needs of different teams. create and publish images for use within Coder workspaces & templates. - [Dev Container support](./managing-templates/devcontainers/index.md): Enable dev containers to allow teams to bring their own tools into Coder workspaces. +- [Early Access Dev Containers](../../user-guides/devcontainers/index.md): Try our + new direct devcontainers integration (distinct from Envbuilder-based + approach). - [Template hardening](./extending-templates/resource-persistence.md#-bulletproofing): Configure your template to prevent certain resources from being destroyed (e.g. user disks). diff --git a/docs/images/user-guides/devcontainers/devcontainer-agent-ports.png b/docs/images/user-guides/devcontainers/devcontainer-agent-ports.png new file mode 100644 index 0000000000000..1979fcd677064 Binary files /dev/null and b/docs/images/user-guides/devcontainers/devcontainer-agent-ports.png differ diff --git a/docs/images/user-guides/devcontainers/devcontainer-web-terminal.png b/docs/images/user-guides/devcontainers/devcontainer-web-terminal.png new file mode 100644 index 0000000000000..6cf570cd73f99 Binary files /dev/null and b/docs/images/user-guides/devcontainers/devcontainer-web-terminal.png differ diff --git a/docs/manifest.json b/docs/manifest.json index 8692336d089ea..23629ccc3b725 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -213,6 +213,27 @@ "path": "./user-guides/workspace-lifecycle.md", "icon_path": "./images/icons/circle-dot.svg" }, + { + "title": "Dev Containers Integration", + "description": "Run containerized development environments in your Coder workspace using the dev containers specification.", + "path": "./user-guides/devcontainers/index.md", + "icon_path": "./images/icons/container.svg", + "state": ["early access"], + "children": [ + { + "title": "Working with dev containers", + "description": "Access dev containers via SSH, your IDE, or web terminal.", + "path": "./user-guides/devcontainers/working-with-dev-containers.md", + "state": ["early access"] + }, + { + "title": "Troubleshooting dev containers", + "description": "Diagnose and resolve common issues with dev containers in your Coder workspace.", + "path": "./user-guides/devcontainers/troubleshooting-dev-containers.md", + "state": ["early access"] + } + ] + }, { "title": "Dotfiles", "description": "Personalize your environment with dotfiles", diff --git a/docs/user-guides/devcontainers/index.md b/docs/user-guides/devcontainers/index.md new file mode 100644 index 0000000000000..ed817fe853416 --- /dev/null +++ b/docs/user-guides/devcontainers/index.md @@ -0,0 +1,99 @@ +# Dev Containers Integration + +> [!NOTE] +> +> The Coder dev containers integration is an [early access](../../install/releases/feature-stages.md) feature. +> +> While functional for testing and feedback, it may change significantly before general availability. + +The dev containers integration is an early access feature that enables seamless +creation and management of dev containers in Coder workspaces. This feature +leverages the [`@devcontainers/cli`](https://github.com/devcontainers/cli) and +[Docker](https://www.docker.com) to provide a streamlined development +experience. + +This implementation is different from the existing +[Envbuilder-based dev containers](../../admin/templates/managing-templates/devcontainers/index.md) +offering. + +## Prerequisites + +- Coder version 2.22.0 or later +- Coder CLI version 2.22.0 or later +- A template with: + - Dev containers integration enabled + - A Docker-compatible workspace image +- Appropriate permissions to execute Docker commands inside your workspace + +## How It Works + +The dev containers integration utilizes the `devcontainer` command from +[`@devcontainers/cli`](https://github.com/devcontainers/cli) to manage dev +containers within your Coder workspace. +This command provides comprehensive functionality for creating, starting, and managing dev containers. + +Dev environments are configured through a standard `devcontainer.json` file, +which allows for extensive customization of your development setup. + +When a workspace with the dev containers integration starts: + +1. The workspace initializes the Docker environment. +1. The integration detects repositories with a `.devcontainer` directory or a + `devcontainer.json` file. +1. The integration builds and starts the dev container based on the + configuration. +1. Your workspace automatically detects the running dev container. + +## Features + +### Available Now + +- Automatic dev container detection from repositories +- Seamless dev container startup during workspace initialization +- Integrated IDE experience in dev containers with VS Code +- Direct service access in dev containers +- Limited SSH access to dev containers + +### Coming Soon + +- Dev container change detection +- On-demand dev container recreation +- Support for automatic port forwarding inside the container +- Full native SSH support to dev containers + +## Limitations during Early Access + +During the early access phase, the dev containers integration has the following +limitations: + +- Changes to the `devcontainer.json` file require manual container recreation +- Automatic port forwarding only works for ports specified in `appPort` +- SSH access requires using the `--container` flag +- Some devcontainer features may not work as expected + +These limitations will be addressed in future updates as the feature matures. + +## Comparison with Envbuilder-based Dev Containers + +| Feature | Dev Containers (Early Access) | Envbuilder Dev Containers | +|----------------|----------------------------------------|----------------------------------------------| +| Implementation | Direct `@devcontainers/cli` and Docker | Coder's Envbuilder | +| Target users | Individual developers | Platform teams and administrators | +| Configuration | Standard `devcontainer.json` | Terraform templates with Envbuilder | +| Management | User-controlled | Admin-controlled | +| Requirements | Docker access in workspace | Compatible with more restricted environments | + +Choose the appropriate solution based on your team's needs and infrastructure +constraints. For additional details on Envbuilder's dev container support, see +the +[Envbuilder devcontainer spec support documentation](https://github.com/coder/envbuilder/blob/main/docs/devcontainer-spec-support.md). + +## Next Steps + +- Explore the [dev container specification](https://containers.dev/) to learn + more about advanced configuration options +- Read about [dev container features](https://containers.dev/features) to + enhance your development environment +- Check the + [VS Code dev containers documentation](https://code.visualstudio.com/docs/devcontainers/containers) + for IDE-specific features diff --git a/docs/user-guides/devcontainers/troubleshooting-dev-containers.md b/docs/user-guides/devcontainers/troubleshooting-dev-containers.md new file mode 100644 index 0000000000000..ca27516a81cc0 --- /dev/null +++ b/docs/user-guides/devcontainers/troubleshooting-dev-containers.md @@ -0,0 +1,16 @@ +# Troubleshooting dev containers + +## Dev Container Not Starting + +If your dev container fails to start: + +1. Check the agent logs for error messages: + + - `/tmp/coder-agent.log` + - `/tmp/coder-startup-script.log` + - `/tmp/coder-script-[script_id].log` + +1. Verify that Docker is running in your workspace. +1. Ensure the `devcontainer.json` file is valid. +1. Check that the repository has been cloned correctly. +1. Verify the resource limits in your workspace are sufficient. diff --git a/docs/user-guides/devcontainers/working-with-dev-containers.md b/docs/user-guides/devcontainers/working-with-dev-containers.md new file mode 100644 index 0000000000000..a4257f91d420e --- /dev/null +++ b/docs/user-guides/devcontainers/working-with-dev-containers.md @@ -0,0 +1,97 @@ +# Working with Dev Containers + +The dev container integration appears in your Coder dashboard, providing a +visual representation of the running environment: + +![Dev container integration in Coder dashboard](../../images/user-guides/devcontainers/devcontainer-agent-ports.png) + +## SSH Access + +You can SSH into your dev container directly using the Coder CLI: + +```console +coder ssh --container keen_dijkstra my-workspace +``` + +> [!NOTE] +> +> SSH access is not yet compatible with the `coder config-ssh` command for use +> with OpenSSH. You would need to manually modify your SSH config to include the +> `--container` flag in the `ProxyCommand`. + +## Web Terminal Access + +Once your workspace and dev container are running, you can use the web terminal +in the Coder interface to execute commands directly inside the dev container. + +![Coder web terminal with dev container](../../images/user-guides/devcontainers/devcontainer-web-terminal.png) + +## IDE Integration (VS Code) + +You can open your dev container directly in VS Code by: + +1. Selecting "Open in VS Code Desktop" from the Coder web interface +2. Using the Coder CLI with the container flag: + +```console +coder open vscode --container keen_dijkstra my-workspace +``` + +While optimized for VS Code, other IDEs with dev containers support may also +work. + +## Port Forwarding + +During the early access phase, port forwarding is limited to ports defined via +[`appPort`](https://containers.dev/implementors/json_reference/#image-specific) +in your `devcontainer.json` file. + +> [!NOTE] +> +> Support for automatic port forwarding via the `forwardPorts` property in +> `devcontainer.json` is planned for a future release. + +For example, with this `devcontainer.json` configuration: + +```json +{ + "appPort": ["8080:8080", "4000:3000"] +} +``` + +You can forward these ports to your local machine using: + +```console +coder port-forward my-workspace --tcp 8080,4000 +``` + +This forwards port 8080 (local) -> 8080 (agent) -> 8080 (dev container) and port +4000 (local) -> 4000 (agent) -> 3000 (dev container). + +## Dev Container Features + +You can use standard dev container features in your `devcontainer.json` file. +Coder also maintains a +[repository of features](https://github.com/coder/devcontainer-features) to +enhance your development experience. + +Currently available features include [code-server](https://github.com/coder/devcontainer-features/blob/main/src/code-server). + +To use the code-server feature, add the following to your `devcontainer.json`: + +```json +{ + "features": { + "ghcr.io/coder/devcontainer-features/code-server:1": { + "port": 13337, + "host": "0.0.0.0" + } + }, + "appPort": ["13337:13337"] +} +``` + +> [!NOTE] +> +> Remember to include the port in the `appPort` section to ensure proper port +> forwarding. diff --git a/docs/user-guides/index.md b/docs/user-guides/index.md index b756c7b0e1202..92040b4bebd1a 100644 --- a/docs/user-guides/index.md +++ b/docs/user-guides/index.md @@ -7,4 +7,7 @@ These are intended for end-user flows only. If you are an administrator, please refer to our docs on configuring [templates](../admin/index.md) or the [control plane](../admin/index.md). +Check out our [early access features](../install/releases/feature-stages.md) for upcoming +functionality, including [Dev Containers integration](../user-guides/devcontainers/index.md). +