Theia Deployment

This repository manages automated deployments of Theia Cloud to Kubernetes clusters using GitHub Actions. Theia Cloud provides browser-based development environments, allowing students and developers to work in containerized IDEs without local setup.

What is This Repository?

This repository serves as the infrastructure-as-code for deploying and managing Theia Cloud instances across multiple environments (production, staging, and testing). It provides:

• Automated CI/CD pipelines for deploying Theia Cloud via GitHub Actions
• Environment-specific configurations for production, staging, and test environments
• Custom Helm charts for AppDefinitions, certificates, metrics, and combined deployments
• GitOps workflow for managing deployments with approval gates and automated rollouts

Repository Structure

.
├── .github/workflows/       # GitHub Actions workflows for automated deployment
│   ├── deploy-theia.yml    # Reusable core deployment workflow
│   ├── deploy-pr.yml       # PR-triggered test deployments
│   ├── deploy-staging.yml  # Auto-deploy to staging on main push
│   └── deploy-production.yml # Manual production deployments
│
├── deployments/            # Environment-specific Helm values
│   ├── theia.artemis.cit.tum.de/              # Production config
│   ├── theia-staging.artemis.cit.tum.de/      # Staging config
│   └── test1.theia-test.artemis.cit.tum.de/   # Test environment config
│
├── charts/                 # Custom Helm charts
│   ├── theia-cloud-combined/    # Combined chart with all components
│   ├── theia-appdefinitions/    # Custom IDE environments (images/configs)
│   ├── theia-certificates/      # SSL certificate management
│   └── theia-metrics/           # Prometheus/Grafana dashboards
│
├── value-reference-files/  # Reference Helm values for different setups
│
└── docs/                   # Detailed documentation
    ├── deployment-workflows.md  # How deployments work
    ├── adding-environments.md   # Adding new environments
    ├── keycloak-setup.md        # Authentication configuration
    ├── tum-certificates.md      # TUM-specific SSL certificate process
    └── monitoring-setup.md      # Prometheus & Grafana setup

Deployment Architecture

┌───────────────────────────────────────────────────────────────┐
│                      GitHub Actions Workflows                 │
├───────────────────────────────────────────────────────────────┤
│                                                               │
│  ┌─────────────┐    ┌──────────────┐    ┌─────────────────┐   │
│  │   PR Push   │    │ Push to main │    │ Manual Trigger  │   │
│  │             │    │              │    │  (GitHub UI)    │   │
│  └──────┬──────┘    └──────┬───────┘    └────────┬────────┘   │
│         │                  │                     │            │
│         ▼                  ▼                     ▼            │
│  ┌─────────────┐    ┌──────────────┐    ┌─────────────────┐   │
│  │deploy-pr.yml│    │deploy-staging│    │deploy-production│   │
│  │             │    │    .yml      │    │     .yml        │   │
│  └──────┬──────┘    └──────┬───────┘    └────────┬────────┘   │
│         │                  │                     │            │
│         └──────────────────┴─────────────────────┘            │
│                            │                                  │
│                            ▼                                  │
│                  ┌──────────────────┐                         │
│                  │  deploy-theia.yml│                         │
│                  │ (Reusable Core)  │                         │
│                  └────────┬─────────┘                         │
│                           │                                   │
└───────────────────────────┼───────────────────────────────────┘
                            │
            ┌───────────────┴───────────────┐
            │                               │
            ▼                               ▼
┌───────────────────────────┐   ┌───────────────────────────┐
│   Production Cluster      │   │  Staging/Test Cluster     │
│   (Separate Kubeconfig)   │   │  (Shared Kubeconfig)      │
├───────────────────────────┤   ├───────────────────────────┤
│                           │   │                           │
│  ┌─────────────────────┐  │   │  ┌─────────────────────┐  │
│  │  theia-prod         │  │   │  │  theia-staging      │  │
│  │  Manual Deploy      │  │   │  │  Auto on main       │  │
│  │  (Approval Req.)    │  │   │  │  (No Approval)      │  │
│  └─────────────────────┘  │   │  └─────────────────────┘  │
│                           │   │                           │
└───────────────────────────┘   │  ┌─────────────────────┐  │
                                │  │  theia-test1        │  │
                                │  │  Auto on PR         │  │
                                │  │  (Approval Req.)    │  │
                                │  └─────────────────────┘  │
                                │                           │
                                └───────────────────────────┘

