### Install and Start Theia Cloud Testing App

Source: https://github.com/eclipse-theia/theia-cloud/blob/main/node/testing-page/README.md

Installs project dependencies and starts the testing application. Open http://localhost:3000 in your browser after running these commands.

```bash
npm ci
npm start
```

--------------------------------

### Run Example App with Extensions

Source: https://github.com/eclipse-theia/theia-cloud/blob/main/theia/README.md

Starts the example application that includes all developed Theia extensions. Access the running application at http://localhost:3000.

```sh
yarn start
```

--------------------------------

### Apply Metrics Server Installation

Source: https://github.com/eclipse-theia/theia-cloud/blob/main/documentation/Install.md

Apply the Metrics Server installation manifest. Refer to the official GitHub repository for the most current installation instructions.

```bash
kubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yaml
```

--------------------------------

### Run Landing Page with npm Start -w

Source: https://github.com/eclipse-theia/theia-cloud/blob/main/node/README.md

Start the landing page development server using 'npm run start -w landing-page'. This command is specific to running the 'landing-page' package.

```bash
npm run start -w landing-page
```

--------------------------------

### Install Theia Cloud Next Version

Source: https://github.com/eclipse-theia/theia-cloud/blob/main/README.md

Installs the latest development (pre-release) version of Theia Cloud. Use the `--devel` flag in addition to the standard installation commands.

```bash
helm install theia-cloud-base theia-cloud-remote/theia-cloud-base --set issuer.email=your-mail@example.com --devel

helm install theia-cloud-crds theia-cloud-remote/theia-cloud-crds  --namespace theia-cloud --create-namespace --devel

helm install theia-cloud theia-cloud-remote/theia-cloud --namespace theia-cloud --devel
```

--------------------------------

### Install Theia Cloud

Source: https://github.com/eclipse-theia/theia-cloud/blob/main/documentation/Install.md

Install the main Theia Cloud Helm chart into the 'theia-cloud' namespace.

```bash
helm install theia-cloud theia-cloud-remote/theia-cloud --namespace theia-cloud
```

--------------------------------

### Build Monorepo and Install Dependencies

Source: https://github.com/eclipse-theia/theia-cloud/blob/main/node/landing-page/README.md

Navigate to the parent directory and run these commands to install dependencies and build the monorepo, which is necessary for linking common packages.

```bash
cd ..
npm ci
npm run build
```

--------------------------------

### Start Session (Existing Workspace)

Source: https://context7.com/eclipse-theia/theia-cloud/llms.txt

Use this endpoint to start a new session for an existing workspace. The response includes the session URL.

```bash
curl -X POST \
  https://service.theia-cloud.example.com/service/session \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "appId": "my-app-id",
    "user": "alice@example.com",
    "appDefinition": "theia-ide",
    "workspaceName": "ws-alice-my-project",
    "timeout": 3,
    "env": {
      "fromMap": { "DEBUG": "true" }
    }
  }'
# Response: "ws-alice-example-com-abc123.theia-cloud.example.com"
```

--------------------------------

### Initialize and Apply Theia Cloud Installation (Step 1)

Source: https://github.com/eclipse-theia/theia-cloud/blob/main/terraform/terraform.md

Initialize Terraform and apply the configuration to install Theia Cloud and its dependencies. Ensure minikube tunnel is running for HAProxy.

```bash
cd ../1_theiacloud-and-dependencies

# download required providers
terraform init

# install Theia Cloud and all dependencies
# You will be asked for an email address used by the cert-manager to contact you about expiring certs.
terraform apply
```

--------------------------------

### Start Session

Source: https://context7.com/eclipse-theia/theia-cloud/llms.txt

Starts a new session for an already-existing workspace. Returns the session URL.

```APIDOC
## POST /service/session — Start Session (for existing workspace)

### Description
Starts a new session for an already-existing workspace. Returns the session URL.

### Method
POST

### Endpoint
/service/session

### Request Body
- **appId** (string) - Required - The application ID.
- **user** (string) - Required - The user identifier.
- **appDefinition** (string) - Required - The application definition.
- **workspaceName** (string) - Required - The name of the workspace.
- **timeout** (number) - Optional - The session timeout in minutes.
- **env** (object) - Optional - Environment variables for the session.
  - **fromMap** (object) - Key-value pairs for environment variables.

### Request Example
```json
{
  "appId": "my-app-id",
  "user": "alice@example.com",
  "appDefinition": "theia-ide",
  "workspaceName": "ws-alice-my-project",
  "timeout": 3,
  "env": {
    "fromMap": { "DEBUG": "true" }
  }
}
```

### Response
#### Success Response (200)
- (string) - The session URL.
```

--------------------------------

### Start New Session

Source: https://github.com/eclipse-theia/theia-cloud/blob/main/documentation/api/Apis/SessionResourceApi.md

Starts a new session for an existing workspace and returns the URL of the started session.

```APIDOC
## POST /service/session

### Description
Start a new session

Starts a new session for an existing workspace and responds with the URL of the started session.

### Method
POST

### Endpoint
/service/session

### Parameters
#### Request Body
- **SessionStartRequest** (SessionStartRequest) - Required - 

### Response
#### Success Response (200)
- **String** (String) - 

### Response Example
{
  "example": "session_url"
}
```

--------------------------------

### Install Theia Cloud via Helm

Source: https://context7.com/eclipse-theia/theia-cloud/llms.txt

Installs Theia Cloud components using Helm charts in a specific order. Ensure to update the Helm repository before installation. Uninstall command is also provided.

```bash
# Add the Theia Cloud Helm repository
helm repo add theia-cloud-remote https://eclipse-theia.github.io/theia-cloud-helm
helm repo update

# 1. Cluster-wide base resources (cert-manager issuers, etc.)
helm install theia-cloud-base theia-cloud-remote/theia-cloud-base \
  --set issuer.email=admin@example.com

# 2. Custom Resource Definitions
helm install theia-cloud-crds theia-cloud-remote/theia-cloud-crds \
  --namespace theia-cloud --create-namespace

# 3. Operator, service, and landing page
helm install theia-cloud theia-cloud-remote/theia-cloud \
  --namespace theia-cloud

# Switch kubectl context to the new namespace
kubectl config set-context --current --namespace=theia-cloud

# Verify installation
helm get manifest theia-cloud -n theia-cloud

# Uninstall
helm uninstall theia-cloud -n theia-cloud
```

