docs: add comprehensive dev containers documentation with examples #18582

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

EdwardAngert · 2025-06-27T20:24:34Z

I had some trouble getting the example working with my barebones deployment, and I think it's because of the docker-in-docker requirement

I'm going to have to come back for some more testing

bpmct · 2025-06-27T21:30:57Z

docs/admin/templates/managing-templates/devcontainers/index.md

@@ -1,4 +1,4 @@
-# Dev containers
+# Envbuilder Dev Containers


Why does it lead with Envbuilder?

we need to decide what to do with this set of docs - I re-titled them and made some quick changes to sections to be envbuilder-specific
we aren't removing envbuilder with this PR, so I want to strip these down as much as possible, but don't want to remove and redirect the docs just yet.

Should we add some sort of notice to this page that users should pick the new devcontainer approach instead of envbuilder?

docs/admin/templates/managing-templates/devcontainers/index.md

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

mafredri

I didn't quite get through everything, but here's some initial feedback.

mafredri · 2025-06-30T07:38:21Z

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

+    1. In the `devcontainers-cli` module block, add:
+
+       ```terraform
+       depends_on       = [module.nodejs]


AFAIK this is not a feature supported by Coder (at least yet), see #10352, #11264.

Essentially both modules will install at the same time and devcontainers-cli will likely fail.

I didn't have any success with depends_on in my testing either

my goal was to ship this as a doc folks can use as a standalone, but that's going to have to come with a future iteration, so I'm going to remove the <details> expand

mafredri · 2025-06-30T07:41:48Z

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


 ```terraform
