diff --git a/.sample/README.md b/.sample/README.md new file mode 100644 index 0000000..8581979 --- /dev/null +++ b/.sample/README.md @@ -0,0 +1,64 @@ +--- +display_name: MODULE_NAME +description: Describe what this module does +icon: ../.icons/.svg +maintainer_github: GITHUB_USERNAME +verified: false +tags: [community] +--- + +# MODULE_NAME + +<-- Describes what this module does --> + +<-- Add a screencast or screenshot here --> + +```hcl +module "MODULE_NAME" { + source = "https://registry.coder.com/modules/MODULE_NAME" +} +``` + +## Examples + +### Example 1 + +Install the Dracula theme from [OpenVSX](https://open-vsx.org/): + +```hcl +module "MODULE_NAME" { + source = "https://registry.coder.com/modules/MODULE_NAME" + agent_id = coder_agent.example.id + extensions = [ + "dracula-theme.theme-dracula" + ] +} +``` + +Enter the `.` into the extensions array and code-server will automatically install on start. + +### Example 2 + +Configure VS Code's [settings.json](https://code.visualstudio.com/docs/getstarted/settings#_settingsjson) file: + +```hcl +module "MODULE_NAME" { + source = "https://registry.coder.com/modules/MODULE_NAME" + agent_id = coder_agent.example.id + extensions = [ "dracula-theme.theme-dracula" ] + settings = { + "workbench.colorTheme" = "Dracula" + } +} +``` + +### Example 3 + +Run code-server in the background, don't fetch it from GitHub: + +```hcl +module "MODULE_NAME" { + source = "https://registry.coder.com/modules/MODULE_NAME" + agent_id = coder_agent.example.id + offline = true +} diff --git a/.sample/main.tf b/.sample/main.tf new file mode 100644 index 0000000..5dcaf01 --- /dev/null +++ b/.sample/main.tf @@ -0,0 +1,101 @@ +terraform { + required_version = ">= 1.0" + + required_providers { + coder = { + source = "coder/coder" + version = ">= 0.12" + } + } +} + +locals { + # A built-in icon like "/icon/code.svg" or a full URL of icon + icon_url = "https://raw.githubusercontent.com/coder/coder/main/site/static/icon/code.svg" + # a map of all possible values + options = { + "Option 1" = { + "name" = "Option 1", + "value" = "1" + "icon" = "/emojis/1.png" + } + "Option 2" = { + "name" = "Option 2", + "value" = "2" + "icon" = "/emojis/2.png" + } + } +} + +# Add required variables for your modules and remove any unneeded variables +variable "agent_id" { + type = string + description = "The ID of a Coder agent." +} + +variable "log_path" { + type = string + description = "The path to log MODULE_NAME to." + default = "/tmp/MODULE_NAME.log" +} + +variable "port" { + type = number + description = "The port to run MODULE_NAME on." + default = 19999 +} + +variable "mutable" { + type = bool + description = "Whether the parameter is mutable." + default = true +} +# Add other variables here + + +resource "coder_script" "MODULE_NAME" { + agent_id = var.agent_id + display_name = "MODULE_NAME" + icon = local.icon_url + script = templatefile("${path.module}/run.sh", { + LOG_PATH : var.log_path, + }) + run_on_start = true + run_on_stopt = false +} + +resource "coder_app" "MODULE_NAME" { + agent_id = var.agent_id + slug = "MODULE_NAME" + display_name = "MODULE_NAME" + url = "http://localhost:${var.port}" + icon = loocal.icon_url + subdomain = false + share = "owner" + + # Remove if the app does not have a healthcheck endpoint + healthcheck { + url = "http://localhost:${var.port}/healthz" + interval = 5 + threshold = 6 + } +} + +data "coder_parameter" "MODULE_NAME" { + type = "list(string)" + name = "MODULE_NAME" + display_name = "MODULE_NAME" + icon = local.icon_url + mutable = var.mutable + default = local.options["Option 1"]["value"] + + dynamic "option" { + for_each = local.options + content { + icon = option.value.icon + name = option.value.name + value = option.value.value + } + } +} + diff --git a/.sample/run.sh b/.sample/run.sh new file mode 100644 index 0000000..88af7ad --- /dev/null +++ b/.sample/run.sh @@ -0,0 +1,17 @@ +#!/usr/bin/env sh + +echo "Instalalting ${MODULE_NAME}..." +# Add code here +# Use varibles from the templatefile function in main.tf +# e.g. LOG_PATH, PORT, etc. + +echo "Installation comlete!" + +echo "Starting ${MODULE_NAME}..." +# Start the app in here +# 1. Use & to run it in background +# 2. redirct stdout and stderr to log files + +./app >${LOG_PATH} 2>&1 & + +echo "Sample app started!" diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..eb8d484 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,42 @@ +# Contributing + +To create a new module, clone this repository and run: + +```shell +./new.sh MOUDLE_NAME +``` + +Test a module by running an instance of Coder on your local machine: + +```shell +coder server --in-memory +``` + +This will create a new module in the modules directory with the given name and scaffolding. +Edit the files, adding your module's implementation, documentation and screenshots. + +## Testing a Module + +Create a template and edit it to include your development module: + +> [!NOTE] +> The Docker starter template is recommended for quick-iteration! + +```hcl +module "MOUDLE_NAME" { + source = "/home/user/coder/modules/MOUDLE_NAME" +} +``` + +You can also test your module by specifying the source as a git repository: + +```hcl +module "MOUDLE_NAME" { + source = "git::https://github.com//.git//?ref=" +} +``` + +Build a workspace and your module will be consumed! 🥳 + +Open a pull-request with your module, a member of the Coder team will +manually test it, and after-merge it will appear on the Registry. diff --git a/README.md b/README.md index 308a45e..b01b24d 100644 --- a/README.md +++ b/README.md @@ -32,30 +32,4 @@ Check out the [Coder Registry](https://registry.coder.com) for instructions to i ## Contributing a Module -To quickly start contributing with a new module, clone this repository and run: - -```sh -./new.sh -``` - -Test a module by running an instance of Coder on your local machine: - -```bash -coder server --in-memory -``` - -Create a template and edit it to include your development module: - -> *Info* -> The Docker starter template is recommended for quick-iteration! - -```tf -module "testing" { - source = "/home/user/coder/modules/my-new-module" -} -``` - -Build a workspace and your module will be consumed! 🥳 - -Open a pull-request with your module, a member of the Coder team will -manually test it, and after-merge it will appear on the Registry. +See [CONTRIBUTING.md](./CONTRIBUTING.md) for instructions on how to construct and publish a module to the [Coder Registry](https://registry.coder.com). diff --git a/new.sh b/new.sh index 0617957..2a3e3fb 100644 --- a/new.sh +++ b/new.sh @@ -1 +1,29 @@ #!/usr/bin/env sh + +# This scripts creates a new sample moduledir with requried files +# Run it like : ./new.sh my-module + +MODULE_NAME=$1 +# Check if module name is provided +if [ -z "$MODULE_NAME" ]; then + echo "Usage: ./new.sh " + exit 1 +fi + +# Create module directory and exist if it alredy exists +if [ -d "$MODULE_NAME" ]; then + echo "Module with name $MODULE_NAME already exists" + echo "Please choose a different name" + exit 1 +fi +mkdir -p "${MODULE_NAME}" + +# Copy required files from the sample module +cp -r .sample/* "${MODULE_NAME}" +# Update main.tf with module name +sed -i "s/MODULE_NAME/${MODULE_NAME}/g" main.tf +# Update README.md with module name +sed -i "s/MODULE_NAME/${MODULE_NAME}/g" README.md + +# Change to module directory +cd "${MODULE_NAME}"