--------------------------------

### Install Theia Cloud (Development Version)

Source: https://github.com/eclipse-theia/theia-cloud/blob/main/documentation/Install.md

Install the development version of the main Theia Cloud Helm chart using the `--devel` flag.

```bash
helm install theia-cloud theia-cloud-remote/theia-cloud --namespace theia-cloud --devel
```

--------------------------------

### Install Theia Cloud Base (Development Version)

Source: https://github.com/eclipse-theia/theia-cloud/blob/main/documentation/Install.md

Install the development version of the Theia Cloud base Helm chart. Use the `--devel` flag to specify the next version.

```bash
helm install theia-cloud-base theia-cloud-remote/theia-cloud-base --set issuer.email=your-mail@example.com --devel
```

--------------------------------

### Install Theia Cloud Base Release

Source: https://github.com/eclipse-theia/theia-cloud/blob/main/documentation/Install.md

Install the Theia Cloud base Helm chart. Replace 'your-mail@example.com' with your actual email address for issuer configuration.

```bash
helm install theia-cloud-base theia-cloud-remote/theia-cloud-base --set issuer.email=your-mail@example.com
```

--------------------------------

### TheiaCloud TypeScript API Examples

Source: https://context7.com/eclipse-theia/theia-cloud/llms.txt

Demonstrates various operations using the TheiaCloud client, including checking service availability, launching and managing sessions, listing app definitions, managing workspaces, and handling errors. Ensure the @eclipse-theiacloud/common package is installed.

```typescript
import {
  TheiaCloud,
  LaunchRequest,
  TheiaCloudError,
  SessionSetConfigValueRequest
} from '@eclipse-theiacloud/common';

const SERVICE_URL = 'https://service.theia-cloud.example.com';
const APP_ID = 'my-app-id';
const ACCESS_TOKEN = '<oauth_token>';
const opts = { accessToken: ACCESS_TOKEN, timeout: 30000, retries: 1 };

// --- Ping ---
const alive: boolean = await TheiaCloud.ping(
  { serviceUrl: SERVICE_URL, appId: APP_ID },
  opts
);
console.log('Service alive:', alive);

// --- Launch ephemeral session (no workspace) ---
const sessionUrl = await TheiaCloud.launch(
  LaunchRequest.ephemeral(SERVICE_URL, APP_ID, 'theia-ide', 3, 'alice@example.com'),
  opts
);
console.log('Session URL:', sessionUrl);

// --- Launch and redirect browser ---
await TheiaCloud.launchAndRedirect(
  LaunchRequest.createWorkspace(SERVICE_URL, APP_ID, 'theia-ide', 3, 'alice@example.com', undefined, 'My Project'),
  opts
);

// --- Launch into existing workspace ---
const url = await TheiaCloud.launch(
  LaunchRequest.existingWorkspace(SERVICE_URL, APP_ID, 'ws-alice-my-project', 3, undefined, 'alice@example.com'),
  opts
);

// --- List app definitions ---
const defs = await TheiaCloud.AppDefinition.listAppDefinitions(
  { serviceUrl: SERVICE_URL, appId: APP_ID },
  opts
);
defs.forEach(d => console.log(d.name, d.image));

// --- Session management ---
const sessions = await TheiaCloud.Session.listSessions(
  { serviceUrl: SERVICE_URL, appId: APP_ID, user: 'alice@example.com' },
  opts
);

const newSessionUrl = await TheiaCloud.Session.startSession(
  { serviceUrl: SERVICE_URL, appId: APP_ID, user: 'alice@example.com', appDefinition: 'theia-ide', workspaceName: 'ws-alice-my-project' },
  opts
);

const stopped: boolean = await TheiaCloud.Session.stopSession(
  { serviceUrl: SERVICE_URL, appId: APP_ID, user: 'alice@example.com', sessionName: sessions[0].name! },
  opts
);

// Report activity to prevent session timeout
await TheiaCloud.Session.reportSessionActivity(
  { serviceUrl: SERVICE_URL, appId: APP_ID, sessionName: sessions[0].name! },
  opts
);

// Get resource usage
const perf = await TheiaCloud.Session.getSessionPerformance(
  { serviceUrl: SERVICE_URL, appId: APP_ID, sessionName: sessions[0].name! },
  opts
);
console.log(`CPU: ${perf.cpuAmount}${perf.cpuFormat}, Memory: ${perf.memoryAmount}${perf.memoryFormat}`);

// Inject config into a running session
await TheiaCloud.Session.setConfigValue(
  sessions[0].name!,
  { serviceUrl: SERVICE_URL, appId: APP_ID, key: 'api_key', value: 'secret123' },
  opts
);

// --- Workspace management ---
const workspaces = await TheiaCloud.Workspace.listWorkspaces(
  { serviceUrl: SERVICE_URL, appId: APP_ID, user: 'alice@example.com' },
  opts
);

const ws = await TheiaCloud.Workspace.createWorkspace(
  { serviceUrl: SERVICE_URL, appId: APP_ID, user: 'alice@example.com', appDefinition: 'theia-ide', label: 'New Project' },
  opts
);

await TheiaCloud.Workspace.deleteWorkspace(
  { serviceUrl: SERVICE_URL, appId: APP_ID, user: 'alice@example.com', workspaceName: ws.name },
  opts
);

// --- Error handling ---
try {
  await TheiaCloud.launch(LaunchRequest.ephemeral(SERVICE_URL, APP_ID, 'missing-app', 3, 'bob@example.com'), opts);
} catch (err) {
  if (err instanceof TheiaCloudError) {
    console.error(`HTTP ${err.status}: ${err.message}`);
    // err.serverError?.code, err.serverError?.reason
    // err.request?.serviceUrl
  }
}
```

--------------------------------

### Install Dependencies with npm CI

