For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /reference/docs/decisions/0043-themelio-compat-service.md.

0043 — The retained Themelio as the themelio-compat service

Status: Proposed. Implements stage 4 of 0040; the implementation is in DD-0043. Decision 0045 amends decisions 1, 3 and 6: the service is installed on every dev box, and its images are built in the cluster. Date: 14 October 2026.

Context

The retained Themelio (web, GitLab root actor and Kubernetes root actor) lives in compat/themelio, relocated with its history under decision 0042. It is not the new themelio service in services/themelio, one of the new platform's five services, deployed from gitops/manifests/pharos with the rest of the platform. That service has no bounded contexts yet and writes nothing. The retained Themelio needs PostgreSQL and Valkey, signs in through an OIDC provider, provisions users and projects in GitLab and synchronises identities with Waldur. Through its actors, it acts with administrator rights in both. Decision 0041 installs GitLab and Waldur as Argo CD services.

Decision

  1. The retained Themelio is the themelio-compat service. The name keeps it apart from the new themelio service. Every dev box installs it beside the new platform until the new Themelio replaces it; it then becomes optional again (amended by 0045). Its Application is gitops/apps/base/themelio-compat.yaml, with the path set by the environment's overlay, and the catalogue serves themelio-compat.pharos. It runs in the themelio-compat namespace of the services project, on wave 4, after GitLab and Waldur.

  2. Its manifests are Kustomize, as in the legacy GitOps. They are plain manifests in gitops/manifests/themelio-compat/base, and overlays/devbox adds the public origins, as legacy/gitops/manifests/themelio does per environment. The service owns its state: PostgreSQL 17 and Valkey 8.1, both pinned by digest, and Secrets generated once in the namespace. An administrator Job creates the migrator and runtime roles, and a migration Job alone runs DDL. The actors and the web never receive the PostgreSQL administrator password.

  3. Images are built from the delivered commit. The three targets of compat/themelio/Dockerfile are built in the cluster, as every platform image is under 0045, and the root passes their digests to the Application's kustomize.images. Without them no container names a usable image. Nothing is published.

  4. Sign-in uses the shared AAI through the existing pharos-control-plane client, which gains Themelio's callback. make deploy delivers the client and the AAI CA. Themelio reaches GitLab, Waldur and the issuer through the edge. It requests only scopes the AAI defines.

  5. Waldur's Identity Bridge is enabled with the service. Themelio creates and updates Waldur users through it, and Waldur keeps it off by default. The apps set the Constance setting on Waldur's own Application, so it appears in Git.

  6. Provider tokens are a dev-box exception. The GitLab root actor needs a root token with api and sudo, and the web needs a Waldur staff token. This contradicts the rule that administrator credentials never enter runtime application containers, so it is limited:

    • only on dev boxes;
    • each token is given only to the workload that uses it;
    • the GitLab token belongs to root, and the Waldur token to a dedicated staff user themelio-compat without a password;
    • make deploy creates both tokens while Argo installs the services, after GitLab and Waldur are healthy, and passes their values only on stdin;
    • both tokens expire after 30 days, and make deploy rotates them when fewer than seven days remain.

    The exception ends when the owning capabilities move to the new platform. Staging and production keep the rule.

  7. Both run side by side during the migration. They share GitLab, Waldur and the AAI, but not databases. Each operation has one writer at a time and moves from themelio-compat to the new services with an explicit handover. When the last one has moved, themelio-compat and its exception are removed.

Consequences

Positive: the retained Themelio runs beside the new platform on the same edge, AAI, GitLab and Waldur, with the same delivery and drift control. Every dev box has the retained behaviour while the new Themelio is built. Its layout matches the legacy GitOps the team already uses.

Negative: every dev box holds administrator tokens in two runtime containers until the new Themelio replaces the service. Image builds add minutes to the first deploy of each change to compat/themelio. The retained web pins Next.js 15.5.7, whose loopback rewrite breaks hosts such as *.127.0.0.1.sslip.io; the image build patches it and stops on any other version. Action execution (spaces, inference services, Slurm jobs) needs execution namespaces with sidecar injection and is not enabled. Waldur keeps the Identity Bridge on if the service is later removed.

Neutral: Themelio's legacy browser polling remains registered in docs/compat-exceptions.json.

Development provider sharing is updated by decision 0048. Consumer database identities and broker scopes remain separate.

Page source

Source snapshot · Revision f928834c8.