-resource "coder_devcontainer" "my-repository" {
+resource "coder_devcontainer" "project" {


I'm glad you used the same name (project) here and in the workspace folder. We should potentially call it out that this name is how users will be connecting to the devcontainer (e.g. ssh://project.<workspace>.me.coder).

I'm trying to standardize the examples and configs we use so that someone using a combination of docs can have a linear/consistent experience. At some point, I think it'd be good to have a heavily commented set of examples that we can use both for teaching and for a docs style guide.

For now, I just added a comment on this line

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

mafredri · 2025-06-30T08:23:06Z

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

+  base_dir = "/home/coder/project"
+}
+
+resource "coder_devcontainer" "project" {


It's unfortunate folder_name can't be used here. 😔 I'm really of two-minds using this for the sub-agent name when present but it is what it is.

We support devcontainer.json customization to change the name on a per-project basis.

we don't really have that documented, but I think we should def add it in the next iteration

adding: it would be great as part of or in addition to the Agent naming section

mafredri · 2025-06-30T08:38:54Z

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

+
+### Disable dev containers integration
+
+To disable the dev containers integration in your workspace, add the `CODER_AGENT_DEVCONTAINERS_ENABLE` environment variable to your existing `coder_agent` block:


This is incorrect, the env must be set before the agent is started, i.e. on the Docker container. We could potentially implement this behavior but it's currently not supported (/cc @DanielleMaywood thoughts?)

changed to

To disable the dev containers integration in your workspace, set the `CODER_AGENT_DEVCONTAINERS_ENABLE= "false"` environment variable.

docs/user-guides/devcontainers/index.md

Co-authored-by: Mathias Fredriksson <[email protected]>

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.

DanielleMaywood · 2025-07-02T08:46:50Z

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

+Coder automatically forwards any port declared in `appPort`, `forwardPorts`,
+or exposed by `docker-compose.yml`.


Is this correct @mafredri?

Nope, called this out in another section I believe.

DanielleMaywood · 2025-07-02T08:47:26Z

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

+
+## Rebuild prompt does not appear
+
+1. Confirm that you saved `devcontainer.json` (or changes to `devcontainer.local.json`) in the correct repo path detected by Coder.


Suggested change

1. Confirm that you saved `devcontainer.json` (or changes to `devcontainer.local.json`) in the correct repo path detected by Coder.

1. Confirm that you saved `devcontainer.json` in the correct repo path detected by Coder.

DanielleMaywood · 2025-07-02T08:49:11Z

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

+## Rebuild prompt does not appear
+
+1. Confirm that you saved `devcontainer.json` (or changes to `devcontainer.local.json`) in the correct repo path detected by Coder.
+1. Run `coder devcontainer rebuild` manually.


This command does not exist.

DanielleMaywood · 2025-07-02T08:52:11Z

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

@@ -9,8 +12,22 @@ If your dev container fails to start:
   - `/tmp/coder-agent.log`
   - `/tmp/coder-startup-script.log`
   - `/tmp/coder-script-[script_id].log`
+   - `/tmp/devcontainer-build.log`


This doesn't exist.

DanielleMaywood · 2025-07-02T08:57:55Z

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

+1. `customizations.coder.name` in `devcontainer.json`
+1. Resource name used in terraform (`resource "coder_devcontainer" "name"`)
+1. Project directory name (name of folder containing `devcontainer.json` or `.devcontainer` folder)
+1. If project directory name is already taken, the name is expanded to include the parent folder (`/home/coder/some/project` -> `project` (taken) -> `some-project`)


@mafredri did that PR make it into the release? If so, this section is outdated with regards to naming using the terraform resource.

Yes, we now ignore the terraform resource name so we can remove this line:

1. Resource name used in terraform (`resource "coder_devcontainer" "name"`)

DanielleMaywood · 2025-07-02T09:00:01Z

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

+
+Choose the new integration if:
+
+- Your workspace image can run Docker (DinD, Sysbox, or a mounted Docker socket).


I'm not sure we should suggest a mounted Docker socket as an approach. It will cause issues with filesystems (cc @mafredri)

DanielleMaywood · 2025-07-02T09:00:17Z

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

+Envbuilder remains a solid choice when:
+
+- Docker isn’t available or allowed inside the workspace image.
+- The platform team wants tight control over container contents via Terraform.


I'm not sure this point makes sense

DanielleMaywood · 2025-07-02T09:00:39Z

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

+
+- Docker isn’t available or allowed inside the workspace image.
+- The platform team wants tight control over container contents via Terraform.
+- A single layered environment is sufficient (no need for separate sub-containers).


Neither does this

DanielleMaywood · 2025-07-02T09:01:52Z

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

+## Troubleshooting
+
+1. Run `docker ps` inside the workspace to ensure Docker is available.
+1. Check `/tmp/startup.log` for agent logs.


Suggested change

1. Check `/tmp/startup.log` for agent logs.

1. Check `/tmp/coder-agent.log` for agent logs.

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

bpmct reviewed Jun 27, 2025

View reviewed changes

docs/admin/templates/managing-templates/devcontainers/index.md Outdated Show resolved Hide resolved

bpmct reviewed Jun 27, 2025

View reviewed changes

docs/admin/templates/extending-templates/dev-containers-envbuilder.md Outdated Show resolved Hide resolved

mafredri reviewed Jun 30, 2025

View reviewed changes

EdwardAngert and others added 4 commits July 1, 2025 11:25

Apply suggestions from code review

acdbe4d

Co-authored-by: Mathias Fredriksson <[email protected]>

Merge branch 'main' into dev-container-ga

1deae60

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


		### Disable dev containers integration

		To disable the dev containers integration in your workspace, add the `CODER_AGENT_DEVCONTAINERS_ENABLE` environment variable to your existing `coder_agent` block:

		Coder automatically forwards any port declared in `appPort`, `forwardPorts`,
		or exposed by `docker-compose.yml`.


		## Rebuild prompt does not appear

		1. Confirm that you saved `devcontainer.json` (or changes to `devcontainer.local.json`) in the correct repo path detected by Coder.


		Choose the new integration if:

		- Your workspace image can run Docker (DinD, Sysbox, or a mounted Docker socket).

	1. Check `/tmp/startup.log` for agent logs.
	1. Check `/tmp/coder-agent.log` for agent logs.

docs: add comprehensive dev containers documentation with examples #18582

Are you sure you want to change the base?

docs: add comprehensive dev containers documentation with examples #18582

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 Jun 27, 2025

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!

mafredri left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

EdwardAngert Jul 1, 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!

Uh oh!

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!

Uh oh!

Uh oh!

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!

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!

Uh oh!

EdwardAngert commented Jun 25, 2025 •

edited

Loading

EdwardAngert Jul 1, 2025 •

edited

Loading

EdwardAngert commented Jul 1, 2025 •

edited

Loading