Source: https://github.com/eclipse-theia/theia-cloud/blob/main/node/README.md

Use 'npm ci' for a clean installation of dependencies, ensuring consistency and reproducibility. This command is recommended for CI environments.

```bash
npm ci
```

--------------------------------

### Install Dependencies with Yarn

Source: https://github.com/eclipse-theia/theia-cloud/blob/main/theia/README.md

Installs project dependencies using Yarn. This is a prerequisite for running or building the application.

```sh
yarn
```

--------------------------------

### Apply Cert-Manager Installation

Source: https://github.com/eclipse-theia/theia-cloud/blob/main/documentation/Install.md

Apply the Cert-Manager installation manifest. Ensure you are using the latest version as per the official documentation.

```bash
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.11.0/cert-manager.yaml
```

--------------------------------

### Install and Set openapi-generator-cli Version

Source: https://github.com/eclipse-theia/theia-cloud/blob/main/documentation/OpenAPI.md

Install the openapi-generator-cli globally via npm and set the desired version.

```bash
npm install @openapitools/openapi-generator-cli -g
openapi-generator-cli version-manager set 7.8.0
```

--------------------------------

### Start Minikube and Enable Addons

Source: https://github.com/eclipse-theia/theia-cloud/blob/main/terraform/ci-configurations/run-locally.md

Initializes Minikube with specified resources and enables essential addons like dashboard, default storage class, ingress, and metrics server. It also patches the ingress controller to allow snippet annotations.

```sh
minikube start --memory=8192 --cpus=4 --driver=virtualbox

minikube addons enable dashboard
minikube addons enable default-storageclass
minikube addons enable ingress
minikube addons enable metrics-server

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

--------------------------------

### Initialize and Apply Minikube Cluster (Step 0)

Source: https://github.com/eclipse-theia/theia-cloud/blob/main/terraform/terraform.md

Initialize Terraform and apply the configuration to create the minikube cluster. This step is required before installing Theia Cloud.

```bash
cd configurations/minikube_getting_started/0_minikube_getting_started

# download required providers
terraform init

# create the cluster
terraform apply
```

--------------------------------

### Install Config Store Extension

Source: https://github.com/eclipse-theia/theia-cloud/blob/main/theia/extensions/config-store/README.md

Add the Config Store extension to your Theia application's package.json dependencies to install it.

```json
{
  "dependencies": {
    "@eclipse-theiacloud/config-store": "1.3.0-next"
  }
}
```

--------------------------------

### Install Theia Cloud CRDs (Development Version)

Source: https://github.com/eclipse-theia/theia-cloud/blob/main/documentation/Install.md

Install the development version of the Theia Cloud CRDs. The `--devel` flag is used to target the next release.

```bash
helm install theia-cloud-crds theia-cloud-remote/theia-cloud-crds  --namespace theia-cloud --create-namespace --devel
```

--------------------------------

### serviceSessionPost

Source: https://github.com/eclipse-theia/theia-cloud/blob/main/documentation/api/README.md

Start a new session.

```APIDOC
## POST /service/session

### Description
Start a new session.

### Method
POST

### Endpoint
/service/session
```

--------------------------------

### Install Theia Cloud Last Release

Source: https://github.com/eclipse-theia/theia-cloud/blob/main/README.md

Installs the latest stable release of Theia Cloud components. Requires the Helm repository to be added and updated. The `issuer.email` should be replaced with your actual email.

```bash
helm install theia-cloud-base theia-cloud-remote/theia-cloud-base --set issuer.email=your-mail@example.com

helm install theia-cloud-crds theia-cloud-remote/theia-cloud-crds  --namespace theia-cloud --create-namespace

helm install theia-cloud theia-cloud-remote/theia-cloud --namespace theia-cloud
```

--------------------------------

### Destroy Theia Cloud Installation (Step 1)

Source: https://github.com/eclipse-theia/theia-cloud/blob/main/terraform/terraform.md

Destroy the Theia Cloud installation and its dependencies by applying the terraform destroy command.

```bash
terraform destroy
```

--------------------------------

### Launch Theia Cloud Session

Source: https://context7.com/eclipse-theia/theia-cloud/llms.txt

Use the POST /service endpoint to atomically create a workspace if needed and start an IDE session. This endpoint supports ephemeral sessions and persistent workspaces with environment variable configuration.

```bash
# Launch an ephemeral session (no persistent workspace)
curl -X POST \
  https://service.theia-cloud.example.com/service \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "appId": "my-app-id",
    "user": "alice@example.com",
    "appDefinition": "theia-ide",
    "ephemeral": true,
    "timeout": 5
  }'
# Response: "ws-alice-example-com-abc123.theia-cloud.example.com"

# Launch with a new persistent workspace
curl -X POST \
  https://service.theia-cloud.example.com/service \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "appId": "my-app-id",
    "user": "alice@example.com",
    "appDefinition": "theia-ide",
    "label": "My Project",
    "ephemeral": false,
    "timeout": 3,
    "env": {
      "fromMap": { "MY_VAR": "hello" },
      "fromConfigMaps": ["my-app-configmap"],
      "fromSecrets": ["my-app-secret"]
    }
  }'

# Launch with an existing workspace by name
curl -X POST \
  https://service.theia-cloud.example.com/service \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "appId": "my-app-id",
    "user": "alice@example.com",
    "workspaceName": "ws-alice-my-project",
    "timeout": 3
  }'
```

--------------------------------

### Generate API Documentation in Markdown

Source: https://github.com/eclipse-theia/theia-cloud/blob/main/documentation/OpenAPI.md

Generate API documentation in markdown format using the openapi-generator-cli. Ensure openapi-generator-cli is installed and version is set.

```bash
openapi-generator-cli generate -g markdown -i ./documentation/openapi.json -o ./documentation/api --skip-validate-spec
```

--------------------------------

### Check Config Server Availability

Source: https://github.com/eclipse-theia/theia-cloud/blob/main/theia/extensions/config-store/README.md

A simple GET endpoint is provided to verify that the config server is running and accessible.

```http
GET /theia-cloud/config-store
```

--------------------------------

### Build Extensions and App with Yarn

Source: https://github.com/eclipse-theia/theia-cloud/blob/main/theia/README.md

Rebuilds all Theia extensions and the example application without reinstalling dependencies. Useful during development to see changes reflected.

```sh
yarn build
```

--------------------------------

### Check Config Server Availability

Source: https://github.com/eclipse-theia/theia-cloud/blob/main/theia/extensions/config-store/README.md

A simple GET endpoint is provided to verify that the config server is running and accessible.

```APIDOC
## GET /theia-cloud/config-store

