Skip to content

Commit 237fe6b

Browse files
mafredrimafredri
committed
docs(user-guides/devcontainers): move customizations from admin to user guide
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.
1 parent 613d4dd commit 237fe6b

File tree

2 files changed

+63
-65
lines changed

2 files changed

+63
-65
lines changed

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

Lines changed: 9 additions & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -142,73 +142,17 @@ always auto-start regardless of this setting.
142142

143143
## Per-Container Customizations
144144

145-
Individual Dev Containers can be customized using the `customizations.coder` block
146-
in your `devcontainer.json` file. These customizations allow you to control
147-
container-specific behavior without modifying your template.
148-
149-
### Ignore Specific Containers
150-
151-
Use the `ignore` option to hide a Dev Container from Coder completely:
152-
153-
```json
154-
{
155-
"name": "My Dev Container",
156-
"image": "mcr.microsoft.com/devcontainers/base:ubuntu",
157-
"customizations": {
158-
"coder": {
159-
"ignore": true
160-
}
161-
}
162-
}
163-
```
164-
165-
When `ignore` is set to `true`:
166-
167-
- The Dev Container won't appear in the Coder UI
168-
- Coder won't manage or monitor the container
169-
170-
This is useful when you have Dev Containers in your repository that you don't
171-
want Coder to manage.
172-
173-
### Per-Container Auto-Start
174-
175-
Control whether individual Dev Containers should auto-start using the
176-
`autoStart` option:
177-
178-
```json
179-
{
180-
"name": "My Dev Container",
181-
"image": "mcr.microsoft.com/devcontainers/base:ubuntu",
182-
"customizations": {
183-
"coder": {
184-
"autoStart": true
185-
}
186-
}
187-
}
188-
```
189-
190-
**Important**: The `autoStart` option only applies when global auto-start is
191-
enabled via `CODER_AGENT_DEVCONTAINERS_DISCOVERY_AUTOSTART_ENABLE=true`. If
192-
the global setting is disabled, containers won't auto-start regardless of this
193-
setting.
194-
195-
When `autoStart` is set to `true`:
196-
197-
- The Dev Container automatically builds and starts during workspace
198-
initialization
199-
- Works on a per-container basis (you can enable it for some containers but not
200-
others)
201-
202-
When `autoStart` is set to `false` or omitted:
203-
204-
- The Dev Container is discovered and shown in the UI
205-
- Users must manually start it via the UI
145+
Developers can customize individual dev containers using the `customizations.coder`
146+
block in their `devcontainer.json` file. Available options include:
206147

207-
### Additional customizations
148+
- `ignore` — Hide a dev container from Coder completely
149+
- `autoStart` — Control whether the container starts automatically (requires
150+
`CODER_AGENT_DEVCONTAINERS_DISCOVERY_AUTOSTART_ENABLE` to be enabled)
151+
- `name` — Set a custom agent name
152+
- `displayApps` — Control which built-in apps appear
153+
- `apps` — Define custom applications
208154

209-
Developers can further customize their dev containers with custom agent names,
210-
display apps, custom applications, and more. See
211-
[Customizing dev containers](../../../user-guides/devcontainers/customizing-dev-containers.md)
155+
See [Customizing dev containers](../../../user-guides/devcontainers/customizing-dev-containers.md)
212156
for the full reference.
213157

214158
## Complete Template Example

‎docs/user-guides/devcontainers/customizing-dev-containers.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,60 @@ Coder supports custom configuration in your `devcontainer.json` file through the
44
`customizations.coder` block. These options let you control how Coder interacts
55
with your dev container without requiring template changes.
66

7+
## Ignore a dev container
8+
9+
Use the `ignore` option to hide a dev container from Coder completely:
10+
11+
```json
12+
{
13+
"name": "My Dev Container",
14+
"image": "mcr.microsoft.com/devcontainers/base:ubuntu",
15+
"customizations": {
16+
"coder": {
17+
"ignore": true
18+
}
19+
}
20+
}
21+
```
22+
23+
When `ignore` is set to `true`:
24+
25+
- The dev container won't appear in the Coder UI
26+
- Coder won't manage or monitor the container
27+
28+
This is useful for dev containers in your repository that you don't want Coder
29+
to manage.
30+
31+
## Auto-start
32+
33+
Control whether your dev container should auto-start using the `autoStart`
34+
option:
35+
36+
```json
37+
{
38+
"name": "My Dev Container",
39+
"image": "mcr.microsoft.com/devcontainers/base:ubuntu",
40+
"customizations": {
41+
"coder": {
42+
"autoStart": true
43+
}
44+
}
45+
}
46+
```
47+
48+
When `autoStart` is set to `true`, the dev container automatically builds and
49+
starts during workspace initialization.
50+
51+
When `autoStart` is set to `false` or omitted, the dev container is discovered
52+
and shown in the UI, but users must manually start it.
53+
54+
> [!NOTE]
55+
>
56+
> The `autoStart` option only takes effect when your template administrator has
57+
> enabled `CODER_AGENT_DEVCONTAINERS_DISCOVERY_AUTOSTART_ENABLE`. If this
58+
> setting is disabled at the template level, containers won't auto-start
59+
> regardless of this option.
60+
761
## Custom agent name
862

963
Each dev container gets an agent name derived from the workspace folder path by

0 commit comments

Comments
 (0)