docs: rewrite dev containers documentation for GA #21080
Conversation
e805ebb to
78fb565
Compare
78fb565 to
237fe6b
Compare
2a7e830 to
7b3109e
Compare
This comment was marked as outdated.
This comment was marked as outdated.
The previous documentation had inaccuracies: SSH examples used the deprecated `--container` flag instead of the agent-based pattern (`coder ssh workspace.agent`), port forwarding focused on `appPort` when native forwarding to sub-agents is the primary method, and prerequisites implied users needed to "enable" dev containers when it is on by default. Renamed admin docs folder from `devcontainers/` to `envbuilder/` since it documents Envbuilder specifically, not native dev containers. Added notes pointing to native dev containers as the recommended approach for most use cases. Also fixes module registry URLs that pointed to dev.registry instead of registry.coder.com. Refs #18907
Documents Coder-specific `devcontainer.json` customizations including
custom agent naming, display apps configuration, custom apps with
health checks, and variable interpolation using `${localEnv:...}`,
Coder variables, and `$SESSION_TOKEN`.
Centralizes the customization documentation in the user guide where users are more likely to find it. The admin docs now link to the user guide instead of duplicating content.
170ac50 to
84572dc
Compare
- Add third devcontainer.json location for monorepos, link to spec - Clarify hostname suffix is a deployment setting - Tighten project discovery section, clarify autostart behavior
0141028 to
eacb146
Compare
- Explain discovery scans working directory for Git repos - Cross-reference standard devcontainer.json locations instead of repeating - Clarify 'How it works' steps depend on auto-start configuration - Add link to admin docs for autostart env var - Fix 'Currently available' phrasing to avoid staleness
0b2da3f to
d052976
Compare
The docker-devcontainer template uses the Dev Containers integration, not Envbuilder. The AWS and Kubernetes templates use Envbuilder. Also adds example template link to the Dev Containers admin doc.
mtojek
left a comment
There was a problem hiding this comment.
I didn't check the correctness of the commands, rather focused on features and step descriptions.
Remove numbered prefixes from Getting Started headers and fix config-ssh section to correctly describe the wildcard host entry instead of multiple entries.
mtojek
left a comment
There was a problem hiding this comment.
Nothing blocking, this will be a great improvement 👍
📚 Documentation Check✨ No Changes NeededThis PR is a comprehensive documentation rewrite that includes all necessary updates: What was updated:
Why no additional changes needed: This comment was generated by an AI Agent through Coder Tasks |
david-fraley
left a comment
There was a problem hiding this comment.
Can we include some callout that modules in our terraform registry are not currently able to be used by the sub agents? I don't want to dig and hint at all of these issues the customer is calling out, but being more clear about not being able to run agent modules would be good imo
https://codercom.slack.com/archives/C06UK9XP3F0/p1763750997864699
Good to go otherwise. I'd be ok with that as a follow up later; I'd rather see the changes get in sooner so
|
@david-fraley adressed in |
This PR rewrites the dev containers documentation for GA readiness.
The previous documentation had inaccuracies: SSH examples used the deprecated
--containerflag instead of the agent-based pattern (coder ssh workspace.agent), port forwarding focused onappPortwhen native forwarding to sub-agents is the primary method, and prerequisites implied users needed to "enable" dev containers when it is on by default.Renamed admin docs folder from
devcontainers/toenvbuilder/since it documents Envbuilder specifically, not native dev containers. Added notes pointing to native dev containers as the recommended approach for most use cases, with Envbuilder as an alternative for Docker-less environments. Also fixes module registry URLs that pointed todev.registryinstead ofregistry.coder.com.Adds a new customization guide documenting Coder-specific
devcontainer.jsonoptions including custom agent naming, display apps configuration, custom apps with health checks, and variable interpolation using${localEnv:...}, Coder variables, and$SESSION_TOKEN.Moves customization content from the admin docs to the user guide where users are more likely to find it. The admin docs now link to the user guide instead of duplicating content.
Improves accuracy around dev container discovery: adds the third standard devcontainer.json location for monorepos (linked to the spec), explains that discovery scans the working directory for Git repos, and clarifies that autostart behavior depends on configuration. Also fixes cross-references between docs to avoid duplication.
Corrects template descriptions: the docker-devcontainer template uses the native Dev Containers integration, while AWS and Kubernetes templates use Envbuilder. Adds example template link to the admin docs.
Refs #18907