Deploying Your Theme

This section explains how to load and enable your theme in your production Keycloak instance.

Warning: If your goal is to test your theme in a Keycloak instance, this is NOT the correct section of the documentation. Refer to the Testing Your Theme in a Keycloak Docker Container section for detailed instructions. This section is intended for deploying your theme to a production Keycloak instance, which involves a completely different process.

Building the JAR File

Keycloak uses an extension system where themes or other custom plugins are packaged as standardized JAR files.

The first step is to build your theme into a JAR file that can be loaded into Keycloak.

npm run build-keycloak-theme

This command will create a /dist_keycloak directory containing the necessary JAR files.

By default, Keycloakify generates multiple JAR files to support different Keycloak versions. Here’s how to choose the correct JAR file for your production environment:

• Keycloak 11 to 21 and 26 and newer: Use keycloak-theme-for-kc-all-other-versions.jar.

• Keycloak 22 to 25: Use keycloak-theme-for-kc-22-to-25.jar.

You can configure which JAR files are generated and how they are named. For details, refer to this guide:

keycloakVersionTargets

If you have an OPS team and your responsibility is limited to developing the theme, your job ends here. The JAR file is your deliverable. You can provide it to the person managing your Keycloak instance—they will know what to do with it.

If you are responsible for both development and deployment, keep reading to learn how to load and enable the theme in Keycloak.

Loading the JAR File into Keycloak

Now that your theme is packaged as a JAR file, you can load it into your Keycloak server, just like any other Keycloak extension.

For official guidance, refer to the Keycloak documentation on registering provider implementations. While the official documentation provides a general overview, you might wonder how to apply those instructions in practice. Below, you’ll find a few code snippets illustrating how to load your theme, depending on the method you use to deploy Keycloak in production.

Improtrant note:

How to deploy Keycloak in production is beyond the scope of Keycloakify’s documentation.

If you’re unfamiliar with deploying a Keycloak instance, we strongly recommend starting with the official Keycloak deployment guides.

Do not attempt to use these snippets directly without understanding how Keycloak deployment works.

Once you’re confident in deploying Keycloak, revisit this section to integrate your custom theme seamlessly.

Docker

One of the most common ways to deploy Keycloak in production is by using the official Docker image.

If you are following this approach, you can use the -v option to mount your JAR file into the /opt/keycloak directory inside the container.

Here’s an example of how to run the Keycloak container with your custom theme:

docker run \
    # ...other options
    -v "./dist_keycloak/keycloak-theme-for-kc-all-other-versions.jar":/opt/keycloak/providers/keycloak-theme.jar \
    quay.io/keycloak/keycloak:26.0.7 \
    start --optimized

Docker Compose

This approach builds on the basic Docker setup, providing a more streamlined way to manage your Keycloak deployment with Docker Compose. Let’s assume you have the following directory structure:

./docker-compose.yaml
./themes/keycloak-theme-for-kc-all-other-versions.jar

docker-compose.yaml

version: '3.7'

services:
  postgres:
    image: postgres:16.2
    volumes:
      - postgres_data:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: ${POSTGRES_DB}
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    ports:
      - 5432:5432
    networks:
      - keycloak_network

  keycloak:

    image: quay.io/keycloak/keycloak:26.0.4
    command: start-dev

    environment:
      KC_HOSTNAME: ${KEYCLOAK_HOSTNAME}
      KC_HOSTNAME_PORT: 8080
      KC_HTTP_ENABLED: true
      KC_HEALTH_ENABLED: true
      KC_HOSTNAME_STRICT_HTTPS: false
      KC_HOSTNAME_STRICT: false
      
      KC_BOOTSTRAP_ADMIN_USERNAME: ${KEYCLOAK_ADMIN}
      KC_BOOTSTRAP_ADMIN_PASSWORD: ${KEYCLOAK_ADMIN_PASSWORD}
      KC_DB: postgres
      KC_DB_URL: jdbc:postgresql://postgres/${POSTGRES_DB}
      KC_DB_USERNAME: ${POSTGRES_USER}
      KC_DB_PASSWORD: ${POSTGRES_PASSWORD}
    ports:
      - 8080:8080
    volumes: 
      - ./themes:/opt/keycloak/providers/
    restart: unless-stopped
    depends_on:
      - postgres
    networks:
      - keycloak_network

