Skip to content
Stackship documentation Svenska

BlueprintsUsers

Custom Keycloak theme

Load your own login, account and email theme into the Keycloak blueprint from a container image in your own registry.

Requires: blueprints/read, containerinstance/write, kernel/deployments/read

The Keycloak blueprint from Stackship's public catalog can load a theme you build yourself — login pages, account console, emails. The theme travels as a small container image in a registry you control, pulled through one of the boundary's private registries, so the registry can stay private and no credential enters the pod. The blueprint is in your catalog when the platform catalog is pulled from Stackship's repository, which is the default.

Build the theme image

Package the theme as one or more .jar files and build an image around them:

The image needs Because
The .jar files directly in /theme/ An init container copies /theme/*.jar into Keycloak's providers directory before Keycloak starts. With no jar there, the pod stops with Init:Error
/bin/sh and cp The copy is a shell command, so scratch and distroless images cannot be used; busybox or alpine can
Files readable by user 1000 The init container runs as Keycloak's user
A lowercase repository name Theme Image takes a repository reference such as ghcr.io/acme/keycloak-theme
dockerfile
FROM docker.io/library/busybox:1.37
COPY acme-theme.jar /theme/acme-theme.jar

Push the image to your registry.

Caution

A theme jar can contain code as well as templates and styles, and Keycloak loads everything in its providers directory. Deploy only images you build and trust.

Connect the registry

Connect the registry to the boundary as a private registry — see Private registry. A public image needs no connection.

Deploy Keycloak with the theme

  1. Deploy the Keycloak blueprint — see Deploy a blueprint.
  2. In Configuration, open Advanced settings and turn on Custom Theme.
  3. Choose the Theme Registry, or Public image — no credentials needed for a public image.
  4. Enter the Theme Image — the repository, without a tag — and the Theme Tag. A sha256: digest pins the exact theme; a tag that moves changes nothing until the pod next restarts.
  5. When you chose a registry, two checks on Review & Deploy cover it: Use the boundary's deployment sources needs kernel/deployments/read on the boundary, and Pull through deployment source needs the registry to be connected. See Preflight checks.

Choose the theme in Keycloak

Keycloak picks the theme up when it starts. Choose it per realm in the Keycloak admin console under Realm settings → Themes, or with loginTheme in an imported realm file.

The complete guide, with an example theme repository, Dockerfile and CI workflow, is keycloak-custom-theme.md in Stackship's blueprints repository.