- Notifications
You must be signed in to change notification settings - Fork928
docs: add documentation for modules in contributing#18597
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to ourterms of service andprivacy statement. We’ll occasionally send you account related emails.
Already on GitHub?Sign in to your account
base:main
Are you sure you want to change the base?
Conversation
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 👌 |
Uh oh!
There was an error while loading.Please reload this page.
docs/about/contributing/modules.md Outdated
| } | ||
| ``` | ||
| ####coder_app - User Interface |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
I suggest adding some screenshots in sections like this!
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
I have moved it up and reorganized into a more worthy module type list.
Let me know if this vibes with you
Uh oh!
There was an error while loading.Please reload this page.
Uh oh!
There was an error while loading.Please reload this page.
Uh oh!
There was an error while loading.Please reload this page.
Uh oh!
There was an error while loading.Please reload this page.
Uh oh!
There was an error while loading.Please reload this page.
Uh oh!
There was an error while loading.Please reload this page.
Uh oh!
There was an error while loading.Please reload this page.
Uh oh!
There was an error while loading.Please reload this page.
Uh oh!
There was an error while loading.Please reload this page.
docs/about/contributing/modules.md Outdated
| ###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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
Can we also link example modules heres?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
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/
Uh oh!
There was an error while loading.Please reload this page.
…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 clarityaddressed all comments up to commit time aside from unresolved comments awaiting replies
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
I did another pass and it looks way better now. Please address comments.
| ```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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
Our Doics engine currently does not support Mermaid rendering, so we need to render this and use an image.
Uh oh!
There was an error while loading.Please reload this page.
Uh oh!
There was an error while loading.Please reload this page.
Uh oh!
There was an error while loading.Please reload this page.
| ###[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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
All web IDEs are also web-based, maybe we merge these two together.
| -**[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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
Keep web-based IDEs and desktop IDEs separate. The main difference is that web-based IDEs require acoder_script to install and launch, while desktop IDEs only have acoder_app that provides the button. Also add a few sentences to describe the flow. Similar to how you described for code-server earlier.
| -**[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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
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
| ###[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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
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 ofcoder_app,coder_env, andcoder_script resources.
| } | ||
| ``` | ||
| ####[coder_app - User Interface](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/app) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
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>
Let me know if this align's with what you were looking for in this modules doc.@matifali