### Description
Provides a simple endpoint to check the availability of the config server.

### Method
GET

### Endpoint
/theia-cloud/config-store

### Response
#### Success Response (200)
This endpoint is for checking availability and does not specify a response body. A successful response (e.g., 200 OK) indicates the server is reachable.
```

--------------------------------

### Generate TypeScript API Client

Source: https://github.com/eclipse-theia/theia-cloud/blob/main/documentation/OpenAPI.md

Generate a TypeScript API client using the openapi-generator-cli from the root of the repository. Ensure openapi-generator-cli is installed and version is set.

```bash
openapi-generator-cli generate -g typescript-axios -i ./documentation/openapi.json -o node/common/src/client/ --additional-properties=supportsES6=true,typescriptThreePlus=true --skip-validate-spec
```

--------------------------------

### Listen to Config Store Changes in Theia Extension

Source: https://context7.com/eclipse-theia/theia-cloud/llms.txt

Use the ConfigStoreService to listen for configuration changes pushed from outside the session. This example shows how to react to 'database_url' changes and read/set/remove other configuration values.

```typescript
// Inside a Theia extension — listening to config store changes
import { ConfigStoreService } from '@eclipse-theiacloud/config-store/lib/browser/config-store-service';
import { inject, injectable } from '@theia/core/shared/inversify';

@injectable()
export class MyService {
  @inject(ConfigStoreService) protected readonly configStore: ConfigStoreService;

  async activate(): Promise<void> {
    // Listen for changes pushed from outside
    this.configStore.onConfigValueChanged(event => {
      console.log(`Config changed: ${event.key} = ${event.value}`);
      if (event.key === 'database_url' && event.value) {
        this.reconnectDatabase(event.value);
      }
    });

    // Read a value set from outside
    const token = await this.configStore.get('api_token');
    console.log('Current API token:', token);

    // Set a value from inside the session
    await this.configStore.set('theme', 'dark');

    // Remove a value
    await this.configStore.remove('temporary_key');
  }
}
```

--------------------------------

### GET /service/appdefinition/{appId} — List App Definitions

Source: https://context7.com/eclipse-theia/theia-cloud/llms.txt

Returns all available `AppDefinitionSpec` objects registered in the cluster for the given app ID.

```APIDOC
## GET /service/appdefinition/{appId} — List App Definitions

### Description
Returns all available `AppDefinitionSpec` objects registered in the cluster for the given app ID.

### Method
GET

### Endpoint
`/service/appdefinition/{appId}`

### Parameters
#### Path Parameters
- **appId** (string) - Required - The ID of the application.

### Request Example
```bash
curl -X GET \
  https://service.theia-cloud.example.com/service/appdefinition/my-app-id \
  -H "Authorization: Bearer <access_token>"
```

### Response
#### Success Response (200)
- **array** - A list of AppDefinitionSpec objects.
  - **name** (string) - The name of the AppDefinition.
  - **image** (string) - The container image to use.
  - **port** (integer) - The port the application listens on.
  - **minInstances** (integer) - Minimum number of instances.
  - **maxInstances** (integer) - Maximum number of instances.
  - **timeout** (integer) - Session timeout in minutes.
  - **requestsMemory** (string) - Memory request for the container.
  - **requestsCpu** (string) - CPU request for the container.
  - **limitsMemory** (string) - Memory limit for the container.
  - **limitsCpu** (string) - CPU limit for the container.
  - **monitor** (object) - Monitoring configuration.
    - **port** (integer) - The port for monitoring.
    - **activityTracker** (object) - Activity tracking configuration.
      - **timeoutAfter** (integer) - Minutes until timeout.
      - **notifyAfter** (integer) - Minutes until warning notification.

### Response Example
```json
[
  {
    "name": "theia-ide",
    "image": "theiacloud/theia-cloud-demo:latest",
    "port": 3000,
    "minInstances": 0,
    "maxInstances": 10,
    "timeout": 30,
    "requestsMemory": "1Gi",
    "requestsCpu": "100m",
    "limitsMemory": "1200Mi",
    "limitsCpu": "2",
    "monitor": { "port": 8081, "activityTracker": { "timeoutAfter": 30, "notifyAfter": 25 } }
  }
]
```
```

--------------------------------

### Interact with Config Store REST API using curl

Source: https://context7.com/eclipse-theia/theia-cloud/llms.txt

These examples show how to check for Config Store availability, set a configuration value, and unset a configuration value using `curl` commands. The API is accessible at `/theia-cloud/config-store` within the session pod.

```bash
# Check config store availability (GET returns 200 if available)
curl -X GET http://localhost:3000/theia-cloud/config-store
```

```bash
# Set a config value (only writable, not readable via REST for security)
curl -X POST http://localhost:3000/theia-cloud/config-store \
  -H "Content-Type: application/json" \
  -d '{"key": "database_url", "value": "postgres://user:pass@host/db"}'
# Response: 204 No Content
```

```bash
# Unset a config value
curl -X POST http://localhost:3000/theia-cloud/config-store \
  -H "Content-Type: application/json" \
  -d '{"key": "database_url", "value": null}'
```

--------------------------------

### List Available App Definitions

Source: https://context7.com/eclipse-theia/theia-cloud/llms.txt

Retrieve a list of all registered AppDefinitionSpec objects for a given app ID using the GET /service/appdefinition/{appId} endpoint. This helps in understanding the available session configurations.

```bash
curl -X GET \
  https://service.theia-cloud.example.com/service/appdefinition/my-app-id \
  -H "Authorization: Bearer <access_token>"
