# 0043 — The retained Themelio as the `themelio-compat` service

Status: Proposed. Implements stage 4 of [0040](0040-platform-layout.md); the
implementation is in [DD-0043](../dd/0043-themelio-compat-service.md).
[Decision 0045](0045-development-loop.md) 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](0042-legacy-source-relocation.md).
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](0041-gitlab-waldur-services.md) 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](0045-development-loop.md)). 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](0045-development-loop.md), 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](0048-shared-development-infrastructure.md). Consumer database identities and broker scopes remain separate.