Keycloak Cluster Setup with Docker Compose and UDP for Distributed Caching

Step-by-step guide on how to use Docker Compose to start a cluster of three Keycloak Docker containers using UDP for distributed caching

In this tutorial, we will delve into the process of running a Keycloak cluster locally with three instances for distributed caching. This setup can be particularly beneficial if you are looking to secure your application with Keycloak and test the complete solution locally during the development phase.

In a few words, Keycloak is an open-source IAM tool that offers robust user identity management, authentication, and authorization features for applications.

Each Keycloak instance will be deployed within its own Docker container and will use MySQL database to store their data. To simplify the container setup and configuration, we will utilize Docker Compose. This tool streamlines the management of multi-container Docker applications using a YAML-based syntax to define and configure the containers, networks, and volumes required for your application.

Keycloak’s current distributed cache implementation relies on Infinispan, an open-source, distributed, in-memory key-value data store. Infinispan is designed to be highly scalable, available, and fault-tolerant.

When starting Keycloak in development mode using the “start-dev” command, the distributed caches are disabled by default. However, we can enable them by adding the “KC_CACHE” environment variable with the value “ispn” (short for Infinispan).

Fortunately, the default Keycloak cache configuration utilizes a UDP transport stack, enabling instance discovery through IP multicast transport based on UDP. This default behavior simplifies the configuration and setup process.

Let’s get started!

Project Diagram

The visual representation of our desired project outcome.

Additional Readings

Prerequisites

To follow along with this guide, please ensure that you have the Docker Desktop installed on your machine. You can find on Docker Docs instruction on how to install in Mac, Windows and Linux.

Create the Docker Compose file

Go ahead and open your favorite text editor. We will create a file called docker-compose.yml. It will have the following content:

version: '3.8'
services:
      
  mysql:
    image: mysql:5.7.42
    container_name: mysql
    ports:
      - "3306:3306"
    environment:
      - MYSQL_DATABASE=keycloak
      - MYSQL_USER=keycloak
      - MYSQL_PASSWORD=password
      - MYSQL_ROOT_PASSWORD=root_password

  keycloak1:
    image: quay.io/keycloak/keycloak:22.0.1
    container_name: keycloak1
    environment:
      - KEYCLOAK_ADMIN=admin
      - KEYCLOAK_ADMIN_PASSWORD=admin
      - KC_DB=mysql
      - KC_DB_URL_HOST=mysql
      - KC_DB_URL_DATABASE=keycloak
      - KC_DB_USERNAME=keycloak
      - KC_DB_PASSWORD=password
      - KC_HEALTH_ENABLED=true
      - KC_CACHE=ispn
      - KC_LOG_LEVEL=INFO,org.infinispan:DEBUG,org.jgroups:DEBUG
    ports:
      - "8080:8080"
    command: start-dev
    depends_on:
      - mysql

  keycloak2:
    image: quay.io/keycloak/keycloak:22.0.1
    container_name: keycloak2
    environment:
      - KEYCLOAK_ADMIN=admin
      - KEYCLOAK_ADMIN_PASSWORD=admin
      - KC_DB=mysql
      - KC_DB_URL_HOST=mysql
      - KC_DB_URL_DATABASE=keycloak
      - KC_DB_USERNAME=keycloak
      - KC_DB_PASSWORD=password
      - KC_HEALTH_ENABLED=true
      - KC_CACHE=ispn
      - KC_LOG_LEVEL=INFO,org.infinispan:DEBUG,org.jgroups:DEBUG
    ports:
      - "8081:8080"
    command: start-dev
    depends_on:
      - mysql

  keycloak3:
    image: quay.io/keycloak/keycloak:22.0.1
    container_name: keycloak3
    environment:
      - KEYCLOAK_ADMIN=admin
      - KEYCLOAK_ADMIN_PASSWORD=admin
      - KC_DB=mysql
      - KC_DB_URL_HOST=mysql
      - KC_DB_URL_DATABASE=keycloak
      - KC_DB_USERNAME=keycloak
      - KC_DB_PASSWORD=password
      - KC_HEALTH_ENABLED=true
      - KC_CACHE=ispn
      - KC_LOG_LEVEL=INFO,org.infinispan:DEBUG,org.jgroups:DEBUG
    ports:
      - "8082:8080"
    command: start-dev
    depends_on:
      - mysql  

Save the docker-compose.yml file in a folder of your preference.

Start the Cluster

Ensure that you are in the folder where you saved the docker-compose.yml file, and execute the following command:

docker compose up -d

When you run the command above, the following actions will take place:

1. Docker Compose reads the configuration file (docker-compose.yml);
2. Docker pulls the required container images if they are not already available;
3. Containers for each service are created and started;
4. The containers run in the background (detached mode);
5. Networks are connected and ports are mapped as specified;
6. Dependencies between services are managed automatically;
7. You can interact with the services once they are up and running.

Demonstration

To verify the functionality of our Keycloak cluster, follow these steps:

1. Open three separate browsers (e.g., Chrome, Safari, and Firefox) or use different browser profiles (e.g., Chrome, Incognito Chrome, and Firefox);
2. In one browser, access http://localhost:8080/admin/; in another browser, access http://localhost:8081/admin/; and in the last browser, access http://localhost:8082/admin/;
3. Use “admin” as both the username and password to log in to Keycloak;
4. Once logged in, choose one of the browsers. Click on “Sessions” in the left-side menu. You should observe that the “admin” user has three active sessions;

5. Proceed to sign out of Keycloak in one of the browsers;

6. Check the session count for the “admin” user again. It should now be reduced to two.

By following these steps, you can test the functionality of the Keycloak cluster and observe the session management behavior for the “admin” user.

Troubleshooting

Check Keycloak Logs

We can use the following command to inspect, for instance, the logs of the keycloak-clustered-1 container:

docker logs keycloak-clustered-1

Shutdown

Make sure you are in the folder where you saved the docker-compose.yml file, and execute the following command:

docker compose down -v

Conclusion

In this tutorial, we demonstrated the process of setting up a Keycloak cluster with three instances for distributed caching. By leveraging Docker and Docker Compose, we streamlined the setup of Keycloak instances in individual containers. The cluster utilizes Infinispan for distributed caching, ensuring scalability and fault tolerance. For this setup, we utilized the official Keycloak Docker image and employed the UDP discovery protocol.

Support and Engagement

If you enjoyed this article and would like to show your support, please consider taking the following actions:

• 👏 Engage by clapping, highlighting, and replying to my story. I’ll be happy to answer any of your questions;
• 🌐 Share my story on Social Media;
• 🔔 Follow me on: Medium | LinkedIn | Twitter;
• ✉️ Subscribe to my newsletter, so you don’t miss out on my latest posts.