How to create a custom Keycloak container image

This page describes how to build a custom Keycloak image with your own themes and providers for use with the VSHNKeycloak service.

Using the Keycloak image template (recommended)

Use the custom-keycloak-image-template Cookiecutter template to generate a project that builds a fully optimized Keycloak image. The resulting image is used with the customImage field in your VSHNKeycloak claim.

Prerequisites

Steps

  1. Generate a new project from the template.

    cookiecutter gh:vshn/custom-keycloak-image-template

    Answer the prompts:

    project_name [My Custom Keycloak]: Acme Keycloak
project_slug [acme-keycloak]:
keycloak_version [26.7.0]: 26.7.0

    This creates a directory named after your project_slug.

  2. Add your themes and provider JARs to the generated project.

    cp -r my-theme/ acme-keycloak/themes/
cp my-provider.jar acme-keycloak/extensions/

    Themes go under themes/ and provider JARs go under extensions/.

    Keycloak 26.7.0 changed the user self-registration flow: the password is no longer collected on the registration form, but on a separate page after the email address has been verified. If your login theme overrides the registration templates, check it against the new flow before rolling out the image. See User self-registration and required actions.

  3. Build the image locally to verify it compiles correctly.

    cd acme-keycloak
make build

  4. Push the image to your container registry.

    make push IMAGE=ghcr.io/my-org/acme-keycloak

    The image is tagged with the Keycloak version by default (for example 26.7.0). Override with TAG=<your-tag> if needed.

  5. Reference the image in your VSHNKeycloak claim using the customImage field. See Customization for the full example.

Legacy approach (for use with the deprecated customizationImage field)

This approach uses the deprecated customizationImage field. Use the template-based approach above with the customImage field instead.

The legacy approach packages themes and providers into a minimal container image. At pod startup, an init container copies the files into the running Keycloak instance.

  1. Open a command line and create two directories.

    mkdir themes && mkdir providers

  2. Place your themes and providers in respective directories.

  3. For other custom files and folders, create them as necessary:

    mkdir my-folder && touch pw-blacklist.txt

  4. Create the following Dockerfile.

    cat <<EOF >>Dockerfile
FROM alpine

COPY themes /themes
COPY providers /providers

# Custom files
COPY pw-blacklist.txt /pw-blacklist.txt
COPY my-folder /my-folder
EOF

  5. Build your Docker image.

    docker build -t myuser/keycloak-custom:v1 .

  6. Push your image to the registry.