# Response:
# [
#   {
#     "name": "theia-ide",
#     "image": "theiacloud/theia-cloud-demo:latest",
#     "port": 3000,
#     "minInstances": 0,
#     "maxInstances": 10,
#     "timeout": 30,
#     "requestsMemory": "1Gi",
#     "requestsCpu": "100m",
#     "limitsMemory": "1200Mi",
#     "limitsCpu": "2",
#     "monitor": { "port": 8081, "activityTracker": { "timeoutAfter": 30, "notifyAfter": 25 } }
#   }
# ]
```

--------------------------------

### Test Custom Operator with Nginx Server

Source: https://github.com/eclipse-theia/theia-cloud/blob/main/demo/dockerfiles/demo-operator-custom-template/README.md

Installs curl and tests the custom operator by accessing a hello world page served by an Nginx container on localhost:80.

```bash
apt install curl
curl localhost:80
```

--------------------------------

### POST /service — Launch Session

Source: https://context7.com/eclipse-theia/theia-cloud/llms.txt

The primary endpoint for dashboards. Atomically creates a workspace if needed and starts a session. Returns the URL path of the running session.

```APIDOC
## POST /service — Launch Session

### Description
The primary endpoint for dashboards. Atomically creates a workspace if needed and starts a session. Returns the URL path of the running session.

### Method
POST

### Endpoint
`/service`

### Parameters
#### Request Body
- **appId** (string) - Required - The ID of the application.
- **user** (string) - Required - The user initiating the session.
- **appDefinition** (string) - Required - The name of the AppDefinition to use.
- **ephemeral** (boolean) - Optional - If true, launches an ephemeral session without a persistent workspace.
- **timeout** (integer) - Optional - Session timeout in minutes.
- **label** (string) - Optional - A label for the workspace.
- **workspaceName** (string) - Optional - The name of an existing workspace to use.
- **env** (object) - Optional - Environment variables configuration.
  - **fromMap** (object) - Key-value pairs for environment variables.
  - **fromConfigMaps** (array) - List of ConfigMap names to load environment variables from.
  - **fromSecrets** (array) - List of Secret names to load environment variables from.

### Request Example
```json
{
  "appId": "my-app-id",
  "user": "alice@example.com",
  "appDefinition": "theia-ide",
  "ephemeral": true,
  "timeout": 5
}
```

### Response
#### Success Response (200)
- **string** - The URL path of the running session.

### Response Example
```json
"ws-alice-example-com-abc123.theia-cloud.example.com"
```
```

--------------------------------

### Build and Run Default Theia Cloud Operator

Source: https://github.com/eclipse-theia/theia-cloud/blob/main/java/operator/README.md

Commands to build and run the default Theia Cloud Operator. Ensure you have Maven installed for the build step.

```sh
mvn clean install
java -jar target/defaultoperator-1.3.0-SNAPSHOT-jar-with-dependencies.jar
```

--------------------------------

### List Active User Sessions

Source: https://context7.com/eclipse-theia/theia-cloud/llms.txt

Retrieve a list of all active IDE sessions for a specific user and app ID by calling GET /service/session/{appId}/{user}. This is useful for monitoring and managing user workspaces.

```bash
curl -X GET \
  "https://service.theia-cloud.example.com/service/session/my-app-id/alice%40example.com" \
  -H "Authorization: Bearer <access_token>"
# Response:
# [
#   {
#     "name": "session-alice-example-com-abc123",
#     "appDefinition": "theia-ide",
#     "user": "alice@example.com",
#     "workspace": "ws-alice-my-project",
#     "envVars": { "MY_VAR": "hello" }
#   }
# ]
```

--------------------------------

### Apply Global Certificate Configuration

Source: https://github.com/eclipse-theia/theia-cloud/blob/main/documentation/Install.md

Apply the global certificate configuration. Remember to replace 'example.com' with your actual host and 'letsencrypt-prod' with your chosen certificate issuer.

```bash
kubectl apply -f  ./documentation/platforms/global-certificate.yaml
```

--------------------------------

### Get Theia Cloud Helm Manifest

Source: https://github.com/eclipse-theia/theia-cloud/blob/main/documentation/Install.md

Retrieve and display the Kubernetes manifest generated by the 'theia-cloud' Helm release in the 'theia-cloud' namespace. Useful for verifying the installation.

```bash
helm get manifest theia-cloud -n theia-cloud
```

--------------------------------

### Build Theia Demo Application

Source: https://github.com/eclipse-theia/theia-cloud/blob/main/documentation/Building.md

Builds the Docker image for the basic Theia demo application.

```bash
docker build -t theia-cloud-demo -f demo/dockerfiles/demo-theia-docker/Dockerfile demo/dockerfiles/demo-theia-docker/.
```

--------------------------------

### Install Theia Cloud CRDs

Source: https://github.com/eclipse-theia/theia-cloud/blob/main/documentation/Install.md

Install the Custom Resource Definitions (CRDs) for Theia Cloud in the 'theia-cloud' namespace. The namespace will be created if it does not exist.

```bash
helm install theia-cloud-crds theia-cloud-remote/theia-cloud-crds  --namespace theia-cloud --create-namespace
```

--------------------------------

### Initialize, Plan, and Apply GKE Cluster

Source: https://github.com/eclipse-theia/theia-cloud/blob/main/terraform/terraform.md

Initialize Terraform, perform a dry run with 'terraform plan', and then apply the configuration to create a Theia Cloud cluster on Google Kubernetes Engine.

```bash
cd configurations/gke_getting_started

# download required providers
terraform init

# dry run
terraform plan
```

--------------------------------

### Build Theia Demo with Theia Activity Tracker

Source: https://github.com/eclipse-theia/theia-cloud/blob/main/documentation/Building.md

Builds the Docker image for the Theia demo application with the Theia Activity Tracker extension.

```bash
docker build -t theiacloud/theia-cloud-activity-demo-theia:latest -f demo/dockerfiles/demo-theia-monitor-theia/Dockerfile .
```

--------------------------------

### servicePost

Source: https://github.com/eclipse-theia/theia-cloud/blob/main/documentation/api/Apis/RootResourceApi.md

Launches a new session, creating a workspace if necessary, and returns the URL of the launched session.

```APIDOC
## POST /service

