docs: add comprehensive dev containers documentation with examples by EdwardAngert · Pull Request #18582 · coder/coder

EdwardAngert · 2025-06-25T16:16:25Z

EdwardAngert · 2025-07-01T18:10:24Z

moved to "ready for review" while I tech test the remaining examples

DanielleMaywood

I'm slightly concerned at how many things were subtly wrong and that I haven't caught them all.

DanielleMaywood · 2025-07-02T08:43:45Z

docs/user-guides/devcontainers/working-with-dev-containers.md

 ```console
-coder ssh --container keen_dijkstra my-workspace
+coder ssh --container my-container-name my-workspace
 ```

+Remember to replace:
+
+- `my-container-name` with the dev container agent name.
+- `my-workspace` with your workspace's name.
+
 > [!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`.
+> Starting with Coder v2.24.0, `coder config-ssh` works with dev containers.
+> If you’re using an older Coder version, add `--container <name>` to the
+> `ProxyCommand` entry in your SSH config.


I feel like this section could be worded better. It gives priority to the old pattern using a hidden CLI flag that was only made available during early access.

I believe we should instead focus entirely on how to do it with the current agent-based approach.

agreed

I think this whole doc needs a review, but I'm leaning towards doing that as a separate PR

I still feel like this needs addressing.

docs/user-guides/devcontainers/working-with-dev-containers.md

docs/user-guides/devcontainers/troubleshooting-dev-containers.md

docs/admin/templates/extending-templates/devcontainers.md

docs/admin/templates/extending-templates/dev-containers-envbuilder.md

docs/admin/templates/extending-templates/advanced-dev-containers.md

Co-authored-by: Danielle Maywood <danielle@themaywoods.com>

docs/admin/templates/extending-templates/devcontainers.md

DanielleMaywood

Sorry for another spam of review comments 😅 I still feel like there is some outdated/confusing/incorrect information present.

DanielleMaywood · 2025-07-09T08:48:05Z

docs/admin/templates/extending-templates/dev-containers-envbuilder.md

+| Build engine                             | `@devcontainers/cli` + Docker            | Envbuilder transforms the workspace image |
+| Runs separate Docker container           | Yes (parent workspace + child container) | No (modifies the parent container)        |
+| Multiple Dev Containers per workspace    | Yes                                      | No                                        |
+| Rebuild when `devcontainer.json` changes | Yes (auto-prompt)                        | Limited (requires full workspace rebuild) |


@mafredri what do we think on the wording of auto-prompt here? We don't technically prompt the user they can rebuild, the UI just indicates the dev container is outdated.

I agree, it feels a bit off. Perhaps "(user initiated, change detection)".

DanielleMaywood · 2025-07-09T08:49:28Z

docs/admin/templates/extending-templates/dev-containers-envbuilder.md

+     source   = "dev.registry.coder.com/modules/devcontainers-cli/coder"
+     agent_id = coder_agent.main.id
+   }
+   resource "coder_devcontainer" "project" { # `project` in this example is how users will connect to the dev container: `ssh://project.<workspace>.me.coder`


This looks like project is the name because of the terraform resource name, but I think we should make it more clear it is because of the workspace folder path.

I agree, the comment could be removed. (FYI for Edward, the resource name did play a role in the past, but not in the code that was released in GA.)

DanielleMaywood · 2025-07-09T08:55:42Z

docs/admin/templates/extending-templates/devcontainers.md

 ```

-Alternatively, install the devcontainer CLI manually in your base image.
+Alternatively, install `devcontainer/cli` manually in your base image:


@devcontainers/cli otherwise this looks a little confusing

DanielleMaywood · 2025-07-09T08:56:04Z

docs/admin/templates/extending-templates/devcontainers.md


 ```terraform
-resource "coder_devcontainer" "my-repository" {
+resource "coder_devcontainer" "project" { # `project` in this example is how users will connect to the dev container: `ssh://project.<workspace>.me.coder`


same as earlier suggestions

DanielleMaywood · 2025-07-09T08:57:25Z

docs/admin/templates/extending-templates/devcontainers.md

+## Clone the Repository

-<!-- nolint:MD028/no-blanks-blockquote -->
+This step is optional, but it ensures that the project is present before the dev container starts.


The way this is worded feels a little confusing as it makes me believe I can just skip this step?

DanielleMaywood · 2025-07-09T09:03:21Z

docs/user-guides/devcontainers/index.md

- Integrated IDE experience in dev containers with VS Code
- Direct service access in dev containers
- Limited SSH access to dev containers
+- Automatic discovery of `.devcontainer` configs.


Same as above

DanielleMaywood · 2025-07-09T09:03:53Z

docs/user-guides/devcontainers/troubleshooting-dev-containers.md

+## Rebuild prompt does not appear
+
+1. Confirm that you saved `devcontainer.json` in the correct repo path detected by Coder.
+1. Check agent logs for `devcontainer build` errors.


Not sure what devcontainer build is referring to here.

DanielleMaywood · 2025-07-09T09:04:29Z

docs/user-guides/devcontainers/working-with-dev-containers.md

 ```console
-coder ssh --container keen_dijkstra my-workspace
+coder ssh --container my-container-name my-workspace
 ```

+Remember to replace:
+
+- `my-container-name` with the dev container agent name.
+- `my-workspace` with your workspace's name.
+
 > [!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`.
+> Starting with Coder v2.24.0, `coder config-ssh` works with dev containers.
+> If you’re using an older Coder version, add `--container <name>` to the
+> `ProxyCommand` entry in your SSH config.


I still feel like this needs addressing.

DanielleMaywood · 2025-07-09T09:04:54Z

docs/user-guides/devcontainers/working-with-dev-containers.md


 ```console
-coder open vscode --container keen_dijkstra my-workspace
+coder open vscode --container my-container-name my-workspace


spotted here as well.

DanielleMaywood · 2025-07-09T09:05:11Z

docs/user-guides/devcontainers/working-with-dev-containers.md

-```
-
-You can forward these ports to your local machine using:
+Coder automatically forwards any port declared in `appPort` or `forwardPorts`.


I'm not sure this is correct (cc @mafredri)

mafredri

I feel there may be too much feedback here and issues/suggestions (especially those that need to be fixed in multiple places) will easily be missed. Not sure how we should tackle this problem but I do see a few issues still present from previous feedback rounds too and with this many changes in one PR, it's also going to be very hard to verify that all the necessary changes are made.

mafredri · 2025-07-09T10:48:20Z

docs/admin/templates/extending-templates/advanced-dev-containers.md

+
+Run independent dev containers in the same workspace so each component appears as its own agent.
+
+In this example, there are two: `frontend` and `backend`:


We should mention here that the names come from the project name (i.e. folder they are cloned into).

mafredri · 2025-07-09T10:49:19Z

docs/admin/templates/extending-templates/advanced-dev-containers.md

+
+  agent_id = coder_agent.main.id
+  url      = "https://github.com/your-org/frontend.git"
+  base_dir = "/home/coder/frontend"


This will result in /home/coder/frontend/frontend, we should drop the base_dir for simplicity since it defaults to $HOME.

mafredri · 2025-07-09T10:51:15Z

docs/admin/templates/extending-templates/advanced-dev-containers.md

+resource "coder_devcontainer" "backend" {
+  count            = data.coder_workspace.me.start_count
+  agent_id         = coder_agent.main.id
+  workspace_folder = "/home/coder/backend/${module.git-clone-backend[0].folder_name}"


Suggested change

workspace_folder = "/home/coder/backend/${module.git-clone-backend[0].folder_name}"

workspace_folder = module.git-clone-backend[0].repo_dir

Simplification.

mafredri · 2025-07-09T10:53:51Z

docs/admin/templates/extending-templates/advanced-dev-containers.md

+```
+
+Each dev container appears as a separate agent, so developers can connect to any
+component in the workspace.


I don't have a better suggestion, but "component" feels a bit off for me and it's feels like we're calling dev containers both dev containers and components.

mafredri · 2025-07-09T11:00:04Z

docs/admin/templates/extending-templates/advanced-dev-containers.md

+data "coder_parameter" "enable_frontend" {
+  type        = "bool"
+  name        = "Enable frontend container"


Suggested change

data "coder_parameter" "enable_frontend" {

type = "bool"

name = "Enable frontend container"

data "coder_parameter" "autostart_frontend" {

type = "bool"

name = "Autostart frontend container"

I suggest alternative terminology here so that we don't accidentally suggest that the exclusion of resource "coder_devcontainer" "frontend" can prevent the devcontainer from showing up in the UI if started manually.

mafredri · 2025-07-09T12:06:43Z

docs/admin/templates/extending-templates/devcontainers.md

+### Slow builds
+
+- Allocate more CPU/RAM.
+- Use image caching or pre-build common images.


A local (Docker) registry mirror can also help.

Also, we should be cautious with the term pre-build here. What are we referring to? Prebuilt Docker image? Prebuilds in Coder? devcontainer build?

mafredri · 2025-07-09T12:08:52Z

docs/user-guides/devcontainers/index.md

-1. The integration builds and starts the dev container based on the
-   configuration.
+1. The integration detects repositories with a `.devcontainer` directory or a `devcontainer.json` file.
+1. The integration builds (or rebuilds) and starts the dev container based on the configuration.


Suggested change

1. The integration builds (or rebuilds) and starts the dev container based on the configuration.

1. The integration starts the dev container based on the configuration.

"Builds" may add a bit of confusion here. Also, please specify what "configuration" means here. I'm assuming terraform but below "configuration" refers to devcontainer.json.

mafredri · 2025-07-09T12:11:14Z

docs/user-guides/devcontainers/index.md

- Integrated IDE experience in dev containers with VS Code
- Direct service access in dev containers
- Limited SSH access to dev containers
+- Automatic discovery of `.devcontainer` configs.


Nit: Why reword this and mention .devcontainer which is the folder and is not required, the main party is devcontainer.json.

Also the statement is kind of not true (requires that bit in terraform or manually starting the devcontainer), but we might want to go here some day (see coder/internal#711)

mafredri · 2025-07-09T12:14:40Z

docs/user-guides/devcontainers/troubleshooting-dev-containers.md

+## Rebuild prompt does not appear
+
+1. Confirm that you saved `devcontainer.json` in the correct repo path detected by Coder.
+1. Check agent logs for `devcontainer build` errors.


We don't ever explicitly run devcontainer build currently. I don't think we should highlight this command.

mafredri · 2025-07-09T12:16:01Z

docs/user-guides/devcontainers/working-with-dev-containers.md

-```
-
-You can forward these ports to your local machine using:
+Coder automatically forwards any port declared in `appPort` or `forwardPorts`.


Weren't we supposed to fix this already?

EdwardAngert · 2025-07-09T14:58:00Z

@mafredri

I feel there may be too much feedback here and issues/suggestions (especially those that need to be fixed in multiple places) will easily be missed. Not sure how we should tackle this problem but I do see a few issues still present from previous feedback rounds too and with this many changes in one PR, it's also going to be very hard to verify that all the necessary changes are made.

I can incorporate all the feedback and suggestions from @DanielleMaywood's and your review, but I think we're butting up against my limited dev containers knowledge and experience, and might need to approach this differently.

Does it make more sense to you both if I keep making changes here, or do you think we're at the point where it makes more sense to open a new PR that's less of an overhaul of the existing doc to add the new functionality and examples there?

EdwardAngert · 2025-07-14T13:38:35Z

changing approach - replacement PR to follow

EdwardAngert added 3 commits June 23, 2025 17:40

remove ea feature status

718e6f9

add advanced dev container doc

ba7a36c

update devcontainers

ef8a4ea

EdwardAngert self-assigned this Jun 25, 2025

EdwardAngert added the docs Area: coder.com/docs label Jun 25, 2025

EdwardAngert added 9 commits June 25, 2025 19:41

new workspace screenshot

f4db3da

consistent and working examples

df07196

edits; prep advanced doc

18998b7

Merge branch 'main' into dev-container-ga

ddc5893

advanced features

048cf5b

better examples

5dc41a5

init user-facing update

be23e85

remove coder_agent_devcontainers_enable requirement

ec77a25

update features; add personal devcontainer file

06d714c

EdwardAngert force-pushed the dev-container-ga branch from 3506fa2 to 06d714c Compare June 27, 2025 15:42

EdwardAngert added 8 commits June 27, 2025 16:02

update troubleshooting

8f392c0

add comparison doc; crosslink

2fe5291

shorten title

33d3eed

clarify envbuilder doc titles

747822e

update envbuilder doc with dev container integration consideration

d9f818c

update envbuilder add-devcontainer with dev container integration links

c10eb7e

envbuilder tweaks

3f8970e

link fix

0d0a9ba

EdwardAngert changed the title ~~docs: (draft) add comprehensive dev containers documentation with examples~~ docs: add comprehensive dev containers documentation with examples Jun 27, 2025

EdwardAngert added 5 commits June 27, 2025 17:20

tweak to devcontainer.local note

88e7c0f

ap title case

8f5e613

leftover ea language

e83d564

update ssh note and example

03c60bf

update example template

cfcef3c

EdwardAngert force-pushed the dev-container-ga branch from cafacc7 to cfcef3c Compare June 27, 2025 20:23

EdwardAngert added 2 commits July 1, 2025 16:04

edits from code review

d3fd3b8

remove full examples; adjustments from review

6ee9fd4

EdwardAngert marked this pull request as ready for review July 1, 2025 18:08

Merge branch 'main' into dev-container-ga

7b2ba10

DanielleMaywood requested changes Jul 2, 2025

View reviewed changes

EdwardAngert and others added 6 commits July 2, 2025 13:00

Apply suggestions from code review

30372fc

Co-authored-by: Danielle Maywood <danielle@themaywoods.com>

edit dev-containers-envbuilder

f7c5272

edit devcontainers doc

9eb367d

changes from code review

abd91a2

edits

032edc3

Merge branch 'main' into dev-container-ga

1804190

EdwardAngert commented Jul 2, 2025

View reviewed changes

docs/admin/templates/extending-templates/devcontainers.md Show resolved Hide resolved

EdwardAngert and others added 6 commits July 3, 2025 20:17

tested configs; remove untested

67702ae

Merge branch 'main' into dev-container-ga

e8cff18

Merge branch 'main' into dev-container-ga

1af39a8

consistency and words

11891da

don't encourage envbuilder

0b5cd24

example edit

6485b8f

EdwardAngert requested review from DanielleMaywood, bpmct and mafredri July 9, 2025 05:37

Merge branch 'main' into dev-container-ga

f1df910

DanielleMaywood requested changes Jul 9, 2025

View reviewed changes

mafredri reviewed Jul 9, 2025

View reviewed changes

EdwardAngert closed this Jul 14, 2025

github-actions bot locked and limited conversation to collaborators Jul 14, 2025

github-actions bot deleted the dev-container-ga branch January 10, 2026 00:08


		Run independent dev containers in the same workspace so each component appears as its own agent.

		In this example, there are two: `frontend` and `backend`:

	workspace_folder = "/home/coder/backend/${module.git-clone-backend[0].folder_name}"
	workspace_folder = module.git-clone-backend[0].repo_dir

	1. The integration builds (or rebuilds) and starts the dev container based on the configuration.
	1. The integration starts the dev container based on the configuration.

Conversation

EdwardAngert commented Jun 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

EdwardAngert commented Jul 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

DanielleMaywood left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

DanielleMaywood left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mafredri Jul 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mafredri left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

EdwardAngert commented Jul 9, 2025

Uh oh!

EdwardAngert commented Jun 25, 2025 •

edited

Loading

EdwardAngert commented Jul 1, 2025 •

edited

Loading

mafredri Jul 9, 2025 •

edited

Loading