docs: add documentation for modules in contributing #18597
Draft
+466
−0
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
Can you add a diagram describing how a module fits into Cider architecture? Also I would suggest being lean on the module usage section i.e. example uses, and more detailed on how to write the module and what is the significance of each type of resource an author can add to the module. What are those sources provided. Here we can also consider examples like what will be needed to write a module to:
In these we can also link existing matching module implementations as examples. |
|
Okay I had those exact examples in my registry version so I'll clean up and add these to the contributing doc and take into account the rest of your points as well 👌 |
bpmct
reviewed
Jun 26, 2025
bpmct
reviewed
Jun 26, 2025
docs/about/contributing/modules.md
Outdated
| } | ||
| ``` | ||
|
|
||
| #### coder_app - User Interface |
There was a problem hiding this comment.
I suggest adding some screenshots in sections like this!
bpmct
reviewed
Jun 26, 2025
docs/about/contributing/modules.md
Outdated
|
|
||
| ### External IDE Integration | ||
|
|
||
| **Browser-based IDE Pattern**: Install web-based development environment with health monitoring and configuration management. |
There was a problem hiding this comment.
Ah I see! You did it down here. I suggest bringing this up more, add links to registry, and remove "Pattern" from the end of each Section.
There was a problem hiding this comment.
I have moved it up and reorganized into a more worthy module type list.
Let me know if this vibes with you
bpmct
reviewed
Jun 26, 2025
matifali
requested changes
Jun 26, 2025
docs/about/contributing/modules.md
Outdated
Comment on lines
405
to
428
| ### External IDE Integration | ||
|
|
||
| **Browser-based IDE Pattern**: Install web-based development environment with health monitoring and configuration management. | ||
|
|
||
| **Desktop IDE Pattern**: Provide protocol-based integration for native applications with backend service management. | ||
|
|
||
| **Editor Extension Pattern**: Configure existing editors with workspace-specific settings and extensions. | ||
|
|
||
| ### Authentication and Secrets | ||
|
|
||
| **OAuth Integration Pattern**: Handle external authentication flows with token management and service configuration. | ||
|
|
||
| **API Key Management Pattern**: Securely distribute credentials and configure authenticated tools. | ||
|
|
||
| **Certificate Management Pattern**: Handle SSL certificates and secure communication setup. | ||
|
|
||
| ### Development Environment Setup | ||
|
|
||
| **Language Runtime Pattern**: Install and configure programming language environments with package managers. | ||
|
|
||
| **Database Service Pattern**: Deploy and configure database services with connection management. | ||
|
|
||
| **Configuration Management Pattern**: Apply dotfiles, settings, and workspace personalization. | ||
|
|
There was a problem hiding this comment.
Can we also link example modules heres?
There was a problem hiding this comment.
Moved module type list up and included module groups with tag links for registry with tag search per-propogated.
Let me know if this vibes with what you were thinking/
…per, Desktop, AI, Integration, and Web-based Tools and remove duplicate explanation from end of doc.
Co-authored-by: Atif Ali <atif@coder.com>
…ced resource links for better clarity addressed all comments up to commit time aside from unresolved comments awaiting replies
matifali
reviewed
Jun 27, 2025
Comment on lines
+20
to
+87
| ```mermaid | ||
| flowchart LR | ||
| subgraph Registry["🌐 Module Registry"] | ||
| ModuleCode["📦 Modules<br/>Terraform configurations<br/>with coder resources"] | ||
| StarterTemplates["📋 Starter Templates<br/>Infrastructure-specific bases<br/>(Docker, AWS, GCP, etc.)"] | ||
| end | ||
|
|
||
| subgraph CoderInstance["🏢 Your Coder Instance"] | ||
| Template["📄 Template<br/>References modules<br/>from registry"] | ||
|
|
||
| subgraph ModuleResources["🔧 Module Resources"] | ||
| Script["📜 coder_script<br/>Installation scripts"] | ||
| App["🖥️ coder_app<br/>UI applications"] | ||
| Env["🌍 coder_env<br/>Environment variables"] | ||
| end | ||
| end | ||
|
|
||
| subgraph Workspace["💻 Developer Workspace"] | ||
| Agent["🤖 Coder Agent"] | ||
|
|
||
| subgraph Results["Results"] | ||
| Tools["🛠️ Installed Tools<br/>IDEs, CLIs, Services"] | ||
| Apps["📱 Accessible Apps<br/>Web interfaces"] | ||
| Environment["⚙️ Configured Environment<br/>Variables, paths, settings"] | ||
| end | ||
| end | ||
|
|
||
| %% Module flow | ||
| ModuleCode -->|" Referenced by "| Template | ||
| StarterTemplates -->|" Used as base for "| Template | ||
|
|
||
| %% Template to resources | ||
| Template --> Script | ||
| Template --> App | ||
| Template --> Env | ||
|
|
||
| %% Resources to agent | ||
| Script --> Agent | ||
| App --> Agent | ||
| Env --> Agent | ||
|
|
||
| %% Agent to results | ||
| Agent --> Tools | ||
| Agent --> Apps | ||
| Agent --> Environment | ||
|
|
||
| %% Styling | ||
| style Registry fill:#e8f5e8,stroke:#2e7d32,stroke-width:2px,color:#000000 | ||
| style ModuleCode fill:#c8e6c9,stroke:#388e3c,stroke-width:2px,color:#000000 | ||
| style StarterTemplates fill:#c8e6c9,stroke:#388e3c,stroke-width:2px,color:#000000 | ||
|
|
||
| style CoderInstance fill:#e3f2fd,stroke:#1976d2,stroke-width:2px,color:#000000 | ||
| style Template fill:#bbdefb,stroke:#1e88e5,stroke-width:2px,color:#000000 | ||
| style ModuleResources fill:#90caf9,stroke:#42a5f5,stroke-width:2px,color:#000000 | ||
| style Script fill:#90caf9,stroke:#42a5f5,stroke-width:1px,color:#000000 | ||
| style App fill:#90caf9,stroke:#42a5f5,stroke-width:1px,color:#000000 | ||
| style Env fill:#90caf9,stroke:#42a5f5,stroke-width:1px,color:#000000 | ||
|
|
||
| style Workspace fill:#fff3e0,stroke:#f57c00,stroke-width:2px,color:#000000 | ||
| style Agent fill:#ffcc02,stroke:#ff9800,stroke-width:2px,color:#000000 | ||
| style Results fill:#ffe0b2,stroke:#ffa726,stroke-width:2px,color:#000000 | ||
| style Tools fill:#ffe0b2,stroke:#ffa726,stroke-width:1px,color:#000000 | ||
| style Apps fill:#ffe0b2,stroke:#ffa726,stroke-width:1px,color:#000000 | ||
| style Environment fill:#ffe0b2,stroke:#ffa726,stroke-width:1px,color:#000000 | ||
|
|
||
| %% Link styling to make arrows visible | ||
| linkStyle default stroke:#333333,stroke-width:2px | ||
| ``` |
There was a problem hiding this comment.
Our Doics engine currently does not support Mermaid rendering, so we need to render this and use an image.
Comment on lines
+170
to
+176
| ### [Web-based Tools](https://registry.coder.com/modules?search=tag%3Aweb) | ||
|
|
||
| Browser-accessible applications and interfaces. | ||
|
|
||
| - **[File Browser](https://registry.coder.com/modules/coder/filebrowser)**: A file browser for your workspace | ||
|
|
||
| Browse all available modules and explore specific categories at [registry.coder.com](https://registry.coder.com). |
There was a problem hiding this comment.
All web IDEs are also web-based, maybe we merge these two together.
Comment on lines
+115
to
+122
| - **[code-server](https://registry.coder.com/modules/coder/code-server)**: VS Code in the browser | ||
| - **[Cursor](https://registry.coder.com/modules/coder/cursor)**: Add a one-click button to launch Cursor IDE | ||
| - **[JetBrains Gateway](https://registry.coder.com/modules/coder/jetbrains-gateway)**: Add a one-click button to launch JetBrains Gateway IDEs in the dashboard | ||
| - **[Jupyter Notebook](https://registry.coder.com/modules/coder/jupyter-notebook)**: A module that adds Jupyter Notebook in your Coder template | ||
| - **[JupyterLab](https://registry.coder.com/modules/coder/jupyterlab)**: A module that adds JupyterLab in your Coder template | ||
| - **[VS Code Desktop](https://registry.coder.com/modules/coder/vscode-desktop)**: Add a one-click button to launch VS Code Desktop | ||
| - **[VS Code Web](https://registry.coder.com/modules/coder/vscode-web)**: VS Code Web - Visual Studio Code in the browser | ||
| - **[Windsurf Editor](https://registry.coder.com/modules/coder/windsurf)**: Add a one-click button to launch Windsurf Editor |
There was a problem hiding this comment.
Keep web-based IDEs and desktop IDEs separate. The main difference is that web-based IDEs require a coder_script to install and launch, while desktop IDEs only have a coder_app that provides the button. Also add a few sentences to describe the flow. Similar to how you described for code-server earlier.
Comment on lines
+128
to
+139
| - **[AWS Region](https://registry.coder.com/modules/coder/aws-region)**: A parameter with human region names and icons | ||
| - **[Azure Region](https://registry.coder.com/modules/coder/azure-region)**: A parameter with human region names and icons | ||
| - **[Coder Login](https://registry.coder.com/modules/coder/coder-login)**: Automatically logs the user into Coder on their workspace | ||
| - **[Dotfiles](https://registry.coder.com/modules/coder/dotfiles)**: Allow developers to optionally bring their own dotfiles repository to customize their shell and IDE settings | ||
| - **[Fly.io Region](https://registry.coder.com/modules/coder/fly-region)**: A parameter with human region names and icons | ||
| - **[GCP Region](https://registry.coder.com/modules/coder/gcp-region)**: Add Google Cloud Platform regions to your Coder template | ||
| - **[Git Clone](https://registry.coder.com/modules/coder/git-clone)**: Clone a Git repository by URL and skip if it exists | ||
| - **[Git commit signing](https://registry.coder.com/modules/coder/git-commit-signing)**: Configures Git to sign commits using your Coder SSH key | ||
| - **[Git Config](https://registry.coder.com/modules/coder/git-config)**: Stores Git configuration from Coder credentials | ||
| - **[Github Upload Public Key](https://registry.coder.com/modules/coder/github-upload-public-key)**: Automates uploading Coder public key to Github so users don't have to | ||
| - **[Personalize](https://registry.coder.com/modules/coder/personalize)**: Allow developers to customize their workspace on start | ||
| - **[Slack Me](https://registry.coder.com/modules/coder/slackme)**: Send a Slack message when a command finishes inside a workspace |
There was a problem hiding this comment.
Here to separate into two sections.
- Modules only using parameters, e.g., region
- Modules with
coder_script, such as installing a CLI or cloning a repository.
docs/about/contributing/modules.md
Outdated
Comment on lines
141
to
166
| ### [Desktop Modules](https://registry.coder.com/modules?search=tag%3Adesktop) | ||
|
|
||
| Provide graphical desktop environments for visual development workflows. | ||
|
|
||
| - **[Amazon DCV Windows](https://registry.coder.com/modules/coder/amazon-dcv-windows)**: Amazon DCV Server and Web Client for Windows | ||
| - **[KasmVNC](https://registry.coder.com/modules/coder/kasmvnc)**: A modern open source VNC server | ||
| - **[Windows RDP](https://registry.coder.com/modules/coder/windows-rdp)**: RDP Server and Web Client, powered by Devolutions Gateway | ||
| - **[Windows RDP Desktop](https://registry.coder.com/modules/coder/local-windows-rdp)**: Enable RDP on Windows and add a one-click Coder Desktop button for seamless access | ||
|
|
||
| ### [AI Modules](https://registry.coder.com/modules?search=tag%3Aai) | ||
|
|
||
| Integrate AI-powered development tools and assistants. | ||
|
|
||
| - **[Aider](https://registry.coder.com/modules/coder/aider)**: Run Aider AI pair programming in your workspace | ||
| - **[Amazon Q](https://registry.coder.com/modules/coder/amazon-q)**: Run Amazon Q in your workspace to access Amazon's AI coding assistant | ||
| - **[Claude Code](https://registry.coder.com/modules/coder/claude-code)**: Run Claude Code in your workspace | ||
| - **[Goose](https://registry.coder.com/modules/coder/goose)**: Run Goose in your workspace | ||
|
|
||
| ### [Integration Modules](https://registry.coder.com/modules?search=tag%3Aintegration) | ||
|
|
||
| Connect with external services and platforms. | ||
|
|
||
| - **[Hashicorp Vault Integration (GitHub)](https://registry.coder.com/modules/coder/vault-github)**: Authenticates with Vault using GitHub | ||
| - **[Hashicorp Vault Integration (JWT)](https://registry.coder.com/modules/coder/vault-jwt)**: Authenticates with Vault using a JWT from Coder's OIDC provider | ||
| - **[Hashicorp Vault Integration (Token)](https://registry.coder.com/modules/coder/vault-token)**: Authenticates with Vault using Token | ||
| - **[HCP Vault Secrets](https://registry.coder.com/modules/coder/hcp-vault-secrets)**: Fetch secrets from HCP Vault |
There was a problem hiding this comment.
We can keep these examples, but there's no need to explain again that they use the same approach as previous modules, i.e., as a collection of coder_app, coder_env, and coder_script resources.
| } | ||
| ``` | ||
|
|
||
| #### [coder_app - User Interface](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/app) |
There was a problem hiding this comment.
Instead of linking to docs in the heading, link to them when they first appear in the body text.
Co-authored-by: Atif Ali <atif@coder.com>
Co-authored-by: Atif Ali <atif@coder.com>
Co-authored-by: Atif Ali <atif@coder.com>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Let me know if this align's with what you were looking for in this modules doc. @matifali