【Docker Compose】Keycloak構築ガイド（postgres連携あり）

本記事では、Dockerを利用してKeycloakとRDBを連携させる方法を詳しく解説します。Keycloak はオープンソースのアイデンティティ・アクセス管理ツールであり、認証・認可の仕組みを統合的に提供できるため、企業システムやWebアプリケーションで広く利用されています。

デフォルトでは組み込みのH2データベースが利用されますが、H2はテストや開発用途向けであり、本番環境では PostgreSQL などの堅牢な外部DBを使用することが推奨されます。

本記事では、Docker Composeを活用してKeycloakとPostgreSQL/MySQL/MariaDBそれぞれの連携パターンで構築する方法を紹介します。初心者でもすぐに試せるよう、設定ファイルやコマンド例を具体的に紹介します。

前提条件

構築にあたり、以下を前提とします。

• Docker / Docker Compose がインストールされていること
• ローカルマシンでポート 8080 が空いていること（Keycloak 管理画面用）
• Keycloakはバージョン26.0（Quarkus版）で確認

推奨環境としては Linux / macOS / Windows いずれでも問題ない想定です。開発環境や検証環境ではローカル PC上で十分ですが、実運用環境ではサーバーやクラウドインフラ上にデプロイするケースが一般的です。

Docker Composeでkeycloak+RDBを構築する手順

docker-compose.ymlファイルの準備

以下は Keycloak と RDB を連携させるための docker-compose.yml のサンプルです。 PostgreSQL / MySQL / MariaDB をバックエンドにする場合の例をそれぞれ示します。 （※Quarkus版 Keycloak は環境変数 KC_DB に応じてDBを切り替えます）

1
version: '3.9'
2

3
services:
4
  postgres:
5
    image: postgres:17
6
    container_name: postgres
7
    environment:
8
      POSTGRES_DB: keycloak
9
      POSTGRES_USER: keycloak
10
      POSTGRES_PASSWORD: password
11
    volumes:
12
      - postgres_data:/var/lib/postgresql/data
13
    networks:
14
      - keycloak_network
15

16
  keycloak:
17
    image: quay.io/keycloak/keycloak:26.0
18
    container_name: keycloak
19
    command: ["start-dev"]
20
    environment:
21
      KC_DB: postgres
22
      KC_DB_URL_HOST: postgres
23
      KC_DB_URL_PORT: 5432
24
      KC_DB_USERNAME: keycloak
25
      KC_DB_PASSWORD: password
26
      KC_DB_SCHEMA: public
27
      KEYCLOAK_ADMIN: admin
28
      KEYCLOAK_ADMIN_PASSWORD: admin
29
    ports:
30
      - 8080:8080
31
    depends_on:
32
      - postgres
33
    networks:
34
      - keycloak_network
35

36
volumes:
37
  postgres_data:
38

39
networks:
40
  keycloak_network:

1
version: '3.9'
2

3
services:
4
  mysql:
5
    image: mysql:8.4
6
    container_name: mysql
7
    environment:
8
      MYSQL_DATABASE: keycloak
9
      MYSQL_USER: keycloak
10
      MYSQL_PASSWORD: password
11
      MYSQL_ROOT_PASSWORD: rootpassword
12
    ports:
13
      - 3306:3306
14
    networks:
15
      - keycloak_network
16

17
  keycloak:
18
    image: quay.io/keycloak/keycloak:26.0
19
    container_name: keycloak
20
    command: ["start-dev"]
21
    environment:
22
      KC_DB: mysql
23
      KC_DB_URL: jdbc:mysql://mysql:3306/keycloak
24
      KC_DB_USERNAME: keycloak
25
      KC_DB_PASSWORD: password
26
      KC_HEALTH_ENABLED: "true"
27
      KC_METRICS_ENABLED: "true"
28
      KEYCLOAK_ADMIN: admin
29
      KEYCLOAK_ADMIN_PASSWORD: admin
30
    ports:
31
      - 8080:8080
32
    depends_on:
33
      - mysql
34
    networks:
35
      - keycloak_network
36

37
networks:
38
  keycloak_network:

1
version: '3.9'
2

3
services:
4
  mariadb:
5
    image: mariadb:11.4
6
    container_name: mariadb
7
    environment:
8
      MARIADB_DATABASE: keycloak
9
      MARIADB_USER: keycloak
10
      MARIADB_PASSWORD: password
11
      MARIADB_ROOT_PASSWORD: rootpassword
12
    ports:
13
      - 3307:3306
14
    networks:
15
      - keycloak_network
16

17
  keycloak:
18
    image: quay.io/keycloak/keycloak:26.0
19
    container_name: keycloak
20
    command: ["start-dev"]
21
    environment:
22
      KC_DB: mariadb
23
      KC_DB_URL: jdbc:mariadb://mariadb:3306/keycloak
24
      KC_DB_USERNAME: keycloak
25
      KC_DB_PASSWORD: password
26

27
      KC_HEALTH_ENABLED: "true"
