Keycloak With Docker Compose

Keycloak is an open sourced project for identity and access management developed by Red Hat. It is designed to be a versatile and robust IAM solution for both authentication and authorization for apps and services. What follows is a brief guide on how to run Keycloak locally using docker compose.

Docker Compose

By default, Keycloak will use a dev-file for storage, but for our use case we will be using Postgres. Keycloak does support other databases as well.

 1#docker-compose.yml
 2version: '3.8'
 3
 4services:
 5  postgres:
 6    image: postgres:${POSTGRES_VERSION}
 7    restart: always
 8    environment:
 9      POSTGRES_DB: ${POSTGRES_DB}
10      POSTGRES_USER: ${POSTGRES_USER}
11      POSTGRES_PASSWORD: ${POSTGRES_PASS}
12
13  keycloak:
14    image: quay.io/keycloak/keycloak:${KEYCLOAK_VERSION}
15    ports:
16      - "8080:8080"
17      - "8443:8443"
18    entrypoint: /opt/keycloak/bin/kc.sh start-dev
19    environment:
20      DB_VENDOR: postgres
21      DB_ADDR: postgres
22      DB_DATABASE: ${POSTGRES_DB}
23      DB_USER: ${POSTGRES_USER}
24      DB_PASSWORD: ${POSTGRES_PASS}
25    env_file:
26      - ./.env
27    depends_on:
28      - postgres

In the same directory add an .env file

 1# postgres
 2POSTGRES_VERSION=16.2
 3POSTGRES_DB=kc
 4POSTGRES_USER=kc
 5POSTGRES_PASS=kc
 6
 7# keycloak
 8KEYCLOAK_VERSION=24.0.3
 9KEYCLOAK_ADMIN=admin
10KEYCLOAK_ADMIN_PASSWORD=admin

Now run docker-compose up, let docker preform its magic, and everything should "just work"tm. Visiting http://localhost:8080 should load the login page for Keycloak's admin console. Using the environment variables provided above a default user "admin" was created in the master realm with the password "admin"

What Just Happened?

A run down of what the above accomplished:

1. Spun up a docker container with Postgres 16.2 running
2. Running docker-compose will load the .env to make the declared environment variables available.
3. Created a new Postgres DB with the name kc and user & password of kc (Using the aforementioned environment variables)
4. Set the Postgres container to always restart if it encounters an error and fatally dies
5. Import and run Keycloak 24.0.3 in a docker container using the above-mentioned Postgres database
6. Load the .env file in order for Keycloak use the environment variables for configuration
7. Explicitly mapped the ports 8080 and 8443. These are the default container ports, but common for local development. Feel free to change them to suite your needs. e.g. 8081:8080 would make Keycloak available via http://localhost:8081 instead
8. If all went well, both services should be running and make a local instance of Keycloak available

Some Notes

This instance of Keycloak was started using the start-dev option when starting the server. This approach, as indicated by the command, is a more developer-friendly method for getting started quickly. Some default configurations for start-dev are:

• HTTP is enabled (HTTPS is available, but not required)
• Strict hostname matching is disabled
• Theme-caching and template-caching are disabled

Go Forth and Profit

Keycloak is favored in the IAM world for being open source, robust, and easy to deploy (Among many, many other things). For more explore the official Keycloak guides. Happy identifying and authenticating my friends.