Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Commitc177510

Browse files
docs: add documentation for Coder modules and their usage
1 parentfdf458e commitc177510

File tree

1 file changed

+336
-0
lines changed

1 file changed

+336
-0
lines changed

‎docs/about/contributing/modules.md

Lines changed: 336 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,336 @@
1+
#Coder modules
2+
3+
Coder modules are reusable Terraform configurations that extend workspace functionality. They provide pre-built integrations for development tools, services, and environments.
4+
5+
##Quick start
6+
7+
Add a module to your template:
8+
9+
```tf
10+
module "code-server" {
11+
source = "registry.coder.com/modules/code-server/coder"
12+
version = "1.0.18"
13+
agent_id = coder_agent.example.id
14+
}
15+
```
16+
17+
Browse available modules at[registry.coder.com](https://registry.coder.com).
18+
19+
##How modules work
20+
21+
Modules use standard Terraform syntax with Coder-specific resources:
22+
23+
-**`coder_script`**: Runs installation and configuration scripts
24+
-**`coder_app`**: Creates accessible applications in the workspace UI
25+
-**`coder_env`**: Sets environment variables
26+
27+
Example module structure:
28+
29+
```tf
30+
# Install and configure the service
31+
resource "coder_script" "install" {
32+
agent_id = var.agent_id
33+
script = file("${path.module}/install.sh")
34+
}
35+
36+
# Make it accessible in the UI
37+
resource "coder_app" "app" {
38+
agent_id = var.agent_id
39+
slug = "myapp"
40+
display_name = "My App"
41+
url = "http://localhost:8080"
42+
icon = "/icon/app.svg"
43+
}
44+
```
45+
46+
##Using modules in templates
47+
48+
###Basic usage
49+
50+
```tf
51+
terraform {
52+
required_providers {
53+
coder = {
54+
source = "coder/coder"
55+
version = ">= 2.0"
56+
}
57+
}
58+
}
59+
60+
# Your infrastructure resources
61+
resource "coder_agent" "main" {
62+
# ... agent configuration
63+
}
64+
65+
# Add modules
66+
module "code-server" {
67+
source = "registry.coder.com/modules/code-server/coder"
68+
version = "1.0.18"
69+
agent_id = coder_agent.main.id
70+
}
71+
72+
module "docker" {
73+
source = "registry.coder.com/modules/docker/coder"
74+
version = "1.0.11"
75+
agent_id = coder_agent.main.id
76+
}
77+
```
78+
79+
###Configuration options
80+
81+
Most modules accept configuration variables:
82+
83+
```tf
84+
module "code-server" {
85+
source = "registry.coder.com/modules/code-server/coder"
86+
version = "1.0.18"
87+
agent_id = coder_agent.main.id
88+
89+
# Configuration
90+
port = 13337
91+
extensions = ["ms-python.python", "golang.go"]
92+
folder = "/home/coder/project"
93+
}
94+
```
95+
96+
###Template parameters
97+
98+
Use template parameters to make modules configurable:
99+
100+
```tf
101+
data "coder_parameter" "ide" {
102+
name = "ide"
103+
display_name = "IDE"
104+
description = "Select your preferred IDE"
105+
default = "code-server"
106+
107+
option {
108+
name = "VS Code (Web)"
109+
value = "code-server"
110+
icon = "/icon/code.svg"
111+
}
112+
113+
option {
114+
name = "JetBrains Gateway"
115+
value = "jetbrains"
116+
icon = "/icon/jetbrains.svg"
117+
}
118+
}
119+
120+
module "code-server" {
121+
count = data.coder_parameter.ide.value == "code-server" ? 1 : 0
122+
source = "registry.coder.com/modules/code-server/coder"
123+
version = "1.0.18"
124+
agent_id = coder_agent.main.id
125+
}
126+
127+
module "jetbrains" {
128+
count = data.coder_parameter.ide.value == "jetbrains" ? 1 : 0
129+
source = "registry.coder.com/modules/jetbrains-gateway/coder"
130+
version = "1.0.12"
131+
agent_id = coder_agent.main.id
132+
}
133+
```
134+
135+
##Popular modules
136+
137+
###Development environments
138+
139+
-**[code-server](https://registry.coder.com/modules/code-server)**: VS Code in the browser
140+
-**[cursor](https://registry.coder.com/modules/cursor)**: Cursor editor with AI assistance
141+
-**[jetbrains-gateway](https://registry.coder.com/modules/jetbrains-gateway)**: JetBrains IDEs
142+
-**[vscode-desktop](https://registry.coder.com/modules/vscode-desktop)**: Local VS Code connection
143+
144+
###Development tools
145+
146+
-**[docker](https://registry.coder.com/modules/docker)**: Docker engine and CLI
147+
-**[git-clone](https://registry.coder.com/modules/git-clone)**: Automatic repository cloning
148+
-**[nodejs](https://registry.coder.com/modules/nodejs)**: Node.js runtime and npm
149+
-**[python](https://registry.coder.com/modules/python)**: Python runtime and pip
150+
151+
###Services
152+
153+
-**[postgres](https://registry.coder.com/modules/postgres)**: PostgreSQL database
154+
-**[redis](https://registry.coder.com/modules/redis)**: Redis cache
155+
-**[jupyter](https://registry.coder.com/modules/jupyter)**: Jupyter notebooks
156+
157+
##Module registry
158+
159+
###Official vs community modules
160+
161+
-**Official modules**:`registry.coder.com/modules/{name}/coder` (maintained by Coder team)
162+
-**Community modules**:`registry.coder.com/modules/{namespace}/{name}/coder`
163+
164+
###Version pinning
165+
166+
Always pin module versions for stability:
167+
168+
```tf
169+
module "code-server" {
170+
source = "registry.coder.com/modules/code-server/coder"
171+
version = "1.0.18" # Pin to specific version
172+
# version = "~> 1.0" # Allow patch updates
173+
agent_id = coder_agent.main.id
174+
}
175+
```
176+
177+
##Creating modules
178+
179+
###Module structure
180+
181+
```
182+
my-module/
183+
├── main.tf # Terraform configuration
184+
├── README.md # Documentation with frontmatter
185+
└── main.test.ts # Test suite
186+
```
187+
188+
###Basic module template
189+
190+
```tf
191+
terraform {
192+
required_version = ">= 1.0"
193+
required_providers {
194+
coder = {
195+
source = "coder/coder"
196+
version = ">= 2.0"
197+
}
198+
}
199+
}
200+
201+
variable "agent_id" {
202+
type = string
203+
description = "The ID of a Coder agent."
204+
}
205+
206+
variable "port" {
207+
type = number
208+
description = "Port to run the service on."
209+
default = 8080
210+
}
211+
212+
data "coder_workspace" "me" {}
213+
214+
resource "coder_script" "install" {
215+
agent_id = var.agent_id
216+
script = "#!/bin/bash\necho 'Installing service...'"
217+
}
218+
219+
resource "coder_app" "service" {
220+
agent_id = var.agent_id
221+
slug = "service"
222+
display_name = "My Service"
223+
url = "http://localhost:${var.port}"
224+
icon = "/icon/service.svg"
225+
}
226+
```
227+
228+
###Required README frontmatter
229+
230+
```yaml
231+
---
232+
display_name:Module Name
233+
description:Brief description of what the module does
234+
icon:../../../../.icons/service.svg
235+
maintainer_github:your-username
236+
verified:false
237+
tags:[development, service]
238+
---
239+
```
240+
241+
###Testing modules
242+
243+
Create`main.test.ts`:
244+
245+
```typescript
246+
import {describe,expect,it }from"bun:test";
247+
import {runTerraformApply,runTerraformInit,testRequiredVariables }from"~test";
248+
249+
describe("my-module",async ()=> {
250+
awaitrunTerraformInit(import.meta.dir);
251+
252+
testRequiredVariables(import.meta.dir, {
253+
agent_id:"test-agent",
254+
});
255+
256+
it("creates resources",async ()=> {
257+
const state=awaitrunTerraformApply(import.meta.dir, {
258+
agent_id:"test-agent",
259+
port:8080,
260+
});
261+
262+
expect(state.resources).toBeDefined();
263+
});
264+
});
265+
```
266+
267+
##Development workflow
268+
269+
###Contributing to the registry
270+
271+
1. Fork the[registry repository](https://github.com/coder/registry)
272+
2. Create your module in`registry/{namespace}/modules/{module-name}/`
273+
3. Test your module:`bun test`
274+
4. Format code:`bun run fmt`
275+
5. Submit a pull request
276+
277+
###Local testing
278+
279+
Test modules locally in templates before publishing:
280+
281+
```tf
282+
module "local-module" {
283+
source = "./path/to/local/module"
284+
agent_id = coder_agent.main.id
285+
}
286+
```
287+
288+
##Offline installations
289+
290+
For air-gapped environments, modules can be vendored locally:
291+
292+
1. Download module source code
293+
2. Place in your template directory
294+
3. Reference with local path:
295+
296+
```tf
297+
module "code-server" {
298+
source = "./modules/code-server"
299+
agent_id = coder_agent.main.id
300+
}
301+
```
302+
303+
##Troubleshooting
304+
305+
###Common issues
306+
307+
**Module script failures**: Module installation or startup scripts fail during workspace creation. Check the workspace build logs and agent startup logs for specific error messages.
308+
309+
**Registry connection errors**: Network issues preventing module downloads from`registry.coder.com`. Ensure your Coder deployment can reach the internet or use[offline installations](#offline-installations).
310+
311+
**Version not found**: Specified module version doesn't exist. Check available versions at[registry.coder.com](https://registry.coder.com) or use`version = "~> 1.0"` for automatic minor updates.
312+
313+
**Missing agent_id**: All modules require the`agent_id` variable to attach to a workspace agent.
314+
315+
**Provider version conflicts**: Module requires a newer Coder provider version than your deployment. Update your Coder installation or use an older module version.
316+
317+
###Debugging
318+
319+
Check workspace build logs and startup script output:
320+
321+
```console
322+
#View build logs
323+
coder show <workspace-name> --build
324+
325+
#View startup script logs (from inside workspace)
326+
cat /tmp/coder-startup-script.log
327+
328+
#View specific script logs
329+
cat /tmp/coder-script-<script-id>.log
330+
```
331+
332+
##Next steps
333+
334+
- Browse modules at[registry.coder.com](https://registry.coder.com)
335+
- Read the[template creation guide](../../tutorials/template-from-scratch.md)
336+
- Learn about[external authentication](../../admin/external-auth/index.md) for Git modules

0 commit comments

Comments
 (0)
[8]ページ先頭
©2009-2025 Movatter.jp