volumes:
  postgres_data:
    driver: local

networks:
  keycloak_network:
    driver: bridge

Helm

If you use Bitnami's Keycloak Helm chart you can leverage the initContainers parameter to load your theme.

Chart.yaml

apiVersion: v2
name: keycloak
version: 1.0.0
dependencies:
  - name: keycloak
    version: 21.4.1 # Keycloak 24
    repository: oci://registry-1.docker.io/bitnamicharts

Here we only list the relevant values:

values.yaml

keycloak:
  initContainers:
    - name: realm-ext-provider
      image: curlimages/curl
      imagePullPolicy: IfNotPresent
      command:
        - sh
      args:
        - -c
        - |
          # Replace USER and PROJECT, use the correct version of the jar for the keycloak version you are deploying    
          curl -L -f -S -o /extensions/keycloak-theme.jar https://github.com/USER/PROJECT/releases/download/v11.3.16/keycloak-theme-for-kc-22-to-25.jar

      volumeMounts:
        - name: extensions
          mountPath: /extensions

  extraVolumeMounts:
    - name: extensions
      mountPath: /opt/bitnami/keycloak/providers

  extraVolumes:
    - name: extensions
      emptyDir: {}

Read this section of the starter project readme to learn how to get GitHub Action to publish your theme's JAR as assets of your GitHub release.

Bare metal

What you need to know is that your keycloak-theme.jar should be placed in the provider directory of your Keycloak (e.g: /opt/keycloak/providers) After that you should run bin/kc.sh build (e.g: sh /opt/keycloak/bin/kc.sh build)

Then you can start your Keycloak server, your theme should be available in it!

Docker - Custom Image

Another common approach is to build a custom Docker image of Keycloak that extends the official Keycloak image and includes your theme.

This approach is not recommended, as it requires rebuilding the Docker image every time you update your theme.

However, if you still prefer this approach, here’s an example of what your Dockerfile might look like:

cd ~/github
git clone https://github.com/keycloakify/keycloakify-starter
cd keycloakify-starter

cat << EOF > ./Dockerfile
FROM node:20-alpine as build
RUN apk update && \
    apk add --no-cache openjdk17 maven
WORKDIR /app
COPY . .
RUN yarn install --frozen-lockfile
RUN yarn build-keycloak-theme

FROM quay.io/keycloak/keycloak:26.0.7
WORKDIR /opt/keycloak
COPY --from=build /app/dist_keycloak/keycloak-theme-for-kc-all-other-versions.jar /opt/keycloak/providers/
RUN /opt/keycloak/bin/kc.sh build
ENTRYPOINT ["/opt/keycloak/bin/kc.sh", "start", "--optimized"]
EOF

docker build -t my-keycloak .
docker run \
    -e KC_BOOTSTRAP_ADMIN_USERNAME=admin \
    -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin \
    -p 8080:8080 \
    my-keycloak

Cloud-IAM

If you have a Keycloak instance managed by Cloud-IAM, you can simply sign-in to and click on the "Upload JAR File" button.

Enabling Your Theme

Once your JAR file is loaded into your Keycloak instance, enable your theme in the Keycloak Admin Console:

1. Go to Realm Settings in your desired realm.

2. Under the Themes section, select your theme from the dropdown menus (e.g., Login Theme).

Never configure the master realm for your application. Create a separate realm for your application to ensure the master realm remains untouched.

Note that the name that apprear in the dropdown (here "keycloakify-starter") can be configured with the themeName option. If you implement theme variants you'll have more than one option.

Enabling diffrent theme for diffrent client

The login theme can be applied at the client level. You typically have one Keycloak client per web application. Setting the login theme at the client level means that each application of your realm can have different login/register pages. This comes in handy if you're implementing Theme Variants.

To enable a login theme on one of your clients:

• Select your realm in the top left corner

• -> Clients

• -> Select your client in the list

• -> Scroll down to "Login Theme" and select your theme.

The account theme can only be enabled at the realm level; however, accessing the account pages requires authentication. If you don't want your user to inadvertently come across the default login theme when navigating to the account pages after their session has expired, you might want to enable your login theme on the "account-console" client.

• Select your realm in the top left corner

• -> Clients

• -> Select "account console"

• -> Scroll down to "Login Theme" and select one of your login theme.