template_development_guide.md

Coder Template Development Guide

This guide documents best practices and workflows for developing and iterating on Coder templates.

Understanding Templates

Coder templates are written in Terraform and define the infrastructure required for workspaces. These templates create VMs, containers, and other resources that developers use as their development environments.

Template Development Workflow

1. Template Creation and Initial Testing

1. Create a new template from scratch or existing examples:

   coder templates init

2. Develop the template locally: Edit the main.tf file to define your workspace infrastructure.

3. Push the template to the Coder server:

   coder templates push my-template --directory /path/to/template

4. Create a test workspace:

   coder create test-workspace --template my-template

2. Iterative Development

When making changes to templates, follow these steps:

1. Make incremental changes: Start with a known working template and make small, incremental changes.

2. Track template versions: Push new versions and note which ones work correctly.

   coder templates versions list my-template

3. Revert to working versions if needed:

   coder templates versions promote --template=my-template --template-version=happy_feynman3

4. Add logging: Use logging in startup scripts to help diagnose issues.

3. Best Practices for Template Development

1. Add meaningful logging:

   • Use simple file-based logging rather than transcript logging in PowerShell
   • Include timestamps and clear step identifiers
   • Log both success and error conditions

2. Verify paths and conditions before use:

   if (-not (Test-Path -Path $SomePath)) {
     # Log and handle missing path
   }

3. Use absolute paths: Always prefer absolute paths over relative paths.

4. Structure scripts for diagnostics:

   • Add status scripts to check workspace health
   • Include self-healing measures where possible

5. Simplify path handling: Avoid complex path manipulation in scripts.

6. Develop incrementally:

   • Start with a minimal working template
   • Add features one at a time, testing each addition

Troubleshooting Template Issues

Common Issues and Solutions

1. Agent connection issues:

   • Check agent logs (e.g., C:\Windows\Temp\coder_agent.log)
   • Verify network connectivity
   • Check agent authentication method

2. Startup script failures:

   • Review startup logs (e.g., C:\Windows\Temp\coder_startup.log)
   • Test scripts outside of Coder in a similar environment
   • Add more detailed logging

3. Resource provisioning problems:

   • Check Terraform state and logs
   • Verify IAM permissions
   • Test resource creation outside of Coder

Debugging Commands

1. SSH into a workspace:

   coder config-ssh  # Configure SSH for Coder workspaces
   ssh coder.my-workspace  # Connect to workspace

2. View workspace details:

   coder show my-workspace

3. Monitor logs:

   ssh coder.my-workspace cat /path/to/logfile

4. Check workspace agent status:

   coder show my-workspace

Template Version Management

1. List template versions:

   coder templates versions list my-template

2. Download a specific template version:

   coder templates pull my-template --version=happy_feynman3 /path/to/destination

3. Promote a template version to active:

   coder templates versions promote --template=my-template --template-version=happy_feynman3

Sharing Templates

1. Export a template:

   coder templates pull my-template /path/to/export

2. Version control: Store templates in Git repositories for better collaboration and version tracking.

Windows-Specific Template Considerations

1. Path handling: Windows uses backslashes (\) while Terraform uses forward slashes. Be careful with escaping.

2. PowerShell vs CMD: Prefer PowerShell for complex scripts, but be aware of execution policy restrictions.

3. Script logging: Use file output instead of transcript logging:

   "$(Get-Date -Format 'yyyy-MM-dd HH:mm:ss') - Your log message" | Out-File -Append $LogFile

4. Disk initialization: Be thorough with disk detection and mounting logic:

   $disk = Get-Disk | Where-Object { $_.Number -eq 1 }
   if ($disk -and $disk.PartitionStyle -eq "RAW") {
     # Initialize and format disk
   }

5. Software installation: Always verify paths and use error handling with installers.

Conclusion

Developing Coder templates requires careful planning, incremental changes, and good logging practices. By following these guidelines, you can create robust templates that provide consistent development environments for your team.