### Description
Launch a session and create a workspace if required. Responds with the URL of the launched session.

### Method
POST

### Endpoint
/service

### Parameters
#### Request Body
- **LaunchRequest** (LaunchRequest) - Required - The request object for launching a session.

### Response
#### Success Response (200)
- **String** - The URL of the launched session.
```

--------------------------------

### Run Application in Dev Mode

Source: https://github.com/eclipse-theia/theia-cloud/blob/main/java/conversion/org.eclipse.theia.cloud.conversion/README.md

Use this command to run the application in development mode, which enables live coding. Access the Dev UI at http://localhost:8080/q/dev/.

```shell
./mvnw compile quarkus:dev
```

--------------------------------

### Execute Native Executable

Source: https://github.com/eclipse-theia/theia-cloud/blob/main/java/service/org.eclipse.theia.cloud.service/README.md

Run the created native executable. The exact filename may vary based on the version.

```shell
./target/service-1.3.0-SNAPSHOT-runner
```

--------------------------------

### Package Application

Source: https://github.com/eclipse-theia/theia-cloud/blob/main/java/conversion/org.eclipse.theia.cloud.conversion/README.md

Package the application into a standard JAR file. Dependencies are copied to `target/quarkus-app/lib/` and the runnable JAR is `target/quarkus-app/quarkus-run.jar`.

```shell
./mvnw package
```

--------------------------------

### Create Native Executable

Source: https://github.com/eclipse-theia/theia-cloud/blob/main/java/conversion/org.eclipse.theia.cloud.conversion/README.md

Create a native executable for the application. This can be done directly or within a container.

```shell
./mvnw package -Pnative
```

```shell
./mvnw package -Pnative -Dquarkus.native.container-build=true
```

--------------------------------

### serviceSessionPerformanceAppIdSessionNameGet

Source: https://github.com/eclipse-theia/theia-cloud/blob/main/documentation/api/README.md

Get performance metrics.

```APIDOC
## GET /service/session/performance/{appId}/{sessionName}

### Description
Get performance metrics.

### Method
GET

### Endpoint
/service/session/performance/{appId}/{sessionName}
```

--------------------------------

### Get Session Performance

Source: https://context7.com/eclipse-theia/theia-cloud/llms.txt

Returns current CPU and memory usage of a session's pod.

```APIDOC
## GET /service/session/performance/{appId}/{sessionName} — Get Session Performance

### Description
Returns current CPU and memory usage of a session's pod.

### Method
GET

### Endpoint
/service/session/performance/{appId}/{sessionName}

### Parameters
#### Path Parameters
- **appId** (string) - Required - The application ID.
- **sessionName** (string) - Required - The name of the session.

### Response
#### Success Response (200)
- **cpuAmount** (string) - The amount of CPU used.
- **cpuFormat** (string) - The format of the CPU amount (e.g., 'm' for millicores).
- **memoryAmount** (string) - The amount of memory used.
- **memoryFormat** (string) - The format of the memory amount (e.g., 'Mi' for Mebibytes).

### Response Example
```json
{
  "cpuAmount": "42",
  "cpuFormat": "m",
  "memoryAmount": "256",
  "memoryFormat": "Mi"
}
```
```

--------------------------------

### Get Performance Metrics

Source: https://github.com/eclipse-theia/theia-cloud/blob/main/documentation/api/Apis/SessionResourceApi.md

Retrieves the current CPU and memory usage of a session's pod.

```APIDOC
## GET /service/session/performance/{appId}/{sessionName}

### Description
Get performance metrics

Returns the current CPU and memory usage of the session's pod.

### Method
GET

### Endpoint
/service/session/performance/{appId}/{sessionName}

### Parameters
#### Path Parameters
- **appId** (String) - Required - 
- **sessionName** (String) - Required - 

### Response
#### Success Response (200)
- **SessionPerformance** (SessionPerformance) - 

### Response Example
{
  "example": "SessionPerformance"
}
```

--------------------------------

### Build Theia Cloud Landing Page

Source: https://github.com/eclipse-theia/theia-cloud/blob/main/documentation/Building.md

Builds the Docker image for the Theia Cloud landing page using a specified Dockerfile.

```bash
docker build -t theia-cloud-landing-page -f dockerfiles/landing-page/Dockerfile .
```

--------------------------------

### GET /service/session/{appId}/{user} — List Sessions

Source: https://context7.com/eclipse-theia/theia-cloud/llms.txt

Lists all active sessions for a given user.

```APIDOC
## GET /service/session/{appId}/{user} — List Sessions

### Description
Lists all active sessions for a given user.

### Method
GET

### Endpoint
`/service/session/{appId}/{user}`

### Parameters
#### Path Parameters
- **appId** (string) - Required - The ID of the application.
- **user** (string) - Required - The user whose sessions are to be listed. This should be URL-encoded if it contains special characters like '@'.

### Request Example
```bash
curl -X GET \
  "https://service.theia-cloud.example.com/service/session/my-app-id/alice%40example.com" \
  -H "Authorization: Bearer <access_token>"
```

### Response
#### Success Response (200)
- **array** - A list of active session objects.
  - **name** (string) - The name of the session.
  - **appDefinition** (string) - The AppDefinition used for the session.
  - **user** (string) - The user associated with the session.
  - **workspace** (string) - The name of the workspace associated with the session.
  - **envVars** (object) - Environment variables set for the session.

### Response Example
```json
[
  {
    "name": "session-alice-example-com-abc123",
    "appDefinition": "theia-ide",
    "user": "alice@example.com",
    "workspace": "ws-alice-my-project",
    "envVars": { "MY_VAR": "hello" }
  }
]
```
```

--------------------------------

### Initialize and Apply Terraform Configuration

Source: https://github.com/eclipse-theia/theia-cloud/blob/main/terraform/ci-configurations/run-locally.md

Initializes the Terraform working directory and applies the infrastructure configuration, passing in the previously exported environment variables for ingress IP, matrix paths, ephemeral storage, and Keycloak.

```sh
terraform init
terraform apply \
    -var="ingress_ip=$INGRESS_HOST" \
    -var="use_paths=$MATRIX_PATHS" \
    -var="use_ephemeral_storage=$MATRIX_EPHEMERAL" \
    -var="enable_keycloak=$MATRIX_KEYCLOAK" \
    -auto-approve
