In a Keycloak Docker Container

TLDR:

npx keycloakify start-keycloak

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 Docker Desktop (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:

MacOS

Using Homebrew:

brew install maven

Ubuntu/Debian

sudo apt-get install maven

Fedora

sudo dnf install maven

Windows

On Windows you can use the Chocolatery package manager:

choco install openjdk
choco install maven

Or install it manually.

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

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
   }
  })
 ]
});

Webpack

package.json

{
  "keycloakify": {
    "startKeycloakOptions": {
      "dockerImage": "quay.io/phasetwo/phasetwo-keycloak:25.0.2.1721752809",
      "dockerExtraArgs": [
        "-e",
        "KC_HTTP_RELATIVE_PATH=/auth"
      ],
      "keycloakExtraArgs": [
        "--spi-email-template-provider=freemarker-plus-mustache",
        "--spi-email-template-freemarker-plus-mustache-enabled=true",
        "--spi-theme-cache-themes=false"
      ],
      "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"
      ],
      "realmJsonFilePath": "./keycloak-resources/myrealm-realm.json",
      "port": 8081
    }
  }
}

See the Vite tab for explaination of the different options.

Configured as the example above, the docker run command will be the following one: