The installable EduIDE platform. Two charts, published as OCI artifacts to
ghcr.io/eduide/charts.
| Chart | Installed | Owns |
|---|---|---|
eduide-cluster |
once per cluster | CRDs, conversion webhook, ClusterRoles, cert-manager issuers |
eduide |
once per environment | operator, REST service, landing page, routes |
# once per cluster
helm install eduide-cluster oci://ghcr.io/eduide/charts/eduide-cluster \
--version <chart version> -n eduide-system --create-namespace
# once per environment
helm install eduide oci://ghcr.io/eduide/charts/eduide \
--version <chart version> -n eduide-test1 -f my-values.yamlBoth charts always carry the same version. Take <chart version> from the
releases page; pass a
prerelease such as 3.0.0-rc.3 explicitly, because helm skips prereleases
otherwise. docs/charts.md explains why the
split exists and what it is safe to change.
A bare --version <chart version> with no overrides pins every image. Nothing floats.
| Value | Source repository | Default |
|---|---|---|
versions.ide |
EduIDE (the IDE images) | empty → the chart's appVersion |
versions.cloud |
EduIDE-Cloud (operator, REST service) | see charts/eduide/values.yaml |
versions.landingPage |
EduIDE-Landing-Page | see charts/eduide/values.yaml |
The three release on their own cadence, so each has its own knob and an
override names exactly one. A blanket tag would be wrong: a pull request only
builds the images of the repo it came from, so pointing everything at pr-451
puts the rest of the namespace into ImagePullBackOff.
appDefinitions.catalog holds the IDE images EduIDE officially releases.
An installation adds its own apps or changes a catalog entry under
appDefinitions.apps, and picks what it offers with appDefinitions.enabled.
An empty enabled (the default) offers every definition, catalog and apps
alike:
appDefinitions:
enabled: # names from the catalog or from apps
- java-25-standalone
- python
- haskell
apps:
python: # merged over the catalog entry
limitsMemory: 4000M
haskell: # your own image
image: registry.example.edu/ide/haskell:2.1.0 # a tag or digest is used as given
limitsMemory: 4000M
landingPage:
label: Haskell # omit landingPage to deploy it but hide it
image: theia-logo.png # a logo the landing page ships, or a path starting with /Each app is appDefinitions.defaults, then its catalog entry, then its apps
entry. A bare repository such as eduide/java-17 gets the tag from
versions.ide. apps.<name>: null removes an app. A name in enabled with
no definition is skipped, and helm install or helm upgrade prints a warning
naming it.
That one merged list drives the AppDefinition custom resource, the landing
page's app list, and the set of images preloaded onto every node. It used to be
three hand-maintained lists across two repositories, the preload one addressed
by array index - which is how production came to offer one app while
preloading everything except it.
scripts/test-app-consistency.sh asserts the three agree, and CI runs it.
Every language comes in two editions, both with Scorpio and the data bridge:
| AppDefinition | Image | Offered on the landing page | Started from |
|---|---|---|---|
<lang> (no suffix) |
eduide/<lang>-artemis |
no (visible: false) |
Artemis, by name (?appDef=) |
<lang>-standalone |
eduide/<lang>-standalone |
yes | the landing page, or an external start |
<lang> is one of java-17, java-25, python, javascript, c, rust,
go. The Artemis edition has the Artemis extension; standalone does not.
Artemis stores the AppDefinition name per exercise, which is why the Artemis
names stay without a suffix.
landingPage.buildSystems of a -standalone app lists the ids of the project
templates its image carries (maven, gradle, make, bazel, python,
node, web, cargo, go). One entry starts it directly, several show the
build system step, none starts an empty workspace. The id is the template
folder in the image; the release train checks every id against the image's
templates-<image>.json (scripts/check-build-systems.sh). An installation
offers fewer templates by overriding buildSystems in its apps.
landingPage.ephemeral (true or false) decides per app whether its sessions
are temporary. Unset, the app follows landingPage.ephemeralStorage. The
privacy page states the workspace as persistent when any rendered app is
persistent, hidden Artemis apps included: an Artemis start launches them with
their own persistence.
An installation's own image needs a full path and tag, because the chart
prefixes imageRegistry to anything that is not one:
registry.example.edu/ide/java-25:1.0.0. Derive it FROM a -standalone image.
Old image names are frozen at their last tag, so 3.0.0 only works with EduIDE
2.0.0. The *-templates apps are renamed; list the new names in
appDefinitions.enabled. The render fails while enabled still names an old
one, because deleting an AppDefinition garbage-collects its live sessions:
| Before | Now |
|---|---|
java-17-templates |
java-17-standalone |
java-25-templates |
java-25-standalone |
c-templates |
c-standalone |
java-17, java-25, python, javascript, c |
same names, image <lang>-artemis, no longer offered on the landing page |
| - | new: rust, go and every <lang>-standalone |
Before you deploy:
- Maintenance window. Removing or renaming an app terminates its live sessions (the operator owns the session Deployments and warm pool volumes through the AppDefinition). The new images also replace every running session.
- Warm pools.
minInstancesof a renamed app does not move. Set it on the new app and patch the live AppDefinition, which the chart does not reset. pythonandjavascriptare hidden now. An installation that offered them on the landing page switches topython-standaloneandjavascript-standalone.landingPage.appDefinitiondefaults tojava-17: the app for links without?appDef=, which is the Artemis start. The render fails when it is not an app the installation renders, so update an override that still names a*-templatesapp.- Explicit
enabled. An emptyenablednow offers and preloads 14 images (two editions of seven languages) on every node. List what your courses use. - Persistence. Template sessions were persistent before and follow
landingPage.ephemeralnow, so a workspace saved under the old template app is no longer reachable and is reaped by the garbage collector. SetlandingPage.ephemeral: falseon the-standaloneapps to keep them persistent, and bumpversions.landingPageto a release that reads it.
Environment configuration for the TUM installations lives in EduIDE-deployment, not here.
Nothing releases on push to main. A release is a reviewed pull request
followed by a manual run of release.yml. The release skill
(.claude/skills/release/SKILL.md) walks through it: it proposes the version,
checks the EduIDE components this repository pins against their latest
releases, writes the CHANGELOG section and opens the pull request.
Chart changes need no version bump. They go under ## [Unreleased] in
CHANGELOG.md; the version moves in the release pull request only.
Both charts, one version; appVersion and the versions.* pins at the
component releases you want to ship:
# charts/eduide/Chart.yaml AND charts/eduide-cluster/Chart.yaml
version: 2.3.0docker run --rm -v "$PWD/charts:/helm-docs" -u "$(id -u)" jnorwood/helm-docs:v1.14.2Move the ## [Unreleased] entries under ## [eduide 2.3.0] - YYYY-MM-DD,
open the PR, let CI run, get it reviewed, merge.
gh workflow run release.yml -R EduIDE/EduIDE-Helm -f version=2.3.0It then, in this order:
- checks that the IDE, Cloud (operator, service, conversion webhook) and landing page images the charts pin exist and are multi-arch, and that the chart versions are not published yet
- validates the version (semver, newer than the last release, matches both
Chart.yamlfiles, CHANGELOG section exists) and creates a draft GitHub Release from the CHANGELOG section - publishes both charts to
oci://ghcr.io/eduide/chartsand adds what the version pins to the release notes - verifies both charts can be pulled
- publishes the release, which creates the
vX.Y.Ztag
The tag appears last on purpose: a missing image or a failed push leaves a draft, not a tag for charts that were never published.
A release deploys nothing. In EduIDE-deployment:
# environments/prod-tum/env.yaml
spec:
platform:
chartVersion: 2.3.0 # the only line that changesMerge that, then run Deploy environment. Production is never deployed
automatically.
Run release.yml with -f version=2.3.0-rc.1, from any branch: same pipeline,
same registry, marked as a prerelease on GitHub. The version files are not
checked for a release candidate; the charts are stamped with it. Consume with
an explicit --version; never --devel.
| Thing | Form | Example |
|---|---|---|
| git tag | vX.Y.Z |
v2.3.0 |
chart version |
X.Y.Z |
2.0.0 |
chart appVersion |
the EduIDE IDE image version | 1.2.0 |
| image tag | X.Y.Z |
1.2.0 |
appVersion is the tag of the IDE images, so a chart says exactly which IDEs it
runs. The operator, REST service and landing page carry their own versions in
versions.cloud and versions.landingPage, because they release on a different
cadence and a one-line landing page fix should not rebuild 14
multi-gigabyte IDE images.
The chart version is the platform version and is what an environment pins.
[ ] both Chart.yaml files at the same `version`
[ ] `appVersion` set to the EduIDE release the IDE images were published under
[ ] `versions.cloud` and `versions.landingPage` set to their releases
[ ] scripts/test-app-consistency.sh passes (no floating tags, three consumers agree)
[ ] helm-docs run, READMEs committed
[ ] CHANGELOG section `## [eduide X.Y.Z]` written
[ ] release PR reviewed and merged
[ ] release.yml run
[ ] chartVersion bumped in EduIDE-deployment for the environments to move
| Symptom | Cause | Fix |
|---|---|---|
version is 'X', expected 'Y' |
release PR missed a Chart.yaml | bump both charts |
missing ghcr.io/... |
a component build failed or is not released | check that repository's Actions, release it first |
is not multi-arch |
one architecture failed | re-run that repository's build |
Tag vX.Y.Z already exists / already published |
version already used | pick the next one, tags are immutable |
No '## [eduide X.Y.Z]' section |
CHANGELOG not moved in the release PR | fix it in a new PR |
- cert-manager - certificate management, including Let's Encrypt. Install.
- Envoy Gateway with the Gateway API CRDs. The GatewayClass name must match
gateway.className(defaultenvoy).
helm lint charts/eduide charts/eduide-cluster
./scripts/render-envs.sh /tmp/out # renders every real environmentCI also renders the PR base and head and posts the diff. For a refactor the expected result is an empty diff — that is the acceptance criterion, not "it still lints".
See AGENTS.md for the things that catch people out, and
.claude/skills/chart-change.md for the loop to follow when editing a template.