```

--------------------------------

### Get Minikube IP Address

Source: https://github.com/eclipse-theia/theia-cloud/blob/main/java/operator/README.md

Command to retrieve the IP address of your Minikube instance, necessary for debugging the operator.

```sh
minikube ip
```

--------------------------------

### Download Minikube VirtualBox Driver

Source: https://github.com/eclipse-theia/theia-cloud/blob/main/terraform/terraform.md

Download the minikube virtualbox driver before invoking terraform. This is a prerequisite for using the VirtualBox driver with minikube.

```bash
minikube start --vm=true --driver=virtualbox --download-only
```

--------------------------------

### Get Session Performance

Source: https://context7.com/eclipse-theia/theia-cloud/llms.txt

Retrieves the current CPU and memory usage for a session's pod. Requires the `appId` and `sessionName`.

```bash
curl -X GET \
  "https://service.theia-cloud.example.com/service/session/performance/my-app-id/session-alice-example-com-abc123" \
  -H "Authorization: Bearer <access_token>"
# Response:
# {
#   "cpuAmount": "42",
#   "cpuFormat": "m",
#   "memoryAmount": "256",
#   "memoryFormat": "Mi"
# }
```

--------------------------------

### Execute Native Executable

Source: https://github.com/eclipse-theia/theia-cloud/blob/main/java/conversion/org.eclipse.theia.cloud.conversion/README.md

Run the generated native executable. The filename may vary based on the version.

```shell
./target/conversion-webhook-1.3.0-SNAPSHOT-runner
```

--------------------------------

### Configure Monitor in AppDefinition

Source: https://context7.com/eclipse-theia/theia-cloud/llms.txt

YAML configuration for the monitor in an AppDefinition, specifying the port and activity tracker settings. Ensure the port matches the environment variable set in launch.json.

```yaml
# AppDefinition with monitor configured to match the extension's port
spec:
  monitor:
    port: 8081                    # Must match THEIACLOUD_MONITOR_PORT
    activityTracker:
      notifyAfter: 25             # Warn user after 25 min inactivity
      timeoutAfter: 30            # Terminate session after 30 min inactivity
```

--------------------------------

### Build Theia Demo with VSCode Activity Tracker

Source: https://github.com/eclipse-theia/theia-cloud/blob/main/documentation/Building.md

Builds the Docker image for the Theia demo application with the VSCode Activity Tracker extension. This requires the base Theia Demo to be built first.

```bash
docker tag theiacloud/theia-cloud-demo:latest theiacloud/theia-cloud-demo
docker build -t theiacloud/theia-cloud-activity-demo:latest -f demo/dockerfiles/demo-theia-monitor-vscode/Dockerfile demo/dockerfiles/demo-theia-monitor-vscode/.
```

--------------------------------

### GET /service/{appId} — Ping (health check)

Source: https://context7.com/eclipse-theia/theia-cloud/llms.txt

Verifies the Theia Cloud service is reachable and that the caller is authenticated. Returns `true` on success.

```APIDOC
## GET /service/{appId} — Ping (health check)

### Description
Verifies the Theia Cloud service is reachable and that the caller is authenticated. Returns `true` on success.

### Method
GET

### Endpoint
`/service/{appId}`

### Parameters
#### Path Parameters
- **appId** (string) - Required - The ID of the application.

### Request Example
```bash
curl -X GET \
  https://service.theia-cloud.example.com/service/my-app-id \
  -H "Authorization: Bearer <access_token>"
```

### Response
#### Success Response (200)
- **true** (boolean) - Indicates the service is reachable and authenticated.

### Response Example
```json
true
```

## GET /service/admin/{appId} — Admin Ping (health check)

### Description
Verifies the Theia Cloud service is reachable and that the caller is authenticated, specifically checking admin roles.

### Method
GET

### Endpoint
`/service/admin/{appId}`

### Parameters
#### Path Parameters
- **appId** (string) - Required - The ID of the application.

### Request Example
```bash
curl -X GET \
  https://service.theia-cloud.example.com/service/admin/my-app-id \
  -H "Authorization: Bearer <access_token>"
```

### Response
#### Success Response (200)
- **true** (boolean) - Indicates the service is reachable and the caller has admin privileges.

### Response Example
```json
true
```
```

--------------------------------

### Enable Monitor Modules in VS Code launch.json

Source: https://context7.com/eclipse-theia/theia-cloud/llms.txt

Configure environment variables in VS Code's launch.json to enable specific monitor modules and set their ports. This is crucial for the monitor extension to function correctly.

```json
// VS Code launch.json — enable monitor modules via environment variables
{
  "name": "Run Extension",
  "env": {
    "THEIACLOUD_MONITOR_PORT": "8081",
    "THEIACLOUD_MONITOR_ENABLE_ACTIVITY_TRACKER": "true"
  }
}
```

--------------------------------

### Set Session Config Value

Source: https://context7.com/eclipse-theia/theia-cloud/llms.txt

Injects a configuration key/value pair into a running session. Use a `null` value to unset a key. Requires `@eclipse-theiacloud/config-store` to be installed.

```bash
# Set a config value (e.g., inject credentials into a running session)
curl -X POST \
  "https://service.theia-cloud.example.com/service/session/session-alice-example-com-abc123/config" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "appId": "my-app-id",
    "key": "github_token",
    "value": "ghp_xxxxxxxxxxxxxxxxxxxx"
  }'
# Response: 204 No Content

# Unset a config value
curl -X POST \
  "https://service.theia-cloud.example.com/service/session/session-alice-example-com-abc123/config" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "appId": "my-app-id",
    "key": "github_token",
    "value": null
  }'
