Hi All, this document deals with how to set up a keycloak cluster using a docker swarm.
Keycloak is an open-source software product to allow single sign-on with Identity Management and Access Management aimed at modern applications and services. As of March 2018, this JBoss community project is under the stewardship of Red Hat who uses it as the upstream project for their RH-SSO product.

  • Docker swarm
  • Mysql/MariaDB database setup for keycloak applications.
  • docker compose

You can build your keycloak application from the below Dockerfile.


FROM jboss/keycloak:latest

ADD cli/TCPPING.cli /opt/jboss/tools/cli/jgroups/discovery/
ADD cli/JDBC_PING.cli /opt/jboss/tools/cli/jgroups/discovery/
HEALTHCHECK --interval=30s --timeout=1s --retries=3 CMD curl -k --fail http://localhost:8080/auth/ || exit 1


Before building a docker image. download the following files.

mkdir cli
wget https://raw.githubusercontent.com/fit2anything/keycloak-cluster-setup-and-configuration/master/src/TCPPING.cli
wget https://raw.githubusercontent.com/fit2anything/keycloak-cluster-setup-and-configuration/master/src/JDBC_PING.cli
cd ..

Create the docker file.

FROM jboss/keycloak:latest

ADD cli/TCPPING.cli /opt/jboss/tools/cli/jgroups/discovery/
ADD cli/JDBC_PING.cli /opt/jboss/tools/cli/jgroups/discovery/
HEALTHCHECK --interval=30s --timeout=1s --retries=3 CMD curl -k --fail http://localhost:8080/auth/ || exit 1

Build the docker image

docker build -t prabhin/keycloak:latest .

Now you can see the docker image got created.

Let’s configure the keycloak cluster.

Create a docker-compose file with the following configuration.

version: '3.3'
    image: prabhin/keycloak:latest 
      DB_PASSWORD: Password
      DB_DATABASE: keycloak_Database_name
      JGROUPS_DISCOVERY_PROPERTIES: datasource_jndi_name=java:jboss/datasources/KeycloakDS,info_writer_sleep_time=500
      KEYCLOAK_USER: admin
      DB_USER: keycloakuser
      DB_VENDOR: mariadb
     - 8080:8080
     - default
      driver: json-file
      replicas: 3

    driver: overlay

DB_PASSWORD keycloak database user password
KEYCLOAK_PASSWORD: keycloak console password
DB_DATABASE: keycloak database name
KEYCLOAK_USER: keycloak console admin user

Here we are running 3 docker containers in a cluster, maintaining a minimum of 3 containers will avoid split-brain while cluster resyncing.
Now let’s deploy the stack.


docker stack deploy -c docker-compose.yml keycloak

Now you can see containers are starting up. You can see the dockers of the entire stack using below command

docker service logs keycloak

You can check the status of the container using the below command and wait for the containers to be healthy.

docker ps

Or else you can check individual container logs using below command,

docker logs -f <containerID>

Once containers are healthy, browse http://IP:8080 for Keycloak application console login.


© 2019, Techrunnr. All rights reserved.

Questions Answered
Articles Written
Overall Points

Prabhin Prabharkaran

He is Technical professional. He is a person who loves to share tricks and tips on the Internet. He Posts what he does!!


  • Ali · May 18, 2020 at 4:19 pm

    hi Prabhin,
    Thanks for this excellent Article.
    how does it work with TCPING?

    Leave a Reply

    Keep ahead of COVID-19

    Follow the below safety measures as precautionary steps to avoid COVID-19 1. Use face mask in public Places 2. Use Hand sanitizers 3. Maintain Social Distancing 4. Avoid going to crowded places 5. Avoid touching eyes, nose and mouth