Deployment Triggers:

• theia-prod: Manual via GitHub UI with approval required
• theia-staging: Automatic on push to main branch (no approval)
• test1: Automatic on PR push with approval gate (configurable)

Environments

Environment	Namespace	Domain	Deployment Trigger	Approval Required
Production	theia-prod	theia.artemis.cit.tum.de	Manual (GitHub UI)	Yes
Staging	theia-staging	theia-staging.artemis.cit.tum.de	Push to main	No
Test1	test1	test1.theia-test.artemis.cit.tum.de	PR push	Yes (configurable)

Configuration files for each environment are located in the deployments/ directory.

Quick Start

Prerequisites

• Kubernetes cluster with ingress-nginx controller
• Helm 3.x installed
• kubectl configured for your cluster
• GitHub repository with appropriate secrets configured

Basic Installation

1. Prepare your cluster (enable snippet annotations for ingress-nginx):

   kubectl -n ingress-nginx patch cm ingress-nginx-controller \
     --patch '{"data":{"allow-snippet-annotations":"true","annotations-risk-level":"Critical"}}'
   kubectl -n ingress-nginx delete pod -l app.kubernetes.io/name=ingress-nginx

2. Install Theia Cloud base charts:

   helm repo add theia-cloud-repo https://eclipse-theia.github.io/theia-cloud-helm/
   helm repo update
   
   helm upgrade theia-cloud-base theia-cloud-repo/theia-cloud-base --install \
     -f deployments/your-environment/theia-base-helm-values.yml
   
   helm upgrade theia-cloud-crds theia-cloud-repo/theia-cloud-crds --install \
     -f deployments/your-environment/theia-crds-helm-values.yml

3. Install the combined Theia Cloud chart:

   helm upgrade --install theia-cloud-combined ./charts/theia-cloud-combined \
     --namespace your-namespace --create-namespace \
     -f deployments/your-environment/values.yaml

Using GitHub Actions for Deployment

The recommended approach is to use the automated GitHub Actions workflows:

1. Configure GitHub Environment with required secrets and variables (see Adding Environments)
2. Push to main to deploy to staging automatically
3. Create a PR to deploy to test environment with approval
4. Manually trigger production deployment from GitHub Actions UI

See Deployment Workflows for detailed instructions.

Common Tasks

• Deploy a PR to test environment: See Deployment Workflows
• Add a new environment: See Adding Environments
• Configure Keycloak authentication: See Keycloak Setup
• Request TUM wildcard certificates: See TUM Certificates
• Set up monitoring: See Monitoring Setup

AppDefinitions

AppDefinitions define the IDE environments that users work in. Custom AppDefinitions are built in a three-stage pipeline at artemis-theia-blueprints.

To install or update AppDefinitions:

helm dependency update ./charts/theia-cloud-combined
helm upgrade --install theia-cloud-combined ./charts/theia-cloud-combined \
  --namespace your-namespace --create-namespace \
  -f deployments/your-environment/values.yaml

The AppDefinitions chart configuration is documented in charts/theia-appdefinitions/templates/appdefinition.yaml.

Documentation

Detailed documentation is available in the docs/ directory:

• Deployment Workflows - How automated deployments work
• Adding Environments - Step-by-step guide to add new environments
• Keycloak Setup - Authentication and authorization configuration
• TUM Certificates - TUM-specific SSL certificate process
• Monitoring Setup - Prometheus and Grafana installation

Related Projects

• Theia Cloud - Main Theia Cloud project
• Theia Cloud Helm Charts - Official Helm charts
• Artemis Theia Blueprints - Custom IDE images and configurations
• Theia Cloud Observability - Monitoring and observability

Support

For issues or questions:

• Check the documentation
• Review existing GitHub Issues
• Consult the Theia Cloud documentation