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 docker container for development purpose, 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-themeThis 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:
keycloakVersionTargetsIf 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.
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 \
startThis 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.jarversion: '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: bridgeIf you use Bitnami's Keycloak Helm chart you can leverage the initContainers parameter to load your theme.
apiVersion: v2
name: keycloak
version: 1.0.0
dependencies:
- name: keycloak
version: 24.4.10 # Keycloak 26.1.2
repository: oci://registry-1.docker.io/bitnamichartsHere we only list the relevant values:
# OPTIONAL: Here you can define environment variables that you can access in your theme, see: https://docs.keycloakify.dev/features/environment-variables
extraEnvVars:
- name: MY_APP_PALLET
value: "monokai"
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
mkdir -p /emptydir/app-providers-dir
curl -L -f -S -o /emptydir/app-providers-dir/keycloak-theme.jar https://github.com/USER/PROJECT/releases/download/VERSION/keycloak-theme-for-kc-all-other-versions.jar
volumeMounts:
- name: empty-dir
mountPath: /emptydirRead 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.
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.
Another common approach is to build a custom Docker image of Keycloak that extends the official Keycloak image and includes your theme.
cd ~/github
git clone https://github.com/keycloakify/keycloakify-starter
cd keycloakify-starter
cat << EOF > ./.dockerignore
node_modules
dist
dist_keycloak
# IMPORTANT: Make sure `.gitignore` is **not** listed
# in your .dockerignore file
EOF
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-keycloakRef to official doc: https://www.keycloak.org/server/containers
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.
Last updated
Was this helpful?