[antonkatsapau]

Summary

White-label theming kit and admin guide. A DevOps engineer fills in one theme package (product name, colours, fonts, logos, links, an optional email block and an optional Keycloak block) and runs apply-theme. The script validates the package, renders values for the platform Helm releases, and applies them with pinned helm upgrade --reuse-values calls plus rollout restarts. --render-only writes the files for GitOps pipelines.

Changes

• Guide: docs/admin/configuration/white-label/index.md and package-reference.md, with a sidebar entry. Two FAQ entries. The EMAIL_FROM_NAME row in api-configuration.md shows the new empty default and the fallback.
• Kit: the apply-theme script, the theme-package.yaml template, a JSON schema, the example acme package and an example GitHub Actions workflow.
• Colours: every token has a required dark and light value. Both are written to brand.css, under html.codemieDark and html.codemieLight.
• Platform emails (optional email block): sender name, signature, a five-colour palette, one logo and message texts for the five platform emails. Bad fields fail before any file is written or any helm or kubectl call. The logo is stored as binaryData and mounted as a directory with no chart change. The checksum covers the logo bytes.
• Keycloak login and email theme (optional keycloak block): a theme name, an optional SMTP block (secret references only) and an HTTPS logo URL for the Keycloak email. With the block present, one run:
  1. validates every input and collects all errors;
  2. renders the child theme values, the realm values and the stale-key values;
  3. runs a read-only preflight on the Keycloak release;
  4. applies the UI, API, Keycloak (helm --wait) and proxy releases in that order, each in its own namespace.
• Gradients and tokens (added after the stand test): the optional effects.gradients (default or none); with none the UI removes every background gradient, and the kit makes two-colour gradients single-colour (the -to value follows -from). The guide lists the tokens for the side panels, button borders, the product tour, links, the "NEW" tag and the gradient fills.
• Product name in visible text (EPMCDME-16332): a new guide section, "Where the Product Name Appears" in index.md, and a corrected product.name row in package-reference.md. It lists the texts that follow the brand name (UI texts, the chat label "{product name} Thoughts", platform emails, Keycloak), the texts that do not change (pre-built assistants, katas, documents, release notes, user-created assistants, the support address, the default tab title), the fallbacks, and the API restart after a brand change.
• New flags: --chart-keycloak, --chart-proxy, --release-keycloak, --release-proxy, --namespace-keycloak, --namespace-proxy, --keycloak-timeout and --no-keycloak.
• Review fixes (28 October): realm SMTP keys are written only with a full smtp block (an empty keycloak.smtp: {} clears them); the example workflow takes the Keycloak and proxy inputs; an unparsable extraVolumes string stops the run; arguments after the assets directory are rejected; the UI asset size check covers the 1 MiB Helm release Secret and fontFaceCSS has a length cap; the smoke check handles names with &; restarts find workloads by release label. Each has bats tests.
• Tests and CI: a bats suite (167 tests) with an extended Helm stub, a contract-drift test and the CI job white-label-kit-tests.yml.

Behaviour changes to note

• The backend EMAIL_FROM_NAME default changes from CodeMie to empty, and platform emails use neutral wording when no brand is set. The guide has the details.
• Without a keycloak block, the output and the Helm calls are the same as before.

Operational notes (also in the guide)

• A full redeploy of the platform charts without the brand values resets the brand to the chart defaults.
• Release the parent theme image first. A child theme on an old parent image shows the old look.
• The sender name for Keycloak emails works only together with a full SMTP connection.
• The vendor parent theme must stay installed. The child theme inherits it.
• A theme change restarts the single Keycloak replica, which gives a short login outage.

Scope note

Pairing the kit with a specific release is out of scope for this change. No Release Notes entry is added.

Testing

• Kit bats suite: 167 passed on macOS and in an Ubuntu 24.04 container; the CI job apply-theme bats suite is green on the merged head. (An earlier head was red on Linux: the UI asset data was passed to yq in an environment variable, and Linux limits one variable to 128 KiB, so assets over about 96 KiB crashed the render. It now goes through files; commit 34d99d9.) markdownlint, prettier and cspell passed on the changed guide pages, including the two pages edited for EPMCDME-16332.
• npm run check, npm run build and secrets:check: passed on the earlier head; not re-run after the review fixes.
• Run against the GCP stand (GKE cdmp-codemie-gke), 20 and 21 October: apply-theme upgraded the UI, API and Keycloak releases with a test package ("Example Co"), and a running Keycloak served the child login theme. These runs also hit the restart problem that review comment 7 describes (fixed in f9ba69d).
• Not run: the oauth2-proxy and realm phase (the stand has no KeycloakRealm resource), an upgrade with oversized assets, the example workflow on a real GitHub runner, and a mail sent by a running Keycloak.

[baduda]

The guide does not say which kit version goes with which CodeMie version. The description says it does, but the "Kit Versions" table lists features, not CodeMie releases. This matters together with the logoUrl problem (inline comment on apply-theme:574): a package with an email block applied to an older backend also stops the API. Please add the minimum CodeMie (chart and app) release for each row once the backend and UI MRs land.

[antonkatsapau]

Re: kit version and CodeMie version table. Agreed. The "Kit Versions" table will get the minimum CodeMie release (chart and app) for each row after the backend and UI MRs are merged and released. I leave this comment open until then. The logoUrl problem from the inline comment is fixed in 94e38c9.