Files
coder/docs/about/contributing/modules.md
T
Nick Vigilante 7846490770 docs: reconcile H1/label mismatches into front-matter titles (Phase 3) (#28036)
## Summary

**Batch B of Phase 3** of the H1 → front-matter migration (`DOCS-484`;
parent `DOCS-477`), the editorial follow-up to Batch A (#28030). For the
**124** hand-authored pages whose leading body H1 differed from the
manifest nav label, this promotes the richer body H1 to the front-matter
**page title** and drops the duplicate H1, while keeping the short
manifest **label** as the sidebar entry.

Policy agreed with the docs owner:
- Short sidebar labels win. Duplicate sidebar labels are acceptable.
- Identical **page titles** across two pages are not. On a collision,
rename the non-generated page's title.

## Page-title collisions resolved

Promoting the H1 created 4 page-title collisions; each is disambiguated
by renaming the non-generated / secondary page (sidebar labels left
unchanged):

| page | sidebar label | body H1 | → page title |
|------|---------------|---------|--------------|
| `install/index.md` | Install | Installing Coder | **Install Coder in
your infrastructure** |
| `install/cli.md` | Coder CLI | Installing Coder | **Install the Coder
CLI** |
| `ai-gateway/clients/jetbrains.md` | JetBrains | JetBrains IDEs |
**JetBrains** |
| `workspace-access/web-ides.md` | Web IDEs and Coder Apps | Web IDEs |
Web IDEs *(kept — primary user guide)* |
| `extending-templates/web-ides.md` | Web IDEs and Coder Apps | Web IDEs
| **Web IDEs in templates** |
| `workspace-management.md` | Workspace Management | Workspaces |
**Manage workspaces** *(vs generated `api/workspaces.md`)* |

These titles are the only non-mechanical editorial calls in this PR.

## Deliberately excluded: generated pages

`admin/security/audit-logs.md` and
`admin/setup/configuration-reference.md` are `make gen` outputs
(`auditdocgen` / `configdocgen`) that Phase 2 did **not** update, so a
hand-added title would be reverted on the next generation. They're
excluded here and need their generators taught to emit front matter
first (Phase 2 pattern), tracked as `DOCS-631`. Batch A (#28030) had the
same issue for three other generated pages; it has been corrected there
too.

## Verification

AI was the primary author of this PR (see disclosure below); per the [AI
Contribution
Guidelines](https://coder.com/docs/about/contributing/AI_CONTRIBUTING)
here is the manual verification.

- Promote = set front-matter `title` to the body H1 (or the
disambiguated title above) and remove that one duplicate H1. No other
body prose is reflowed.
- Every added front-matter block parses as YAML; all files pass `pnpm
check-docs` (markdownlint-cli2 + table formatter): `Summary: 0
error(s)`.
- Removing the H1 orphaned one in-page fragment (`[MCP](#mcp)` in
`ai-gateway/mcp.md`), now repointed. A cross-file fragment audit into
the retitled pages found no real breakage.


Anchor-change note

Unlike Batch A (title unchanged, a rendered no-op), Batch B changes each
page's effective title from the manifest label to the body H1, so the
rendered H1 **anchor slug changes**. An audit of cross-file
`.md#fragment` links into these pages surfaced no links that break as a
result (the only hits were false positives against a still-present `##
TLS & Reverse Proxy` heading). Same-file fragments are enforced by
markdownlint MD051, which is green.

## Title casing (follow-up, DOCS-742)

A follow-up commit puts the promoted titles into sentence case and
removes leading gerunds (for example, `Managing workspace schedules` →
`Manage workspace schedules`): 57 of the 120 titles changed, the other
63 were already compliant. Proper nouns and branded names (Coder
Validated Architecture, JetBrains, File Browser, Dev Containers,
Island), acronyms (API, CLI, IDE, MCP, OIDC, URL, UI, CI/CD), the
Premium license tier, and maturity labels (Beta, Experimental) are
preserved. The four `Nk-users` pages become `Reference architecture: up
to N users` (lowercase, matching the CVA landing page's own usage); the
CVA landing page keeps its branded title. `pnpm check-docs`: `Summary: 0
error(s)`.

Linear: DOCS-484, DOCS-742

> This PR was created with AI assistance (Coder Agents).
2026-09-08 16:34:00 +00:00

389 lines
11 KiB
Markdown

---
title: Contribute modules
---
Learn how to create and contribute Terraform modules to the Coder Registry. Modules provide reusable components that extend Coder workspaces with IDEs, development tools, login tools, and other features.
## What are Coder modules
Coder modules are Terraform modules that integrate with Coder workspaces to provide specific functionality. They are published to the Coder Registry at [registry.coder.com](https://registry.coder.com) and can be consumed in any Coder template using standard Terraform module syntax.
Examples of modules include:
- **Desktop IDEs**: [`jetbrains`](https://registry.coder.com/modules/coder/jetbrains), [`cursor`](https://registry.coder.com/modules/coder/cursor), [`devin-desktop`](https://registry.coder.com/modules/coder/devin-desktop), [`zed`](https://registry.coder.com/modules/coder/zed)
- **Web IDEs**: [`code-server`](https://registry.coder.com/modules/coder/code-server), [`vscode-web`](https://registry.coder.com/modules/coder/vscode-web), [`jupyter-notebook`](https://registry.coder.com/modules/coder/jupyter-notebook), [`jupyter-lab`](https://registry.coder.com/modules/coder/jupyterlab)
- **Integrations**: [`devcontainers-cli`](https://registry.coder.com/modules/coder/devcontainers-cli), [`vault-github`](https://registry.coder.com/modules/coder/vault-github), [`jfrog-oauth`](https://registry.coder.com/modules/coder/jfrog-oauth), [`jfrog-token`](https://registry.coder.com/modules/coder/jfrog-token)
- **Workspace utilities**: [`git-clone`](https://registry.coder.com/modules/coder/git-clone), [`dotfiles`](https://registry.coder.com/modules/coder/dotfiles), [`filebrowser`](https://registry.coder.com/modules/coder/filebrowser), [`coder-login`](https://registry.coder.com/modules/coder/coder-login), [`personalize`](https://registry.coder.com/modules/coder/personalize)
## Prerequisites
Before contributing modules, ensure you have:
- Basic Terraform knowledge
- [Terraform installed](https://developer.hashicorp.com/terraform/install)
- [Docker installed](https://docs.docker.com/get-docker/) (for running tests)
- [Bun installed](https://bun.sh/docs/installation) (for running tests and tooling)
## Setup your development environment
1. **Fork and clone the repository**:
```sh
git clone https://github.com/your-username/registry.git
cd registry
```
2. **Install dependencies**:
```sh
bun install
```
3. **Understand the structure**:
```txt
registry/[namespace]/
├── modules/ # Your modules
├── .images/ # Namespace avatar and screenshots
└── README.md # Namespace description
```
## Create your first module
### 1. Set up your namespace
If you're a new contributor, create your namespace directory:
```sh
mkdir -p registry/[your-username]
mkdir -p registry/[your-username]/.images
```
Add your namespace avatar by downloading your GitHub avatar and saving it as `avatar.png`:
```sh
curl -o registry/[your-username]/.images/avatar.png https://github.com/[your-username].png
```
Create your namespace README at `registry/[your-username]/README.md`:
```md
---
display_name: "Your Name"
bio: "Brief description of what you do"
github: "your-username"
avatar: "./.images/avatar.png"
linkedin: "https://www.linkedin.com/in/your-username"
website: "https://your-website.com"
support_email: "support@your-domain.com"
status: "community"
---
# Your Name
Brief description of who you are and what you do.
```
> [!NOTE]
> The `linkedin`, `website`, and `support_email` fields are optional and can be omitted or left empty if not applicable.
### 2. Generate module scaffolding
Use the provided script to generate your module structure:
```sh
./scripts/new_module.sh [your-username]/[module-name]
cd registry/[your-username]/modules/[module-name]
```
This creates:
- `main.tf` - Terraform configuration template
- `README.md` - Documentation template with frontmatter
- `run.sh` - Optional execution script
### 3. Implement your module
Edit `main.tf` to build your module's features. Here's an example based on the `git-clone` module structure:
```tf
terraform {
required_providers {
coder = {
source = "coder/coder"
}
}
}
# Input variables
variable "agent_id" {
description = "The ID of a Coder agent"
type = string
}
variable "url" {
description = "Git repository URL to clone"
type = string
validation {
condition = can(regex("^(https?://|git@)", var.url))
error_message = "URL must be a valid git repository URL."
}
}
variable "base_dir" {
description = "Directory to clone the repository into"
type = string
default = "~"
}
# Resources
resource "coder_script" "clone_repo" {
agent_id = var.agent_id
display_name = "Clone Repository"
script = <<-EOT
#!/bin/bash
set -e
# Ensure git is installed
if ! command -v git &> /dev/null; then
echo "Installing git..."
sudo apt-get update && sudo apt-get install -y git
fi
# Clone repository if it doesn't exist
if [ ! -d "${var.base_dir}/$(basename ${var.url} .git)" ]; then
echo "Cloning ${var.url}..."
git clone ${var.url} ${var.base_dir}/$(basename ${var.url} .git)
fi
EOT
run_on_start = true
}
# Outputs
output "repo_dir" {
description = "Path to the cloned repository"
value = "${var.base_dir}/$(basename ${var.url} .git)"
}
```
### 4. Write complete tests
Create `main.test.ts` to test your module features:
```tsx
import { runTerraformApply, runTerraformInit, testRequiredVariables } from "~test"
describe("git-clone", async () => {
await testRequiredVariables("registry/[your-username]/modules/git-clone")
it("should clone repository successfully", async () => {
await runTerraformInit("registry/[your-username]/modules/git-clone")
await runTerraformApply("registry/[your-username]/modules/git-clone", {
agent_id: "test-agent-id",
url: "https://github.com/coder/coder.git",
base_dir: "/tmp"
})
})
it("should work with SSH URLs", async () => {
await runTerraformInit("registry/[your-username]/modules/git-clone")
await runTerraformApply("registry/[your-username]/modules/git-clone", {
agent_id: "test-agent-id",
url: "git@github.com:coder/coder.git"
})
})
})
```
### 5. Document your module
Update `README.md` with complete documentation:
```md
---
display_name: "Git Clone"
description: "Clone a Git repository into your Coder workspace"
icon: "../../../../.icons/git.svg"
verified: false
tags: ["git", "development", "vcs"]
---
# Git Clone
This module clones a Git repository into your Coder workspace and ensures Git is installed.
## Usage
```tf
module "git_clone" {
source = "registry.coder.com/[your-username]/git-clone/coder"
version = "~> 1.0"
agent_id = coder_agent.main.id
url = "https://github.com/coder/coder.git"
base_dir = "/home/coder/projects"
}
```
## Module best practices
### Design principles
- **Single responsibility**: Each module should have one clear purpose
- **Reusability**: Design for use across different workspace types
- **Flexibility**: Provide sensible defaults but allow customization
- **Safe to rerun**: Ensure modules can be applied multiple times safely
### Terraform conventions
- Use descriptive variable names and include descriptions
- Provide default values for optional variables
- Include helpful outputs for working with other modules
- Use proper resource dependencies
- Follow [Terraform style conventions](https://developer.hashicorp.com/terraform/language/syntax/style)
### Documentation standards
Your module README should include:
- **Frontmatter**: Required metadata for the registry
- **Description**: Clear explanation of what the module does
- **Usage example**: Working Terraform code snippet
- **Additional context**: Setup requirements, known limitations, etc.
> [!NOTE]
> Do not include variables tables in your README. The registry automatically generates variable documentation from your `main.tf` file.
## Test your module
Run tests to ensure your module works correctly:
```sh
# Test your specific module
bun test -t 'git-clone'
# Test all modules
bun test
# Format code
bun fmt
```
> [!IMPORTANT]
> Tests require Docker with `--network=host` support, which typically requires Linux. macOS users can use [Colima](https://github.com/abiosoft/colima) or [OrbStack](https://orbstack.dev/) instead of Docker Desktop.
## Contribute to existing modules
### Types of contributions
**Bug fixes**:
- Fix installation or configuration issues
- Resolve compatibility problems
- Correct documentation errors
**Feature additions**:
- Add new configuration options
- Support additional platforms or versions
- Add new features
**Maintenance**:
- Update dependencies
- Improve error handling
- Optimize performance
### Making changes
1. **Identify the issue**: Reproduce the problem or identify the improvement needed
2. **Make focused changes**: Keep modifications minimal and targeted
3. **Maintain compatibility**: Ensure existing users aren't broken
4. **Add tests**: Test new features and edge cases
5. **Update documentation**: Reflect changes in the README
### Backward compatibility
When modifying existing modules:
- Add new variables with sensible defaults
- Don't remove existing variables without a migration path
- Don't change variable types or meanings
- Test that basic configurations still work
## Versioning
When you modify a module, update its version following semantic versioning:
- **Patch** (1.0.0 → 1.0.1): Bug fixes, documentation updates
- **Minor** (1.0.0 → 1.1.0): New features, new variables
- **Major** (1.0.0 → 2.0.0): Breaking changes, removing variables
Use the version bump script to update versions:
```sh
./.github/scripts/version-bump.sh patch|minor|major
```
## Submit your contribution
1. **Create a feature branch**:
```sh
git checkout -b feat/modify-git-clone-module
```
2. **Test thoroughly**:
```sh
bun test -t 'git-clone'
bun fmt
```
3. **Commit with clear messages**:
```sh
git add .
git commit -m "feat(git-clone): add git-clone module"
```
4. **Open a pull request**:
- Use a descriptive title
- Explain what the module does and why it's useful
- Reference any related issues
## Common issues and solutions
### Testing problems
**Issue**: Tests fail with network errors
**Solution**: Ensure Docker is running with `--network=host` support
### Module development
**Issue**: Icon not displaying
**Solution**: Verify icon path is correct and file exists in `.icons/` directory
### Documentation
**Issue**: Code blocks not syntax highlighted
**Solution**: Use `tf` language identifier for Terraform code blocks
## Get help
- **Examples**: Review existing modules like [`code-server`](https://registry.coder.com/modules/coder/code-server), [`git-clone`](https://registry.coder.com/modules/coder/git-clone), and [`jetbrains`](https://registry.coder.com/modules/coder/jetbrains)
- **Issues**: Open an issue at [github.com/coder/registry](https://github.com/coder/registry/issues)
- **Community**: Join the [Coder Discord](https://discord.gg/coder) for questions
- **Documentation**: Check the [Coder docs](https://coder.com/docs) for help on Coder.
## Next steps
After creating your first module:
1. **Share with the community**: Announce your module on Discord or social media
2. **Iterate based on feedback**: Improve based on user suggestions
3. **Create more modules**: Build a collection of related tools
4. **Contribute to existing modules**: Help maintain and improve the ecosystem
Happy contributing! 🚀