Quick guide to running Keycloak with Docker Compose using H2 or Postgres.Our Docker Support Team is always here to help you.

Quick Setup for Keycloak Docker Compose with H2 or PostgreSQL

When working on authentication setups, having Keycloak running locally is a lifesaver. It helps you focus on building your app without juggling multiple auth services. In this post, let’s walk through how to spin up Keycloak using Docker Compose, with both PostgreSQL and H2 database options. If you searched for keycloak docker compose h2, you’re exactly where you should be.

System Prep

Make sure Docker is installed on your system (Install and Configure Docker on Ubuntu 24.04). To check, run:

docker --version

Docker Compose Configuration for Keycloak

We’ll create two services:

• keycloak from the jboss/keycloak image
• keycloakdb using postgres

Here’s the full Docker Compose file setup:

version: '3.3'

services:

keycloak:

image: jboss/keycloak:${KEYCLOAK_VERSION}

ports:

- "8024:8080"

environment:

- KEYCLOAK_USER=${KEYCLOAK_USER}

- KEYCLOAK_PASSWORD=${KEYCLOAK_PASSWORD}

- DB_DATABASE=${KEYCLOAK_DATABASE_NAME}

- DB_USER=${KEYCLOAK_DATABASE_USER}

- DB_PASSWORD=${KEYCLOAK_DATABASE_PASSWORD}

- DB_ADDR=${KEYCLOAK_DATABASE_HOST}

- DB_VENDOR=${KEYCLOAK_DATABASE_VENDOR}

networks:

internal:

depends_on:

- keycloakdb

keycloakdb:

image: postgres:${POSTGRES_VERSION}

ports:

- "5433:5432"

environment:

- POSTGRES_USER=${KEYCLOAK_DATABASE_USER}

- POSTGRES_PASSWORD=${KEYCLOAK_DATABASE_PASSWORD}

- POSTGRES_DB=${KEYCLOAK_DATABASE_NAME}

volumes:

- keycloak-postgres:/var/lib/postgresql/data

networks:

internal:

volumes:

keycloak-postgres:

networks:

Internal:

Environment Variables

Create a .env file in the same directory and paste the following:

COMPOSE_PROJECT_NAME=keycloakindocker

POSTGRES_VERSION=14.1-alpine

KEYCLOAK_VERSION=15.0.2

KEYCLOAK_USER=keycloak

KEYCLOAK_PASSWORD=keycloak

KEYCLOAK_DATABASE_NAME=keycloakdb

KEYCLOAK_DATABASE_USER=keycloakdb

KEYCLOAK_DATABASE_PASSWORD=keycloakdb

KEYCLOAK_DATABASE_HOST=keycloakdb

KEYCLOAK_DATABASE_VENDOR=postgres

These variables handle your service names, admin credentials, and database connections. Especially if you want to fall back on H2 later, don’t miss the DB_VENDOR setting. This is a key trigger when discussing keycloak docker compose h2.

Start Keycloak with Docker

Now run the following command from your project directory:

docker-compose -f docker-compose-keycloak.yml up -d

The -d flag runs your containers in the background, and the -f option points to the specific YAML file.

Check Running Services

To verify the containers are up:

docker ps

CONTAINER ID   IMAGE                      PORTS                                                 NAMES

774a1d259bf9   jboss/keycloak:15.0.2      0.0.0.0:8024->8080/tcp                                 keycloakindocker_keycloak_1

6f10181d012b   postgres:14.1-alpine       0.0.0.0:5433->5432/tcp                                 keycloakindocker_keycloakdb_1

At this stage, Keycloak is running and connected to the PostgreSQL container. But here’s the cool part, if you remove or comment out the DB_VENDOR and related database variables, Keycloak will default to H2. So, if you’re just testing locally or don’t need persistent DB, the embedded H2 database works instantly. That’s why this setup is popular for quick trials, though it’s worth being aware of the disadvantages of containerization.

Access Keycloak

Head over to:

http://localhost:8024/auth/

You’ll land on the welcome page. Click Administration Console, then login using:

• Username: keycloak
• Password: keycloak

This brings you into the master realm dashboard.

[If needed, Our team is available 24/7 for additional assistance.]

Conclusion

Setting up Keycloak with Docker Compose doesn’t have to be complicated. Whether you’re using PostgreSQL or H2, it just works if configured correctly. The keycloak docker compose h2 setup is especially useful for quick tests or demos without setting up a full database.