Keycloak Quarkus Migration

Preparation

Remember to always create a backup before getting started.

Keycloak Configuration Changes

Keycloak now has split the configuration into two parts:

• Build Configuration ... is defined on build time. (e.g. database type)
• Runtime Configuration ... is defined on runtime. (e.g. database credentials)

Unfortunately, the default docker image is only built for H2, an in-memory database for Java. Because of that, we are forced to install the necessary Postgres drivers ourselves. Luckily Keycloak is providing a nice CLI that is easily configurable using environment variables.

Custom Image

The first step is to create a Dockerfile that looks like the following:

# DockerfileARG KEYCLOAK_VERSIONFROM quay.io/keycloak/keycloak:${KEYCLOAK_VERSION}ENV KC_DB=postgresRUN /opt/keycloak/bin/kc.sh build

Now we are able to build our own image like this:

# shelldocker build \  -t local/keycloak:17.0.0 \  --build-arg=KEYCLOAK_VERSION=17.0.0 \  .

or build it using docker-compose like this:

# docker-compose.yamlversion: '3.9'services:  keycloak:    image: local/keycloak:17.0.0    build:      context: .      args:        - 'KEYCLOAK_VERSION=17.0.0'    command: start --optimized

and the following command:

# shelldocker-compose build

Starting with Keycloak 19 start --optimized should be specified as a command. This prevents the startup script inside the container from rebuilding Keycloak every time the container is started.

Environment Variables

The environment variables also did slightly changed:

# .keycloak.env
KEYCLOAK_ADMIN=admin
KEYCLOAK_ADMIN_PASSWORD=<cool_password>
KC_DB_SCHEMA=public
KC_DB_URL_HOST=postgres
KC_DB_URL_DATABASE=keycloak
KC_DB_USERNAME=keycloak
KC_DB_PASSWORD=<another_cool_password>
KC_HOSTNAME=id.<cool_domain>
KC_PROXY=edge

KC_PROXY tells Keycloak to respect X-Forwared-headers and start without the configuration of certificates. Keycloak has a nice list of all configuration parameters, that are all available either as a command-line argument or as an environment variable: keycloak.org/server/all-config All options that have a wrench in the last column need to be specified at build time (in the Dockerfile) al other are runtime configuration options (.env file).

Startup Command

The last thing you have to do is to add the startup command start.

Your docker-compose.yaml should look like this:

# docker-compose.yamlversion: '3.9'services:  keycloak:    command: start

URLs

The tidiest thing is that Keycloak stripped the /auth from all URLs. If you have too many clients and don't want to update every URL you can use the config KC_HTTP_RELATIVE_PATH and set it to /auth. Please note that this is a build option, which means you have to define it in your Dockerfile.