# Response: 204 No Content
# Error codes: 403 (wrong user), 474 (session not found), 580 (config store not available)
```

--------------------------------

### Build Theia Cloud Landing Page Docker Image

Source: https://context7.com/eclipse-theia/theia-cloud/llms.txt

Commands to build the entire Node.js monorepo and then build the Docker image for the landing page. This is necessary for production deployment.

```bash
# Build the entire Node.js monorepo (landing page depends on common package)
cd node
npm ci
npm run build

# Build the Docker image for production
docker build -t theia-cloud-landing-page \
  -f dockerfiles/landing-page/Dockerfile .
```

--------------------------------

### Run Swagger UI Docker Container

Source: https://github.com/eclipse-theia/theia-cloud/blob/main/documentation/OpenAPI.md

Download and run the Swagger UI Docker image to explore OpenAPI specifications locally.

```bash
docker pull swaggerapi/swagger-ui
docker run -p 80:8080 swagger-ui
```

--------------------------------

### Build Theia Cloud Docker Images

Source: https://context7.com/eclipse-theia/theia-cloud/llms.txt

Builds Docker images for various Theia Cloud components from source. All commands should be executed from the repository root.

```bash
# REST Service
docker build --no-cache -t theia-cloud-service \
  -f dockerfiles/service/Dockerfile .

# Kubernetes Operator
docker build --no-cache -t theia-cloud-operator \
  -f dockerfiles/operator/Dockerfile .

# Landing Page (dashboard)
docker build -t theia-cloud-landing-page \
  -f dockerfiles/landing-page/Dockerfile .

# CRD Conversion Webhook
docker build -t theia-cloud-conversion-webhook \
  -f dockerfiles/conversion-webhook/Dockerfile .

# Bandwidth-limiting init container (wondershaper)
docker build -t theia-cloud-wondershaper \
  -f dockerfiles/wondershaper/Dockerfile .

# Demo Theia application
docker build -t theia-cloud-demo \
  -f demo/dockerfiles/demo-theia-docker/Dockerfile \
  demo/dockerfiles/demo-theia-docker/.

# Demo with VSCode Monitor extension (activity tracker)
docker tag theiacloud/theia-cloud-demo:latest theiacloud/theia-cloud-demo
docker build -t theiacloud/theia-cloud-activity-demo:latest \
  -f demo/dockerfiles/demo-theia-monitor-vscode/Dockerfile \
  demo/dockerfiles/demo-theia-monitor-vscode/.
```

--------------------------------

### Get Ingress Nginx Controller External IP

Source: https://github.com/eclipse-theia/theia-cloud/blob/main/documentation/Install.md

Retrieve the external IP address of the ingress-nginx-controller service. This IP is used to configure hostnames in the values file.

```bash
$ kubectl get svc --all-namespaces
```

--------------------------------

### Build Docker Images for Minikube

Source: https://github.com/eclipse-theia/theia-cloud/blob/main/terraform/ci-configurations/run-locally.md

Configures the local Docker environment to build images within Minikube and then builds all necessary Theia Cloud Docker images and demos, tagging them for Minikube CI E2E.

```sh
eval $(minikube docker-env)

docker build --no-cache -t theiacloud/theia-cloud-service:minikube-ci-e2e -f dockerfiles/service/Dockerfile .
docker build --no-cache -t theiacloud/theia-cloud-operator:minikube-ci-e2e -f dockerfiles/operator/Dockerfile .
docker build --no-cache -t theiacloud/theia-cloud-landing-page:minikube-ci-e2e -f dockerfiles/landing-page/Dockerfile .
docker build --no-cache -t theiacloud/theia-cloud-wondershaper:minikube-ci-e2e -f dockerfiles/wondershaper/Dockerfile .
docker build --no-cache -t theiacloud/theia-cloud-conversion-webhook:minikube-ci-e2e -f dockerfiles/conversion-webhook/Dockerfile .
docker build --no-cache -t theiacloud/theia-cloud-demo:latest -f demo/dockerfiles/demo-theia-docker/Dockerfile demo/dockerfiles/demo-theia-docker/.
docker tag theiacloud/theia-cloud-demo:latest theiacloud/theia-cloud-demo:minikube-ci-e2e
docker build --no-cache -t theiacloud/theia-cloud-activity-demo:minikube-ci-e2e -f demo/dockerfiles/demo-theia-monitor-vscode/Dockerfile demo/dockerfiles/demo-theia-monitor-vscode/.
docker build --no-cache -t theiacloud/theia-cloud-activity-demo-theia:minikube-ci-e2e -f demo/dockerfiles/demo-theia-monitor-theia/Dockerfile .
```

--------------------------------

### Get Keycloak Access Token

Source: https://github.com/eclipse-theia/theia-cloud/blob/main/terraform/test-configurations/test.md

Obtain a Bearer token from Keycloak for authenticating REST API calls. This command uses `curl` and `jq` to retrieve the token for a test user.

```bash
curl -s --insecure --request POST \
  --url https://$(minikube ip).nip.io/keycloak/realms/TheiaCloud/protocol/openid-connect/token \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=password \
  --data client_id=theia-cloud \
  --data username=foo \
  --data password=foo | jq -r '.access_token'
```

--------------------------------

### Build Theia Cloud Wondershaper

Source: https://github.com/eclipse-theia/theia-cloud/blob/main/documentation/Building.md

Builds the Docker image for the Theia Cloud wondershaper, which can be used for network bandwidth limiting.

```bash
docker build -t theia-cloud-wondershaper -f dockerfiles/wondershaper/Dockerfile .
```

--------------------------------

### Create Workspace

Source: https://context7.com/eclipse-theia/theia-cloud/llms.txt

Creates a new persistent workspace for a user. The response returns the created `UserWorkspace` object.

```bash
curl -X POST \
  https://service.theia-cloud.example.com/service/workspace \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "appId": "my-app-id",
    "user": "alice@example.com",
    "appDefinition": "theia-ide",
    "label": "New Workspace"
  }'
# Response:
# {
#   "name": "ws-alice-new-workspace-xyz",
#   "label": "New Workspace",
#   "appDefinition": "theia-ide",
#   "user": "alice@example.com",
#   "active": false
# }
```