keycloak-scim/testsuite/docker-cluster/README.md

How to test Keycloak cluster with Docker

Docker+Fig allows to easily setup and test the whole environment with:

• Apache HTTPD 2.4 + modcluster 1.3 as Load Balancer
• MySQL 5.6.1 as database
• Various number of Keycloak cluster nodes running on WildFly (with "demo" examples deployed)

You don't need to setup Apache with modcluster + MySQL on your laptop as Docker will do it for you and all will run in Docker containers.

Steps to setup

1. Download and install Docker and Fig

2. Build Keycloak including distribution. This will be used by Docker+Fig. The point is that you can test clustering stuff from latest Keycloak master:

$ cd $KEYCLOAK_HOME
$ mvn clean install
$ cd distribution
$ mvn clean install

3. Build Docker with maven to ensure that needed data will be accessible to Docker+Fig volumes:

$ cd $KEYCLOAK_HOME/testsuite/docker-cluster
$ mvn clean install

4. Build fig and run the whole env. By default it will run Apache + MySQL + 1 Keycloak node:

$ fig build
$ fig up

First build will take long time as it need to download bunch of stuff and install into Docker container. Next builds will be much faster due to Docker cache. After some time, WildFly server is started

Testing

Apache is running in separate container and have 2 ports exposed locally: 10001 and 8000. Port 10001 is for modCluster - you should be able to access Apache modCluster status page: http://localhost:10001/mod_cluster_manager and see one node with deployed "auth-server.war" and few other WARs (keycloak demo).

Also you can access Keycloak admin console via loadBalancer on http://localhost:8000/auth/admin and similarly Account mgmt. TODO: Examples currently doesn't work and I am looking at it..

MySQL can be directly accessed from your machine (if you have MySQL client installed):

$ mysql -h127.0.0.1 -P33306 -uroot -pmysecretpassword

Used database is "keycloak_db"

Remote debugging

With command:

$ docker ps

You can see running ports. For the Keycloak node you may see output similar to this:

0.0.0.0:49153->8080/tcp, 0.0.0.0:49154->8787/tcp, 0.0.0.0:49155->9990/tcp

This means that you can directly access Keycloak (bypass loadbalancer) by going to http://localhost:49153/auth/admin . Also it means that debugger is mapped From Docker port 8787 to local port 49154 . So in your IDE you can connect with settings similar to:

-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=49154

Scale / more cluster nodes

Run this in separate terminal to add more (in this case 2) cluster nodes:

$ fig scale node=2

Now it should be visible on mod_cluster_manager page that they are 2 nodes.

Seeing logs

It's easiest to do:

$ fig logs

to see output of MySql and Keycloak server consoles.

To see Apache and debug logs of keycloak server:

$ fig run node /bin/bash

Then you're in shell inside docker container, which has some mounted volumes with apache logs and keycloak nodes. Apache logs are at:

$ cd /apachelogs/

Keycloak nodes are at (debug logging enabled by default for "org.keycloak"):

$ cd /keycloak-docker/shared

Restart whole environment

Just run:

$ fig stop
$ fig start

This will restart apache + MySQL + all nodes, but won't clear data.

Changing configuration and clear data

Changing configuration (for example UserSession provider from 'mem' to 'jpa') is possible in

$KEYCLOAK_HOME/testsuite/docker-cluster/target/keycloak-docker-cluster/deployments/auth-server.war/WEB-INF/classes/META-INF/keycloak-server.json

then whole environment needs to be stopped, containers removed (in order to update configuration in nodes) and started again:

$ fig stop
$ fig rm
$ fig up

Rebuilding after changed sources

In this case you might need to stop and remove existing containers. Then start from step 2 (Rebuild Keycloak or at least changed jars, then rebuild distribution and testsuite/docker-cluster (or just copy changed JAR into $KEYCLOAK_HOME/testsuite/docker-cluster/target/keycloak-docker-cluster/deployments/auth-server.war/WEB-INF/lib if it's not adapter stuff. But 'fig rm' is safer to call anyway)