28
      KC_METRICS_ENABLED: "true"
29
      KEYCLOAK_ADMIN: admin
30
      KEYCLOAK_ADMIN_PASSWORD: admin
31
    ports:
32
      - 8080:8080
33
    depends_on:
34
      - mariadb
35
    networks:
36
      - keycloak_network
37

38
networks:
39
  keycloak_network:

Keycloakの起動コマンド

docker-compose.ymlを配置したディレクトリで以下コマンドを実行します。

1
docker-compose up  --build -d --remove-orphans

コマンド説明

• docker-compose up

  docker-compose.yml に定義されたサービスを起動する。 コンテナが存在しない場合は新規作成、存在する場合は再利用される。

必要に応じて以下オプションを付けて実行してください。

1. --build コンテナを起動する前に イメージを必ずビルドし直す。

   • Dockerfile や依存関係を変更した場合に反映させたいときに指定する。

2. -d （--detach の短縮形） バックグラウンドで起動する。

   • 指定しない場合は、ターミナルにログが出続ける（フォアグラウンド実行）。

3. --remove-orphans docker-compose.yml に書かれていない不要なコンテナを削除する。

   • 以前の定義にあって現在の docker-compose.yml に無いサービスが残っているとき、それを自動的に消してくれる。

各オプションを付与する場合でまとめると

「docker-compose.yml の内容に従って、不要な古いコンテナを削除しつつ、イメージを再ビルドし、サービスをバックグラウンドで起動する」

コマンドです。

起動が完了したら、以下の URL にアクセスしてください。

1
http://localhost:8080/admin

ブラウザに管理画面が表示され、ユーザー名 admin / パスワード admin でログイン可能です。ログイン後は必要に応じて Realm（認証領域）を作成し、クライアントやユーザーを追加して利用を開始できます。

docker-compose.yml解説

PostgreSQL版 (docker-compose.yml)

このファイルでは PostgreSQL を Keycloak のデータベースとして利用する設定が記載されています。

• postgres サービス

  • イメージ: postgres:17
  • 環境変数でデータベース名（keycloak）、ユーザー名（keycloak）、パスワードを設定。
  • ポート 5432 をホストに公開。

• keycloak サービス

  • イメージ: quay.io/keycloak/keycloak:26.0
  • start-dev モードで起動（開発用途向け）。
  • 環境変数でデータベース接続を指定（KC_DB=postgres、KC_DB_URL=jdbc:postgresql://postgres:5432/keycloak）。
  • 管理者アカウント（admin / admin）を定義。
  • ポート 8080 を公開。
  • depends_on により、Keycloak 起動前に PostgreSQL が立ち上がるよう制御。

MySQL版 (docker-compose.yml)

このファイルでは MySQL を利用する設定です。

• mysql サービス

  • イメージ: mysql:8.4
  • データベース名・ユーザー・パスワードを環境変数で設定。
  • ルートユーザー用パスワードも指定（MYSQL_ROOT_PASSWORD）。
  • ポート 3306 を公開。

• keycloak サービス

  • 同様に quay.io/keycloak/keycloak:26.0 を利用。
  • データベース接続は KC_DB=mysql、URLは jdbc:mysql://mysql:3306/keycloak。
  • 管理者アカウントを定義。
  • depends_on により、MySQL が起動してから Keycloak が立ち上がる。

MariaDB版 (docker-compose.yml)

このファイルでは MariaDB を利用します。MySQL と互換性があるため設定が非常に似ています。

• mariadb サービス

  • イメージ: mariadb:11.4
  • 環境変数でデータベース・ユーザー・パスワードを設定。
  • MARIADB_ROOT_PASSWORD を指定して管理用の認証も確保。
  • ポート 3306 を公開。

• keycloak サービス

  • イメージ: quay.io/keycloak/keycloak:26.0
  • KC_DB=mariadb と指定。
  • 接続URLは jdbc:mariadb://mariadb:3306/keycloak。
  • 管理者アカウント admin / admin を定義。
  • depends_on により MariaDB の起動を待機。

Docker Keycloak構築まとめ

• PostgreSQL: エンタープライズ用途で広く使われ、Keycloak の推奨DB。
• MySQL: 利用者が多く、セットアップが容易。
• MariaDB: MySQL 互換で軽量・高速、オープンソースとして人気。

本記事では、Docker Composeを使ってKeycloakとRDBを連携して起動する方法を解説しました。 いずれも Keycloak（Quarkus版） で動作確認用に最適化された設定であり、開発環境や検証環境の構築に役立ちます。

Docker を活用すれば、開発環境や検証環境を短時間で立ち上げられるだけでなく、本番環境に近い構成でテストすることも可能です。PostgreSQLを始めとするRDBを利用することで、安定性とスケーラビリティを備えた認証基盤を運用できるようになります。さらに実運用を見据える場合は、クラスタリングや監視、バックアップなどの仕組みを整えることで、より信頼性の高いシステムを構築できるでしょう。