Skip to content

Commit 78fb565

Browse files
mafredrimafredri
committed
docs: centralize customizations
1 parent 0ce9411 commit 78fb565

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)