Keycloak Using Docker and Docker Compose (2025 Edition)

In this updated tutorial, we’ll walk you through the step-by-step process of running Keycloak 26 with Docker. We will learn how to deploy Keycloak with Docker and Docker Compose, covering development mode, data persistence and production set up with PostgreSQL.

Prerequisites

• Docker (v20+): install from docker.com or Podman
• Docker Compose (v1.29+): optional but recommended
• (Production) External database (PostgreSQL recommended)

Finally, if you are new to Keycloak, we recommend checking this article which introduces Keycloak with Quarkus: Keycloak Tutorial for Beginners

Step # 1: Pull the Image

The Keycloak Docker Image for is available in this repository:  quay.io/repository/keycloak/keycloak . To pull the latest Docker Image of Keycloak you can run from the Command Line:

$ docker pull  quay.io/keycloak/keycloak:latest

The latest version of Keycloak with Quarkus ( May 2026 ) is 26.6.1.

Step # 2: Run Keycloak Image in Development mode

Then, the following command will start a Docker Image of Keycloak in development mode:

docker run --name keycloak_dev -p 8080:8080 \
        -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin \
        quay.io/keycloak/keycloak:latest \
        start-dev

Please notice that, when using Keycloak 26, the variables KC_BOOTSTRAP_ADMIN_USERNAME and KC_BOOTSTRAP_ADMIN_PASSWORD deprecate the older KEYCLOAK_ADMIN and KEYCLOAK_ADMIN_PASSWORD

Next, verify the connectivity with the Admin Console which is available at http://localhost:8080

How to start Keycloak Docker image on a different Port ?

On the other hand, if you want to start Keycloak with Docker on a different server port, include the --http-port parameter:

docker run --name keycloak_dev -p 8180:8180 \
        -e KC_BOOTSTRAP_ADMIN_USERNAME -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin \
        quay.io/keycloak/keycloak:latest \
        start-dev --http-port=8180

Step # 3: Run Keycloak with Docker in Production mode

Finally, to start Keycloak in production mode with PostgreSQL as database, use the following example command:

docker run --name keycloak_auto_build -p 8080:8080 \
        -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin \
        quay.io/keycloak/keycloak:latest \
        start \
        --auto-build \
        --db=postgres --features=token-exchange \
        --db-url=jdbc:postgresql://localhost:5432/keycloak --db-username=postgres --db-password=postgres \
        --https-key-store-file=server.keystore --https-key-store-password=secret

Update the Database and Keystore settings accordingly.

Running Keycloak with Docker compose

Docker compose is a valuable tool to orchestrate multiple containers and to provide complex configurations to a Container Image. For example, you can use it to import an existing Realm when using Keycloak Docker Image. To do that, you have to use the –import-realm option at startup. For example, with docker-compose the following file will import the Realm available in the local file /home/keycloak/realm.json:

services:
  auth:
    image: quay.io/keycloak/keycloak
    ports:
      - "8080:8080"
    environment:
      KC_BOOTSTRAP_ADMIN_USERNAME: admin 
      KC_BOOTSTRAP_ADMIN_PASSWORD: admin
    command: 
      - start-dev 
      - --import-realm
    volumes:
      - /home/keycloak/realm.json:/opt/keycloak/data/import/realm.json

To start Keycloak, simply run:

docker-compose up

Finally, verify that the Realm in realm.json has been imported at start up:

Finally, notice how to use docker-compose exec to run commands on the Keycloak Docker Image. For example, here is how to login and add a new User:

# Login into keycloak with admin credentials
docker-compose exec auth /opt/keycloak/bin/kcadm.sh  config credentials --server http://localhost:8080 --realm master --user admin --password admin

# Add the user test
docker-compose exec auth /opt/keycloak/bin/kcadm.sh create users --realm=master -s username=test -s enabled=true -s [email protected] -s emailVerified=true --server http://localhost:8080 

# Sets the password for the user test
docker-compose exec auth /opt/keycloak/bin/kcadm.sh set-password --realm=master --username test --new-password password --server http://localhost:8080 

Running Keycloak with Docker compose and PostgreSQL

Our Docker compose example uses the built-in H2 Database. In Production, you would need to switch to a solid Database, for example to PostgreSQL. The following sample docker-compose.yml file shows how to kickstart Keycloak with Docker Compose and PostgreSQL by bridging them in the same network:

version: '3'

volumes:
  postgres_data:
    driver: local

services:
  postgres:
    image: postgres:latest
    volumes:
      - postgres_data:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: keycloak
      POSTGRES_USER: keycloak
      POSTGRES_PASSWORD: 123456
    healthcheck:
      test: "exit 0"
    ports:
      - 5432:5432
    networks:
      - keycloak_demo

  keycloak:
    image: quay.io/keycloak/keycloak
    command: start-dev
    environment:
      KC_DB: postgres
      KC_DB_URL_HOST: postgres
      KC_DB_URL_DATABASE: keycloak
      KC_DB_PASSWORD: 123456
      KC_DB_USERNAME: keycloak
      KC_DB_SCHEMA: public
      KC_BOOTSTRAP_ADMIN_USERNAME: admin
      KC_BOOTSTRAP_ADMIN_PASSWORD: password
    ports:
      - 8081:8080
    depends_on:
      postgres:
        condition: service_healthy
    networks:
      - keycloak_demo
networks:
  keycloak_demo:
    driver: bridge

Conclusion

You now have a lean, step‑by‑step setup for running Keycloak in Docker—covering quick dev instances, data persistence, Compose orchestration, and a production configuration with PostgreSQL. From here, explore realm customization, secure your instance with SSL, and integrate Keycloak into your applications.