mastertheboss.com
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 **( August 2025 )** is**26.3.2**.
## 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.
