Setting up a local Keycloak stand

This post is a continuation of a series of articles about the implementation of Keycloak in a large enterprise project.

The main practical topic of this post is setting up a bench for local development, which can later be used in CI to run tests.

Below I will give the compose file that I got and give a number of comments.

version: "3.9"
services:
  keycloak-postgres:
    image: library/postgres:${KC_POSTGRES_IMAGE_TAG:-14}
    container_name: ${POSTGRES_CONTAINER_NAME:-postgres}
    restart: on-failure
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: postgres
    healthcheck:
      test: pg_isready -d postgres
      interval: 10s
      timeout: 5s
      retries: 3
      start_period: 5s
    ports:
      - ${KC_POSTGRES_PORT_MAPPING:-5435}:5432
    deploy:
      resources:
        limits:
          memory: 256M

  keycloak:
    image: quay.io/keycloak/keycloak:20.0.2
    container_name: keycloak
    command:
      - start --auto-build --db postgres --hostname-strict-https false --hostname-strict false --proxy edge --http-enabled true --import-realm --spi-user-profile-legacy-user-profile-read-only-attributes *_RES_ACCESS_MODE
    environment:
      KC_DB_URL: jdbc:postgresql://keycloak-postgres:5432/postgres
      KC_DB_USERNAME: postgres
      KC_DB_PASSWORD: postgres
      KC_DB_SCHEMA: public
      KC_FEATURES: preview
      KEYCLOAK_ADMIN: admin
      KEYCLOAK_ADMIN_PASSWORD: admin
    volumes:
      - type: bind
        source: ./src/main/resources/keycloak/import/realm-export.json
        target: /opt/keycloak/data/import/realm-export.json
        read_only: true
      - type: bind
        source: ./src/main/resources/keycloak/scripts/custom-scripts.jar
        target: /opt/keycloak/providers/custom-scripts.jar
        read_only: true
    ports:
      - 8282:8080
    depends_on:
      keycloak-postgres:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "curl", "-f", "http://0.0.0.0:8080/realms/master"]
      start_period: 10s
      interval: 30s
      retries: 3
      timeout: 5s

This compose file allows you to run keycloak in production mode with a relational database.

Since SSO is usually a separate microservice, it makes sense to allocate its own database for it.

This file contains a number of place-holders for more flexible configuration via .env files (we will need this later for CI).

Let’s go through the configuration of the keycloak service in more detail:

It all starts with the run command:

start --auto-build --db postgres --hostname-strict-https false --hostname-strict false --proxy edge --http-enabled true --import-realm

If we look at the DockerFile [https://www.keycloak.org/server/containers ] from which our Keycloak image is assembled, we will see that the entrypoint is ENTRYPOINT there [“/opt/keycloak/bin/kc.sh”] (Script to launch Keycloak in standalone mode). The start command starts the application in production mode.

Now let’s go through the options:

auto build – builds our instance with all dependencies and customizations
db – indicates which database we will use to select the appropriate driver
hostname-strict-https allow/prohibit front and back of keycloak to communicate over HTTP
proxy sets reverse-proxy mode
hostname-strict enable/disable dynamic hostname from request headers
http-enabled allow interaction over http
import-realm enable importing realms from configuration files

After running this configuration with the command docker-compose up -d you will have a ready-made Keycloak bench that you can use to develop and run tests, the main page will be available at http://localhost:8282.

By logging in with admin:admin we will find ourselves on the master realm page: