Platform overview¶

This page orients developers: what the platform is, how the repository is organised, what gets built, and how releases work.

The platform in one loop¶

1. An administrator defines a site in the Hub UI or through the Hub API.
2. The Hub writes the desired state as a Site custom resource (apiVersion: operators.ecmwf.int/v2, Custom Resource Definition (CRD) sites.operators.ecmwf.int) in Kubernetes.
3. The operator reconciles each Site resource into running Site Pods plus the Service, persistent volume claim (PVC), Secret, ConfigMaps, and route — all named after the Site id.
4. Users and automation reach the site through the site URL and the Site API.

The Site resource is the only source of truth. 03-domain-model describes it; 09-lifecycle-and-reconciliation describes the reconciliation; 02-architecture shows how the pieces connect.

Repository layout¶

Python workspace¶

The four Python packages share one uv workspace (core, hub, operator, site, listed in the root pyproject.toml). From the repository root:

uv venv --python 3.13        # Makefile default: UV_PYTHON = 3.13
uv sync --all-packages --all-groups

make init-workspace runs the same commands. make test refuses to run unless lua is on PATH (the proxy Lua modules are unit-tested), then runs unittest discover over each package's Python tests and go test for the Go API; see 20-testing.

Built images¶

make publish-images IMAGE_TAG=<tag> builds and pushes these images to $(SITES_PRIVATE_REGISTRY)/$(SITES_PRIVATE_REGISTRY_PROJECT) (defaults eccr.ecmwf.int and sites-oss):

There is no site-custom image: custom applications supply their own. The platform Dockerfiles build from a pinned uv + Python 3.12 slim base image, while the local workspace standardises on 3.13.

Chart defaults are separate: images.hub|core|operator.repository point to eccr.ecmwf.int/sites/..., while this repository publishes to $(SITES_PRIVATE_REGISTRY)/$(SITES_PRIVATE_REGISTRY_PROJECT). Set the chart repository values when you deploy images published from this repository.

Monorepo lockstep versioning¶

One release version covers:

• The Python packages sites-core, sites-hub, sites-operator, sites-site (each package's __init__.__version__).
• The Helm chart version and appVersion, and the chart's default images.tag.
• The site.version setting used for site application images.

The root VERSION file is the single source. The chart injects images.tag into the platform configuration as site.version, so site application images follow the chart release. images.redis.tag is the only independent image tag.

make check-lockstep-version (utilities/release/check-lockstep-version.sh) compares the four package versions, the chart version and appVersion, and images.tag against VERSION, reports every mismatch, and exits non-zero when any differ. CI runs it in the release workflow. Helpers:

./utilities/release/set-version.sh 2.6.0
./utilities/release/check-lockstep-version.sh
# or: make set-version NEW_VERSION=2.6.0

Release flow¶

1. Set the version: make set-version NEW_VERSION=<version>.
2. Add a ## Version <version> section to CHANGELOG.md. The GitHub release uses this text (utilities/release/changelog-notes.sh).
3. Merge into main and wait for the CI workflow to pass.
4. Start the Release workflow from main.

The Release workflow checks the CI gate result for the target commit, re-runs the repository tests, checks the lockstep versions, and refuses an existing tag. The tag-and-release job then creates and pushes the tag with a deploy key that bypasses the organisation tag-protection ruleset, opens the GitHub release, and calls the Publish workflow. Publish verifies that the tag matches VERSION, builds and pushes the images and the chart to oci://eccr.ecmwf.int/sites-oss/ecmwf-sites (the pushed chart copy carries images.tag set to the release tag), and a separate job installs sitesctl from the Sites CLI repository (get.ecmwf.int) to build and upload this documentation. make release is the same path locally: it checks lockstep and calls make publish with the version read from VERSION. Override the registry with SITES_PRIVATE_REGISTRY and SITES_PRIVATE_REGISTRY_PROJECT. The full trigger, permission, and gate model is in 15-ci-cd.

Endpoint anatomy¶

The Hub owns the platform paths under the public host:

• /hub/... — Hub UI pages.
• /hub/api/v1/... and /hub/api/v2/... — Hub API.
• /hub/admin/... — Hub administration pages.
• /hub/error/page/<code>/ — shared error pages.
• /favicon.svg, /favicon.ico — the configured platform icon (/favicon.ico redirects to the versioned SVG; see 16).
• Root-level redirects: the redirects blueprint (prefix /) serves legacy paths such as /error/page/<code>/ and redirects them to their /hub equivalents.

Each site owns the paths under its own prefix /<space>/<site>/ (the owner replaces the space when the site has none):

• /<space>/<site>/... — site content and listing, served by the site proxy.
• /<space>/<site>/s/api/v2/... — authenticated Site API.
• /<space>/<site>/s/api/v2/pub/... — anonymous read API on public sites.
• /<space>/<site>/s/admin/, s/dav/, s/s3/ — optional site applications.
• /<space>/<site>/s/healthz — NGINX stub status; allowed to the Site's own loopback probe and to trusted_ips only.
• /s/metrics — Prometheus text from the Lua metrics module. Note this location is not under the site prefix. ServiceMonitors scrape it through the Site Service port (4180); OAuth2 Proxy skips authentication for it only while the metrics integration is enabled, and the proxy then requires a trusted client IP. See 21-observability.

Paths are identical in both routing modes; see 14-routing. A user-facing guide to these paths, with examples, is in end-user: Understanding Sites URLs.

Behaviour requirements¶