From fce8d9964b2f91686ad5fabf9dd01e7aff9b7b8a Mon Sep 17 00:00:00 2001 From: Iliyan Velichkov Date: Thu, 4 Jun 2026 15:09:57 +0300 Subject: [PATCH 1/3] Add CLAUDE.md guidance file Document the project as a Dirigible Terminal-over-HTTP distribution, build/run/test commands, Spring profile wiring, and conventions for future Claude Code instances. Co-Authored-By: Claude Opus 4.8 (1M context) --- CLAUDE.md | 81 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 81 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..ae40835 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,81 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## What this is + +`codbex-theia` is a stripped-down distribution of [Eclipse Dirigible](https://github.com/eclipse/dirigible) packaged as a Spring Boot application. Despite the name, it does **not** bundle the Eclipse Theia IDE — it ships only the **Terminal-over-HTTP** standard components (and supporting IDE/git/console UI). The intended use is browser-based shell access into a target environment such as a Kubernetes pod. + +The application is essentially a thin assembly layer: nearly all functionality comes from `org.eclipse.dirigible:dirigible-components-*` dependencies declared in `application/pom.xml`. There is very little hand-written Java here — understand the codebase by understanding *which Dirigible components are included* and *how Spring profiles wire them up*, not by reading local source. + +## Module layout + +Maven multi-module project under parent `com.codbex.platform:codbex-platform-parent` (the parent defines build profiles, plugin config, and dependency versions — it is external, not in this repo): + +- `application/` — the Spring Boot app. `TheiaApplication` is the entry point; it scans `org.eclipse.dirigible` and excludes the default JDBC/JPA autoconfiguration (Dirigible manages datasources itself). Also contains the `Dockerfile`. +- `branding/` — Dirigible branding resources (logo, favicon, `branding.js`) served under `/services/web/ide-branding/`. Packaged as a jar and consumed by `application`. +- `integration-tests/` — Selenium/browser-driven integration tests built on `dirigible-tests-framework` / `dirigible-tests-base`. No production code. + +## Build & run + +All commands run from the repo root. Maven profiles (`quick-build`, `unit-tests`, `integration-tests`, `tests`, `format`) come from the platform parent. + +```shell +mvn -T 1C clean install -P quick-build # build the jar, skip tests +mvn clean install -P unit-tests # unit tests +mvn clean install -P integration-tests # integration tests (browser-driven) +mvn clean install -P tests # all tests +mvn verify -P format # format the code — run before committing +``` + +Run the built jar (note the required `--add-opens` flags — the app will misbehave without them): + +```shell +java --add-opens=java.base/java.lang=ALL-UNNAMED \ + --add-opens=java.base/java.lang.reflect=ALL-UNNAMED \ + --add-opens=java.base/java.nio=ALL-UNNAMED \ + -jar application/target/codbex-theia-*.jar +``` + +Docker (build the jar first): + +```shell +cd application && docker build . --tag ghcr.io/codbex/codbex-theia:latest +docker run --name theia -p 80:80 ghcr.io/codbex/codbex-theia:latest +``` + +The Docker image is based on `amazoncorretto:21-alpine` and installs `ttyd`, `nodejs`/`npm`, `esbuild`, `typescript`, and `git` — these are runtime requirements of the terminal and JavaScript engine components. + +### Running a single test + +Standard Maven, but bind to the right profile so the surrounding config (datasource, etc.) is active: + +```shell +mvn test -P unit-tests -pl application -Dtest=TheiaApplicationTest +mvn verify -P integration-tests -pl integration-tests -Dit.test=TheiaTerminalIT +``` + +## Access + +- App: http://localhost:80 — default login `admin` / `admin` +- Swagger UI: http://localhost/swagger-ui/index.html + +## Spring profiles (important) + +The app is driven by Spring profiles, not by the small amount of local code. `application.properties` activates `common,app-default` by default. To enable a specific Dirigible security/deployment mode, add its profile explicitly alongside `common` and `app-default`, e.g.: + +``` +SPRING_PROFILES_ACTIVE=common,snowflake,app-default +``` + +Security backends are pluggable via the included components: `basic` (default), `keycloak`, `cognito`, `snowflake`, `client-registration`. Activate the matching profile to switch. + +## Configuration + +- `application/src/main/resources/dirigible.properties` — Dirigible product config. Notable: `DIRIGIBLE_MULTI_TENANT_MODE=false`, `DIRIGIBLE_PRODUCT_TYPE=terminal`, `DIRIGIBLE_HOME_URL=services/web/ide-terminal/` (the terminal is the landing page). `${project.version}` / `${git.commit.id}` are filled at build time via resource filtering. +- `application-app-default.properties` — sets `server.port=80`. + +## Conventions + +- Java source files carry the EPL-2.0 license header (see any existing `.java` file). New files should reuse it verbatim. +- This repo is released on a version-bump cadence: commits like "version set to X for release" / "version set to Y-SNAPSHOT for development" are made by the release pipeline (`.github/workflows/release.yaml`) — do not hand-edit versions for normal work. From 5c943a5c53768ad32af47e9412fae41e4e5c3dcb Mon Sep 17 00:00:00 2001 From: Iliyan Velichkov Date: Thu, 4 Jun 2026 15:22:24 +0300 Subject: [PATCH 2/3] Add codbex product family context to CLAUDE.md Document that theia is the terminal-only member of the codbex product family (Atlas, Helios, Hades, etc.), each a Dirigible-based distribution scoped to a use case. Helps clarify what belongs in this repo. Co-Authored-By: Claude Opus 4.8 (1M context) --- CLAUDE.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index ae40835..c02b5e1 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -8,6 +8,10 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co The application is essentially a thin assembly layer: nearly all functionality comes from `org.eclipse.dirigible:dirigible-components-*` dependencies declared in `application/pom.xml`. There is very little hand-written Java here — understand the codebase by understanding *which Dirigible components are included* and *how Spring profiles wire them up*, not by reading local source. +### Product family + +codbex-theia is one of a family of codbex products (see https://www.codbex.com/products/), each a Dirigible-based distribution scoped to a specific use case — e.g. **Atlas** (full development platform), **Helios** (API development), **Hades** (database management), **Hyperion** (BPMN), **Iapetus** (Apache Camel integration), **Rhea** (model-driven), **Phoebe** (Apache Airflow workflows). theia is the minimal, terminal-only member: it strips the platform down to shell access. This is why `dirigible.properties` sets `DIRIGIBLE_PRODUCT_TYPE=terminal`. When deciding what belongs in this repo, keep that scope in mind — broader IDE/engine features live in the larger products, not here. + ## Module layout Maven multi-module project under parent `com.codbex.platform:codbex-platform-parent` (the parent defines build profiles, plugin config, and dependency versions — it is external, not in this repo): From e2f1fa711728341f14f8b0d5beee44a25a5f5601 Mon Sep 17 00:00:00 2001 From: Iliyan Velichkov Date: Thu, 4 Jun 2026 15:24:46 +0300 Subject: [PATCH 3/3] Scope product context to theia only Drop the enumeration of sibling codbex products; keep only theia's own scope (terminal-only shell access). Co-Authored-By: Claude Opus 4.8 (1M context) --- CLAUDE.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index c02b5e1..d8f6399 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -8,9 +8,9 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co The application is essentially a thin assembly layer: nearly all functionality comes from `org.eclipse.dirigible:dirigible-components-*` dependencies declared in `application/pom.xml`. There is very little hand-written Java here — understand the codebase by understanding *which Dirigible components are included* and *how Spring profiles wire them up*, not by reading local source. -### Product family +### Product scope -codbex-theia is one of a family of codbex products (see https://www.codbex.com/products/), each a Dirigible-based distribution scoped to a specific use case — e.g. **Atlas** (full development platform), **Helios** (API development), **Hades** (database management), **Hyperion** (BPMN), **Iapetus** (Apache Camel integration), **Rhea** (model-driven), **Phoebe** (Apache Airflow workflows). theia is the minimal, terminal-only member: it strips the platform down to shell access. This is why `dirigible.properties` sets `DIRIGIBLE_PRODUCT_TYPE=terminal`. When deciding what belongs in this repo, keep that scope in mind — broader IDE/engine features live in the larger products, not here. +codbex-theia is a codbex product (see https://www.codbex.com/products/): a Dirigible-based distribution scoped to a single use case — minimal, terminal-only shell access. It strips the platform down to that, which is why `dirigible.properties` sets `DIRIGIBLE_PRODUCT_TYPE=terminal`. When deciding what belongs in this repo, keep that scope in mind — broader IDE/engine features are out of scope here. ## Module layout