Testing your theme in Storybook is nice, but at some point you'll want to test your theme in a real Keycloak before shipping it in production!
First you want to install and launch (or just Docker) on your computer, if you haven't done it already.
You'll also need Maven to build the .jar locally. Try running mvn --version to see if you have it already. If you don't install it with:
Using :
brew install maven
sudo apt-get install maven
sudo dnf install maven
On Windows you can use the package manager:
choco install openjdk
choco install maven
Or .
You are ready! In your Keycloakify just run:
npx keycloakify start-keycloak
You'll be invited to chose the Keycloak version you want to spin up:
Keycloakify will preconfigure a realm and client for your theme so you don't necessarily need to go in the the Keycloak admin console you can simply navigate to https://my-theme.keycloakify.dev it will redirect to your local Keycloak login pages!
If you makes changes in your theme while the Keycloak container is running your theme will be automatically recompiled and updated in Keycloak. After a few seconds you'll just have to refresh the page you see them live.
Clicking on the https://my-theme.keycloakify.dev link will redirect you to the login page of your theme:
With the developer tool of your brower you'll be able to explore the kcContext of the page. You can use it to creates new stories of your pages in specific configuration.
Loggin in with the test user (testuser/password123) will redirect you to a page where you'll be able to inspect the decoded id token JWT beside other things.
Configuration options
There are many options available to you to configure the Keycloak testing container.
vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { keycloakify } from "keycloakify/vite-plugin";
// https://vitejs.dev/config/
export default defineConfig({
plugins: [
react(),
keycloakify({
accountThemeImplementation: "none",
startKeycloakOptions: {
// All the options are optional
/*
By default Keycloakify uses the official Keycloak Docker Image (quay.io/keycloak/keycloak)
and lets you select the tag when you run the command by asking you to
select a Keycloak version.
Using this option you can use an alternative Docker Image like the one
of Phase2 (https://quay.io/repository/phasetwo/phasetwo-keycloak) and a
specific tag to use.
This option can also be used to pin a specific version of the official
Keycloak Docker Image.
Example: `dockerImage: "quay.io/keycloak/keycloak:25.0.2"`
*/
dockerImage: "quay.io/phasetwo/phasetwo-keycloak:25.0.2.1721752809",
/*
This option allows you to pass extra docker arguments to the
`docker run` command.
*/
dockerExtraArgs: [
"-e", "KC_HTTP_RELATIVE_PATH=/auth"
],
/*
This option allows you to start Keycloak with extra arguments.
*/
keycloakExtraArgs: [
"--spi-email-template-provider=freemarker-plus-mustache",
"--spi-email-template-freemarker-plus-mustache-enabled=true",
"--spi-theme-cache-themes=false"
],
/*
This option allow you to load custom Keycloak extensions in the
Keycloak instance running in the Docker container.
In this example we load two extensions:
- https://github.com/InseeFr/Keycloak-FranceConnect
- https://github.com/micedre/keycloak-mail-whitelisting
*/
extensionJars: [
"https://github.com/InseeFr/Keycloak-FranceConnect/releases/download/6.2.0/keycloak-franceconnect-6.2.0.jar",
"./keycloak-resources/keycloak-mail-whitelisting-2.0.jar"
],
/*
By default, the Keycloak instance is loaded with a pre-configured
realm so you do not have to create a realm, a client, a user, etc.
However you might want to edit this base realm configuration and
persist the changes that you made.
I explain it in this video: https://www.youtube.com/watch?v=lMOLrdqilqE&t=991s
*/
realmJsonFilePath: "./keycloak-resources/myrealm-realm.json",
/*
* By default the Keycloak instance will run on port 8080.
* This option allows you to change it to another port.
*/
port: 8081
}
})
]
});
