diff --git a/content/en/docs/components/orchestration/stacks/coder.md b/content/en/docs/components/orchestration/stacks/coder.md index d4a6316..31c8794 100644 --- a/content/en/docs/components/orchestration/stacks/coder.md +++ b/content/en/docs/components/orchestration/stacks/coder.md @@ -3,126 +3,366 @@ title: "Coder" linkTitle: "Coder" weight: 20 description: > - Component 1 + Cloud Development Environments for secure, scalable remote development --- -{{% alert title="Draft" color="warning" %}} -**Editorial Status**: This page is currently being developed. - -* **Jira Ticket**: [TBD] -* **Assignee**: [Name or Team] -* **Status**: Draft -* **Last Updated**: YYYY-MM-DD -* **TODO**: - * [ ] Add detailed component description - * [ ] Include usage examples and code samples - * [ ] Add architecture diagrams - * [ ] Review and finalize content -{{% /alert %}} - ## Overview -[Detailed description of the component - what it is, what it does, and why it exists] +Coder is an enterprise cloud development environment (CDE) platform that provisions secure, consistent remote development workspaces. As part of the Edge Developer Platform, Coder enables developers to work in standardized, on-demand environments defined as code, moving development workloads from local machines to centrally managed infrastructure. + +The Coder stack deploys a self-hosted Coder instance with PostgreSQL database backend, integrated authentication, and edge connectivity capabilities. ## Key Features -* [Feature 1] -* [Feature 2] -* [Feature 3] - -## Purpose in EDP - -[Explain the role this component plays in the Edge Developer Platform and how it contributes to the overall platform capabilities] +* **Infrastructure as Code Workspaces**: Development environments defined using Terraform templates +* **IDE Agnostic**: Supports browser-based IDEs, VS Code, JetBrains IDEs, and other development tools +* **Secure Remote Access**: Workspaces run in controlled cloud or on-premises infrastructure +* **On-Demand Provisioning**: Developers create ephemeral or persistent workspaces as needed +* **AI Agent Support**: Secure execution environment for AI coding assistants +* **Template-Based Deployment**: Reusable workspace templates ensure consistency across teams ## Repository -**Code**: [Link to source code repository] +**Code**: [Coder Stack Templates](https://edp.buildth.ing/DevFW-CICD/stacks/src/branch/main/template/stacks/coder) -**Documentation**: [Link to component-specific documentation] +**Documentation**: +* [Coder Official Documentation](https://coder.com/docs) +* [Coder GitHub Repository](https://github.com/coder/coder) ## Getting Started ### Prerequisites -* [Prerequisite 1] -* [Prerequisite 2] +* Kubernetes cluster with ArgoCD installed (provided by `core` stack) +* CloudNativePG operator (provided by `core` stack) +* Ingress controller configured (provided by `otc` stack) +* cert-manager for TLS certificate management (provided by `otc` stack) +* Domain name configured via `DOMAIN_GITEA` environment variable ### Quick Start -[Step-by-step guide to get started with this component] +The Coder stack is deployed as part of the EDP installation process: -1. [Step 1] -2. [Step 2] -3. [Step 3] +1. **Trigger Deploy Pipeline** + - Go to [Infra Deploy Pipeline](https://edp.buildth.ing/DevFW/infra-deploy/actions?workflow=deploy.yaml) + - Click on Run workflow + - Enter a name in "Select environment directory to deploy". This must be DNS Compatible. (if you enter `test-me` then the domain will be `coder.test-me.t09.de`) + - Execute workflow + +2. **ArgoCD Synchronization** + ArgoCD automatically deploys: + - PostgreSQL database cluster (CloudNativePG) + - Coder application (Helm chart v2.28.3) + - Ingress configuration with TLS + - Database credentials and edge connectivity secrets ### Verification -[How to verify the component is working correctly] - -## Usage Examples - -### [Use Case 1] - -[Example with code/commands showing common use case] +Verify the Coder deployment: ```bash -# Example commands +# Check ArgoCD application status +kubectl get application coder -n argocd + +# Verify Coder pods are running +kubectl get pods -n coder + +# Check PostgreSQL cluster status +kubectl get cluster coder-db -n coder + +# Verify ingress configuration +kubectl get ingress -n coder ``` -### [Use Case 2] - -[Another common scenario] - -## Integration Points - -* **[Component A]**: [How it integrates] -* **[Component B]**: [How it integrates] -* **[Component C]**: [How it integrates] +Access the Coder web interface at `https://coder.{DOMAIN_GITEA}`. ## Architecture -[Optional: Add architectural diagrams and descriptions] +### Component Architecture -### Component Architecture (C4) +The Coder stack consists of: -[Add C4 Container or Component diagrams showing the internal structure] +**Coder Control Plane**: +- Web application for workspace management +- API server for workspace provisioning +- Terraform executor for infrastructure operations -### Sequence Diagrams +**PostgreSQL Database**: +- Single-instance CloudNativePG cluster +- Stores workspace metadata, templates, and user data +- Managed database user with `coder-db-user` secret +- 10Gi persistent storage on `csi-disk` storage class -[Add sequence diagrams showing key interaction flows with other components] - -### Deployment Architecture - -[Add infrastructure and deployment diagrams showing how the component is deployed] +**Networking**: +- ClusterIP service for internal communication +- Nginx ingress with TLS termination +- cert-manager integration for automatic certificate management ## Configuration -[Key configuration options and how to set them] +### Environment Variables + +The Coder application is configured through environment variables in `values.yaml`: + +**Access Configuration**: +- `CODER_ACCESS_URL`: Public URL where Coder is accessible (`https://coder.{DOMAIN_GITEA}`) + +**Database Configuration**: +- `CODER_PG_CONNECTION_URL`: PostgreSQL connection string (from `coder-db-user` secret) + +**Authentication**: +- `CODER_OAUTH2_GITHUB_DEFAULT_PROVIDER_ENABLE`: GitHub OAuth integration (disabled by default) + +**Edge Connectivity**: +- `EDGE_CONNECT_ENDPOINT`: Edge connection endpoint (from `edge-credential` secret) +- `EDGE_CONNECT_USERNAME`: Edge authentication username +- `EDGE_CONNECT_PASSWORD`: Edge authentication password + +### Helm Chart Configuration + +Key Helm values configured in `stacks/coder/coder/values.yaml`: + +```yaml +coder: + env: + - name: CODER_ACCESS_URL + value: "https://coder.{DOMAIN_GITEA}" + - name: CODER_PG_CONNECTION_URL + valueFrom: + secretKeyRef: + name: coder-db-user + key: uri + + service: + type: ClusterIP + + ingress: + enable: true + className: nginx + host: "coder.{DOMAIN_GITEA}" + annotations: + cert-manager.io/cluster-issuer: main + tls: + enable: true + secretName: coder-tls-secret +``` + +**Important**: Do not override `CODER_HTTP_ADDRESS`, `CODER_TLS_ENABLE`, `CODER_TLS_CERT_FILE`, or `CODER_TLS_KEY_FILE` as these are managed by the Helm chart. + +### PostgreSQL Database Configuration + +Defined in `stacks/coder/coder/manifests/postgres.yaml`: + +**Cluster Specification**: +- 1 instance (single-node cluster) +- Primary update strategy: unsupervised +- Resource requests/limits: 1 CPU, 1Gi memory +- Storage: 10Gi using `csi-disk` storage class + +**Managed Roles**: +- User: `coder` +- Permissions: createdb, login +- Password stored in `coder-db-user` secret + +### ArgoCD Application Configuration + +**Registry Application** (`template/registry/coder.yaml`): +- Name: `coder-reg` +- Manages the Coder stack directory +- Automated sync with prune and self-heal enabled + +**Stack Application** (`template/stacks/coder/coder.yaml`): +- Name: `coder` +- Deploys Coder Helm chart v2.28.3 from `https://helm.coder.com/v2` +- Automated self-healing enabled +- Creates namespace automatically +- References values from `stacks-instances` repository + +## Usage Examples + +### Creating a Workspace Template + +After deployment, create workspace templates using Terraform: + +1. **Access Coder Dashboard** + ```bash + open https://coder.${DOMAIN_GITEA} + ``` + +2. **Create Template Repository** + Create a Git repository with a Terraform template: + ```hcl + # main.tf + terraform { + required_providers { + coder = { + source = "coder/coder" + version = "~> 0.12" + } + kubernetes = { + source = "hashicorp/kubernetes" + version = "~> 2.23" + } + } + } + + resource "coder_agent" "main" { + os = "linux" + arch = "amd64" + } + + resource "kubernetes_pod" "main" { + metadata { + name = "coder-${data.coder_workspace.me.owner}-${data.coder_workspace.me.name}" + namespace = "coder-workspaces" + } + spec { + container { + name = "dev" + image = "codercom/enterprise-base:ubuntu" + command = ["sh", "-c", coder_agent.main.init_script] + } + } + } + ``` + +3. **Push Template to Coder** + ```bash + coder templates push kubernetes-dev + ``` + +### Provisioning a Development Workspace + +```bash +# Create a new workspace from template +coder create my-workspace --template kubernetes-dev + +# Connect via SSH +coder ssh my-workspace + +# Open in VS Code +coder open my-workspace --ide vscode + +# Stop workspace when not in use +coder stop my-workspace + +# Delete workspace +coder delete my-workspace +``` + +### Integrating with Platform Services + +Access EDP platform services from Coder workspaces: + +```bash +# Connect to platform PostgreSQL +psql "postgresql://myuser@postgres.core.svc.cluster.local:5432/mydb" + +# Access Forgejo +git clone https://forgejo.${DOMAIN_GITEA}/myorg/myrepo.git + +# Query platform metrics +curl https://grafana.${DOMAIN}/api/datasources +``` + +## Integration Points + +* **Core Stack**: Depends on ArgoCD for deployment orchestration and CloudNativePG operator for database management +* **OTC Stack**: Requires ingress-nginx controller and cert-manager for external access and TLS +* **Forgejo Stack**: Workspace templates can integrate with platform Git repositories +* **Observability Stack**: Workspace metrics can be collected by platform observability tools +* **Dex (SSO)**: Can be configured for centralized authentication (requires additional configuration) ## Troubleshooting -### [Common Issue 1] +### Coder Pods Not Starting -**Problem**: [Description] +**Problem**: Coder pods remain in `Pending` or `CrashLoopBackOff` state -**Solution**: [How to fix] +**Solution**: +1. Check PostgreSQL cluster status: + ```bash + kubectl get cluster coder-db -n coder + kubectl describe cluster coder-db -n coder + ``` -### [Common Issue 2] +2. Verify database credentials secret: + ```bash + kubectl get secret coder-db-user -n coder + kubectl get secret coder-db-user -n coder -o jsonpath='{.data.uri}' | base64 -d + ``` -**Problem**: [Description] +3. Check Coder logs: + ```bash + kubectl logs -n coder -l app=coder + ``` -**Solution**: [How to fix] +### Cannot Access Coder UI -## Status +**Problem**: Coder web interface is not accessible at configured URL -**Maturity**: [Production / Beta / Experimental] +**Solution**: +1. Verify ingress configuration: + ```bash + kubectl get ingress -n coder + kubectl describe ingress -n coder + ``` + +2. Check TLS certificate status: + ```bash + kubectl get certificate -n coder + kubectl describe certificate coder-tls-secret -n coder + ``` + +3. Verify DNS resolution: + ```bash + nslookup coder.${DOMAIN_GITEA} + ``` + +### Database Connection Errors + +**Problem**: Coder cannot connect to PostgreSQL database + +**Solution**: +1. Verify PostgreSQL cluster health: + ```bash + kubectl get pods -n coder -l cnpg.io/cluster=coder-db + kubectl logs -n coder -l cnpg.io/cluster=coder-db + ``` + +2. Check database and user creation: + ```bash + kubectl get database coder -n coder + kubectl exec -it coder-db-1 -n coder -- psql -U postgres -c "\l" + kubectl exec -it coder-db-1 -n coder -- psql -U postgres -c "\du" + ``` + +3. Test connection string: + ```bash + kubectl exec -it coder-db-1 -n coder -- psql "$(kubectl get secret coder-db-user -n coder -o jsonpath='{.data.uri}' | base64 -d)" + ``` + +### Workspace Provisioning Fails + +**Problem**: Workspaces fail to provision from templates + +**Solution**: +1. Check Coder provisioner logs: + ```bash + kubectl logs -n coder -l app=coder --tail=100 + ``` + +2. Verify Kubernetes permissions for workspace creation: + ```bash + kubectl auth can-i create pods --as=system:serviceaccount:coder:coder -n coder-workspaces + ``` + +3. Review template Terraform configuration for errors ## Additional Resources -* [Link to external documentation] -* [Link to community resources] -* [Link to related components] - -## Documentation Notes - -[Instructions for team members filling in this documentation - remove this section once complete] +* [Coder Documentation](https://coder.com/docs) +* [Coder Templates Repository](https://github.com/coder/coder) +* [CloudNativePG Documentation](https://cloudnative-pg.io/) +* [ArgoCD Documentation](https://argo-cd.readthedocs.io/) +* [Coder Blog: 2025 Launch Week](https://coder.com/blog/launch-week-2025-instant-infrastructure)