Skip to content
This repository was archived by the owner on May 15, 2025. It is now read-only.

Commit e8bd011

Browse files
matifalibpmct
matifali
and
bpmct
authored
add a template module and boilerplate (#30)
* add a template module and boilerplate * add CONTRIBUTING.md (#31) * Update .sample/README.md Co-authored-by: Ben Potter <[email protected]> * swap screenshot and code sample --------- Co-authored-by: Ben Potter <[email protected]>
1 parent abb51a3 commit e8bd011

6 files changed

Lines changed: 253 additions & 27 deletions

File tree

‎.sample/README.md‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
---
2+
display_name: MODULE_NAME
3+
description: Describe what this module does
4+
icon: ../.icons/<A_RELEVANT_ICON>.svg
5+
maintainer_github: GITHUB_USERNAME
6+
verified: false
7+
tags: [community]
8+
---
9+
10+
# MODULE_NAME
11+
12+
<-- Describes what this module does -->
13+
14+
<-- Add a screencast or screenshot here -->
15+
16+
```hcl
17+
module "MODULE_NAME" {
18+
source = "https://registry.coder.com/modules/MODULE_NAME"
19+
}
20+
```
21+
22+
## Examples
23+
24+
### Example 1
25+
26+
Install the Dracula theme from [OpenVSX](https://open-vsx.org/):
27+
28+
```hcl
29+
module "MODULE_NAME" {
30+
source = "https://registry.coder.com/modules/MODULE_NAME"
31+
agent_id = coder_agent.example.id
32+
extensions = [
33+
"dracula-theme.theme-dracula"
34+
]
35+
}
36+
```
37+
38+
Enter the `<author>.<name>` into the extensions array and code-server will automatically install on start.
39+
40+
### Example 2
41+
42+
Configure VS Code's [settings.json](https://code.visualstudio.com/docs/getstarted/settings#_settingsjson) file:
43+
44+
```hcl
45+
module "MODULE_NAME" {
46+
source = "https://registry.coder.com/modules/MODULE_NAME"
47+
agent_id = coder_agent.example.id
48+
extensions = [ "dracula-theme.theme-dracula" ]
49+
settings = {
50+
"workbench.colorTheme" = "Dracula"
51+
}
52+
}
53+
```
54+
55+
### Example 3
56+
57+
Run code-server in the background, don't fetch it from GitHub:
58+
59+
```hcl
60+
module "MODULE_NAME" {
61+
source = "https://registry.coder.com/modules/MODULE_NAME"
62+
agent_id = coder_agent.example.id
63+
offline = true
64+
}

‎.sample/main.tf‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
terraform {
2+
required_version = ">= 1.0"
3+
4+
required_providers {
5+
coder = {
6+
source = "coder/coder"
7+
version = ">= 0.12"
8+
}
9+
}
10+
}
11+
12+
locals {
13+
# A built-in icon like "/icon/code.svg" or a full URL of icon
14+
icon_url = "https://raw.githubusercontent.com/coder/coder/main/site/static/icon/code.svg"
15+
# a map of all possible values
16+
options = {
17+
"Option 1" = {
18+
"name" = "Option 1",
19+
"value" = "1"
20+
"icon" = "/emojis/1.png"
21+
}
22+
"Option 2" = {
23+
"name" = "Option 2",
24+
"value" = "2"
25+
"icon" = "/emojis/2.png"
26+
}
27+
}
28+
}
29+
30+
# Add required variables for your modules and remove any unneeded variables
31+
variable "agent_id" {
32+
type = string
33+
description = "The ID of a Coder agent."
34+
}
35+
36+
variable "log_path" {
37+
type = string
38+
description = "The path to log MODULE_NAME to."
39+
default = "/tmp/MODULE_NAME.log"
40+
}
41+
42+
variable "port" {
43+
type = number
44+
description = "The port to run MODULE_NAME on."
45+
default = 19999
46+
}
47+
48+
variable "mutable" {
49+
type = bool
50+
description = "Whether the parameter is mutable."
51+
default = true
52+
}
53+
# Add other variables here
54+
55+
56+
resource "coder_script" "MODULE_NAME" {
57+
agent_id = var.agent_id
58+
display_name = "MODULE_NAME"
59+
icon = local.icon_url
60+
script = templatefile("${path.module}/run.sh", {
61+
LOG_PATH : var.log_path,
62+
})
63+
run_on_start = true
64+
run_on_stopt = false
65+
}
66+
67+
resource "coder_app" "MODULE_NAME" {
68+
agent_id = var.agent_id
69+
slug = "MODULE_NAME"
70+
display_name = "MODULE_NAME"
71+
url = "http://localhost:${var.port}"
72+
icon = loocal.icon_url
73+
subdomain = false
74+
share = "owner"
75+
76+
# Remove if the app does not have a healthcheck endpoint
77+
healthcheck {
78+
url = "http://localhost:${var.port}/healthz"
79+
interval = 5
80+
threshold = 6
81+
}
82+
}
83+
84+
data "coder_parameter" "MODULE_NAME" {
85+
type = "list(string)"
86+
name = "MODULE_NAME"
87+
display_name = "MODULE_NAME"
88+
icon = local.icon_url
89+
mutable = var.mutable
90+
default = local.options["Option 1"]["value"]
91+
92+
dynamic "option" {
93+
for_each = local.options
94+
content {
95+
icon = option.value.icon
96+
name = option.value.name
97+
value = option.value.value
98+
}
99+
}
100+
}
101+

‎.sample/run.sh‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
#!/usr/bin/env sh
2+
3+
echo "Instalalting ${MODULE_NAME}..."
4+
# Add code here
5+
# Use varibles from the templatefile function in main.tf
6+
# e.g. LOG_PATH, PORT, etc.
7+
8+
echo "Installation comlete!"
9+
10+
echo "Starting ${MODULE_NAME}..."
11+
# Start the app in here
12+
# 1. Use & to run it in background
13+
# 2. redirct stdout and stderr to log files
14+
15+
./app >${LOG_PATH} 2>&1 &
16+
17+
echo "Sample app started!"

‎CONTRIBUTING.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# Contributing
2+
3+
To create a new module, clone this repository and run:
4+
5+
```shell
6+
./new.sh MOUDLE_NAME
7+
```
8+
9+
Test a module by running an instance of Coder on your local machine:
10+
11+
```shell
12+
coder server --in-memory
13+
```
14+
15+
This will create a new module in the modules directory with the given name and scaffolding.
16+
Edit the files, adding your module's implementation, documentation and screenshots.
17+
18+
## Testing a Module
19+
20+
Create a template and edit it to include your development module:
21+
22+
> [!NOTE]
23+
> The Docker starter template is recommended for quick-iteration!
24+
25+
```hcl
26+
module "MOUDLE_NAME" {
27+
source = "/home/user/coder/modules/MOUDLE_NAME"
28+
}
29+
```
30+
31+
You can also test your module by specifying the source as a git repository:
32+
33+
```hcl
34+
module "MOUDLE_NAME" {
35+
source = "git::https://github.com/<USERNAME>/<REPO>.git//<FOLDER>?ref=<BRANCH>"
36+
}
37+
```
38+
39+
Build a workspace and your module will be consumed! 🥳
40+
41+
Open a pull-request with your module, a member of the Coder team will
42+
manually test it, and after-merge it will appear on the Registry.

‎README.md‎

Lines changed: 1 addition & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -32,30 +32,4 @@ Check out the [Coder Registry](https://registry.coder.com) for instructions to i
3232

3333
## Contributing a Module
3434

35-
To quickly start contributing with a new module, clone this repository and run:
36-
37-
```sh
38-
./new.sh
39-
```
40-
41-
Test a module by running an instance of Coder on your local machine:
42-
43-
```bash
44-
coder server --in-memory
45-
```
46-
47-
Create a template and edit it to include your development module:
48-
49-
> *Info*
50-
> The Docker starter template is recommended for quick-iteration!
51-
52-
```tf
53-
module "testing" {
54-
source = "/home/user/coder/modules/my-new-module"
55-
}
56-
```
57-
58-
Build a workspace and your module will be consumed! 🥳
59-
60-
Open a pull-request with your module, a member of the Coder team will
61-
manually test it, and after-merge it will appear on the Registry.
35+
See [CONTRIBUTING.md](./CONTRIBUTING.md) for instructions on how to construct and publish a module to the [Coder Registry](https://registry.coder.com).

‎new.sh‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,29 @@
11
#!/usr/bin/env sh
2+
3+
# This scripts creates a new sample moduledir with requried files
4+
# Run it like : ./new.sh my-module
5+
6+
MODULE_NAME=$1
7+
# Check if module name is provided
8+
if [ -z "$MODULE_NAME" ]; then
9+
echo "Usage: ./new.sh <module_name>"
10+
exit 1
11+
fi
12+
13+
# Create module directory and exist if it alredy exists
14+
if [ -d "$MODULE_NAME" ]; then
15+
echo "Module with name $MODULE_NAME already exists"
16+
echo "Please choose a different name"
17+
exit 1
18+
fi
19+
mkdir -p "${MODULE_NAME}"
20+
21+
# Copy required files from the sample module
22+
cp -r .sample/* "${MODULE_NAME}"
23+
# Update main.tf with module name
24+
sed -i "s/MODULE_NAME/${MODULE_NAME}/g" main.tf
25+
# Update README.md with module name
26+
sed -i "s/MODULE_NAME/${MODULE_NAME}/g" README.md
27+
28+
# Change to module directory
29+
cd "${MODULE_NAME}"

0 commit comments

Comments
 (0)