- Notifications
You must be signed in to change notification settings - Fork926
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 👌 |
| # Coder modules | ||
| Coder modules are reusable Terraform configurations that extend workspace functionality through the Coder Terraform provider. This guide focuses on understanding and creating effective modules. | ||
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 would suggest talking about "Examples" of different "module types" here, linking to the corresponding tags. Examples include:
- IDE
- Remote Desktop
- Agents
- Developer Tools
- Helper Parameters
- Dev Experience
- Security
| } | ||
| ``` | ||
| #### 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!
| ### 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.
| ### 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.
| **Browser-based IDE Pattern**: Install web-based development environment with health monitoring and configuration management. | |
| **Browser-based IDE**: Install web-based development environment with health monitoring and configuration management. |
| 1. **Module Registry**: External registry hosts reusable modules and starter templates | ||
| - Modules are Terraform configurations using Coder-specific resources | ||
| - Starter templates provide infrastructure-specific bases (Docker, AWS, GCP, etc.) to start building your own templates | ||
| - Community and official modules available 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.
| -Community and official modules available at[registry.coder.com](https://registry.coder.com) | |
| -[Coderregistry](https://registry.coder.com) hosts a collection of official, partner, and community contributed templates and modules. |
| 2. **Template Development**: Your Coder templates reference modules from the registry | ||
| - Use starter templates as infrastructure-specific starting points for your own templates | ||
| - Reference individual modules to add functionality to your templates | ||
| - Modules add `coder_script`, `coder_app`, and `coder_env` resources to templates |
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.
This is too specfic. I think its better to remove
| - Modules add `coder_script`, `coder_app`, and `coder_env` resources to templates |
| - Starter templates provide infrastructure-specific bases (Docker, AWS, GCP, etc.) to start building your own templates | ||
| - Community and official modules available at [registry.coder.com](https://registry.coder.com) | ||
| 2. **Template Development**: Your Coder templates reference modules from the registry |
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.
| 2.**Template Development**: Your Coder templates reference modules from the registry | |
| 2.**Templates**: Your Coder templates reference modules from the registry |
| ├── main.tf # Terraform configuration with Coder resources | ||
| ├── main.test.ts # Test suite | ||
| ├── README.md # Documentation with frontmatter | ||
| └── run.sh # Installation script |
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.
| └── run.sh # Installation script | |
| └── run.sh # Installationor setupscript |
| ### Coder Resources | ||
| #### coder_script - Command Execution |
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.
link with provder docs
| # Provides: name, id, access_url, start_count | ||
| data "coder_workspace_owner" "me" {} | ||
| # Provides: name, email, full_name |
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.
| #Provides: name, email, full_name | |
| #Provides: name, email, full_name, groups of the workspace owner. |
| url = "http://localhost:${var.port}" | ||
| healthcheck { | ||
| url = "http://localhost:${var.port}/health" |
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.
healthcheck url is service-specific and may not be the exact path for all services. I think it's important to mention and avoid misleading.
| ## Testing and Documentation | ||
| ### Module Testing | ||
| While not mandatory, **tests are recommended** for all modules. A `main.test.ts` file validates that the module works correctly. Tests use **Bun** as the test runner and verify that: | ||
| - **Custom configurations** work with different variable values | ||
| - **Default configuration** creates expected resources | ||
| - **Input validation** catches invalid parameters | ||
| - **Required variables** are properly validated | ||
| The test framework provides utilities from `~test` import to: | ||
| - Initialize Terraform in the module directory | ||
| - Apply Terraform with test variables | ||
| - Validate the resulting infrastructure state | ||
| - Test error conditions and edge cases | ||
| Tests run in Docker with `--network=host` capabilities and help ensure module quality and reliability. | ||
| ### Documentation Requirements | ||
| Every module requires a `README.md` with YAML frontmatter containing metadata like display name, description, icon, maintainer, and tags. The README must include: | ||
| - **Purpose and functionality** - What the module does and when to use it | ||
| - **Variable documentation** - All input variables with types, defaults, and descriptions | ||
| - **Resource listing** - What Coder resources the module creates | ||
| - **Usage examples** - Basic and advanced configuration examples | ||
| - **Requirements** - Any prerequisites or dependencies | ||
| The documentation format is validated automatically and must pass validation before modules can be accepted. See the [Registry Contributing Guide](https://github.com/coder/registry/blob/main/CONTRIBUTING.md) for detailed formatting requirements and examples. |
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 think this whole section can be removed or moved to Contributing docs in registry repo.
| ### 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?
| ## Contributing to the Registry | ||
| The [Coder Registry](https://github.com/coder/registry) hosts all community and official modules. For detailed contribution guidelines, code standards, and submission processes, refer to the [Registry Contributing Guide](https://github.com/coder/registry/blob/main/CONTRIBUTING.md). | ||
| **Quick contribution steps**: | ||
| 1. Fork the [registry repository](https://github.com/coder/registry) | ||
| 2. Follow the [registry contribution guidelines](https://github.com/coder/registry/blob/main/CONTRIBUTING.md) for module creation process | ||
| 3. Implement tests: `bun test` | ||
| 4. Format code: `bun run fmt` | ||
| 5. Validate documentation: `bun run readme-validate` | ||
| 6. Submit pull request with detailed description | ||
| **Important**: The registry repository contains specific requirements for module structure, testing, documentation format, and submission process. Always consult the [official contributing documentation](https://github.com/coder/registry/blob/main/CONTRIBUTING.md) for the most current guidelines. | ||
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.
Again move this to regstry repo and link.
Let me know if this align's with what you were looking for in this modules doc.@matifali