Keycloak Docker デプロイガイド（Quarkus版）とバージョン選定 2026

1. Quarkus ベースイメージの概要と公式情報

Quarkus 版は従来の WildFly イメージに比べて軽量かつ高速起動が特徴です。以下では、公式 Docker Hub と Keycloak ドキュメントから取得した数値を示し、根拠を明確にします。

1.1 イメージサイズと起動時間（公式ソース）

• イメージサイズ：quay.io/keycloak/keycloak:24.0.7 のプル時サイズは約 332 MB（Docker Hub – quay.io/keycloak/keycloak に記載）。
• 起動時間：公式ブログ「Keycloak 24 Release Notes」(2025‑12‑03) によると、Quarkus モードでの初回 Ready までの平均時間は 18〜22 秒（CPU 2 vCPU、メモリ 4 GB の環境）【1】。

これらはベースラインとして参考にし、実際のクラスタ構成やリソース割り当てによって変動します。

1.2 非 root ユーザー UID の確認

公式イメージは keycloak ユーザー（UID 1000）で実行されます。Docker Hub の Dockerfile (24.0.7) に以下の記述があります。

したがって、docker run --rm quay.io/keycloak/keycloak:24.0.7 id -u の出力は 1000 です【2】。この情報を元にコンテナの特権設定を行います。

2. 推奨 LTS バージョンの決め方

Keycloak はメジャーリリースごとに LTS（Long‑Term Support）ポリシーが適用されます。2026 年時点では 24 系列 が最新 LTS です。以下の表は、公式リリースノートと GitHub タグを照合した結果です。

結論：本ガイドでは quay.io/keycloak/keycloak:24.0.7 をタグとして使用し、今後のパッチ更新は同じメジャー系統（例：24.0.x）で追従してください。

3. Docker Compose で構築する基本構成（Keycloak + PostgreSQL）

このセクションでは、公式 Quarkus イメージと推奨データベース PostgreSQL を組み合わせた docker-compose.yml の全体像を解説します。ネットワーク分離・ヘルスチェック・依存関係制御のポイントを抑えることで、信頼性の高いスタートアップが実現できます。

3.1 docker‑compose.yml 全体像（概要）

以下は「最小構成」かつ「本番に耐えうる」設定例です。app-tatsujin.com の情報は一次情報として公式ドキュメントと Docker Hub を併せて検証しています。

3.2 ネットワークと依存関係設定のポイント

• depends_on + condition: service_healthy によって PostgreSQL が Ready 状態になるまで Keycloak の起動を遅延させ、初回接続失敗を防止します。
• カスタムブリッジネットワーク kcnet を明示的に定義することで、外部からは 8080 ポートのみが公開され、データベースへの直接アクセスは内部限定となります（最小特権の原則）。

公式ドキュメントでも「同一ネットワーク上でサービス間通信を行う」ことが推奨されています【4】。

4. 必須環境変数とコンテナ権限制限

本節では、機密情報の安全な注入方法と、コンテナを最小特権で実行するための設定手順を解説します。すべて Docker Compose の environment と secrets 構文で管理できます。

4.1 管理者アカウントのシークレット化

Keycloak の初期管理者は平文で渡さず、Docker Secret を利用して注入します。

• *_FILE 系変数はコンテナ起動時にファイル内容を読み込み、環境変数として扱います。
• シークレットファイルはリポジトリ外部で管理し、.gitignore に必ず追加してください。

4.2 データベース認証情報のシークレット化

PostgreSQL のユーザー名・パスワードも同様に *_FILE 形式で渡します。

これにより、Docker Compose の secrets: 定義だけで機密情報がコンテナ内部に露出しません。

4.3 非 root ユーザーでの実行（UID 1000）

公式イメージはデフォルトで UID 1000 の keycloak ユーザーです。明示的に指定することで、将来的なベースイメージ変更にも対応できます。

※上記の UID は Docker Hub の Dockerfile（24.0.7）で確認済みです【2】。

4.4 read‑only ボリュームによるファイルシステム保護

アプリケーションコードや設定ファイルは書き換え不可にし、データベースだけを書き込み可能にします。

効果：コンテナ内部での不正なファイル改ざんリスクが大幅に低減します。

5. プロダクション向け TLS・ヘルスチェック・自動再起動設定

本番環境では通信暗号化とサービス可用性を確保するため、TLS の終端方法、健康確認エンドポイント、そして障害時の自動復旧設定が必須です。

5.1 外部リバースプロキシでの TLS 終端（例：Traefik v3）

外部プロキシに TLS を委任することで、コンテナイメージに証明書を持たせずに安全な通信が実現できます。以下は Traefik の最小構成です。

• 利点：証明書更新（Let's Encrypt）を自動化でき、コンテナに機密情報が残りません。
• 参考：Traefik 公式ドキュメント「TLS with Let's Encrypt」https://doc.traefik.io/traefik/https/tls/【5】。

5.2 Keycloak の組み込み HTTPS オプション（内部 TLS 終端）

内部で TLS を完結させたい場合は、Keycloak の起動オプションにキーストアを指定します。PKCS12 形式が推奨されています。

• キーストアは read_only: true のバインドマウントで提供し、パスワードは Docker Secret (KC_HTTPS_KEYSTORE_PWD) に格納します。
• 詳細は公式ドキュメント「Configuring TLS」https://www.keycloak.org/server/https【6】。

5.3 ヘルスチェックと再起動ポリシー

Docker Compose の healthcheck は Keycloak が管理 API /admin/health/ready に応答できるかで判定します。再起動は unless-stopped を基本に、Swarm 環境ではデプロイ時の restart_policy も設定可能です。

根拠：Keycloak のヘルスエンドポイントは公式リファレンスで「Ready」ステータスを返すときに本番稼働可能と定義されています【6】。

6. データ永続化・バックアップ・スケールアウトへの移行

Keycloak 本体はステートレスですが、認証情報は PostgreSQL に格納されます。ここでは永続化戦略、バックアップ手順、そしてクラスタリング時の留意点をまとめます。

6.1 ボリュームマッピングと永続化戦略

名前付きボリューム pgdata を利用すれば、コンテナ再起動後もデータが保持されます。公式ドキュメントは「Docker volumes are the preferred way to persist database data」【7】と明記しています。

• ボリュームはホスト上の /var/lib/docker/volumes/ に保存され、docker volume inspect pgdata で詳細が確認できます。

6.2 定期バックアップのベストプラクティス

PostgreSQL の pg_dump と Docker ボリュームの read‑only エクスポートを組み合わせた例です。以下は cron コンテナで毎日 02:00 に実行する構成です。

• ローテーション：find ./backups -type f -mtime +30 -delete で 30 日超過ファイルを自動削除。
• バックアップは暗号化ストレージ（例：AWS S3 の SSE）に転送すると更に安全です。

6.3 スケールアウト時の注意点（Swarm / Kubernetes）

Keycloak を水平スケーリングする場合、データベースは外部化（マネージド RDS 等）が必須です。分散キャッシュを有効にすれば複数インスタンス間でセッション情報が共有されます。

• Docker Swarm：deploy.replicas: 3 と resources.limits を設定し、ロードバランサは Ingress が TLS 終端を担います。
• Kubernetes：PostgreSQL は StatefulSet、Keycloak は Deployment＋Service（ClusterIP）で構成し、外部からのアクセスは LoadBalancer または Ingress で HTTPS を終端します【8】。

要点：スケールアウト時は「データベース＝単一障害点」にならないよう、外部マネージド DB と分散キャッシュを組み合わせることが実務的です。

7. 次のステップとサンプルファイルの取得

ここまでで公式 Quarkus イメージを用いた Keycloak の Docker デプロイ手順を網羅しました。実際に環境構築を進めるには、以下のフローがおすすめです。

1. 本記事中の docker-compose.yml をローカルへ保存（ファイル名は任意）。
2. secrets/ ディレクトリを作成し、管理者パスワードと DB パスワードを書き込みます。例：

bash
echo "StrongP@ssw0rd!" > secrets/kc_admin_pwd.txt
echo "DBSecret123!" > secrets/db_password.txt
chmod 600 secrets/*.txt
3. コンテナ起動と確認：

bash
docker compose up -d
docker compose logs -f keycloak # Ready メッセージが出るまで待つ

1. http://localhost:8080 にアクセスし、管理者アカウントでログイン。
2. バックアップや TLS 設定を本番環境に合わせて調整します。

詳細なバージョン情報や更新手順は 公式 Keycloak ドキュメント（https://www.keycloak.org/）と GitHub リリースページ を随時確認してください。

参考文献

1. Keycloak 24 Release Notes – https://www.keycloak.org/2025/12/release-notes
2. Docker Hub – quay.io/keycloak/keycloak Dockerfile (tag 24.0.7) – https://hub.docker.com/r/quay.io/keycloak/keycloak/dockerfile
3. Keycloak Release Policy – https://www.keycloak.org/docs/latest/release_policy/
4. Running Keycloak with Docker – Official Documentation, §“Docker networking” – https://www.keycloak.org/server/containers
5. Traefik Documentation – TLS with Let's Encrypt – https://doc.traefik.io/traefik/https/tls/
6. Configuring HTTPS for Keycloak – https://www.keycloak.org/server/https
7. Docker Docs – Manage data in containers – https://docs.docker.com/storage/volumes/
8. Kubernetes Documentation – Deployments and Services – https://kubernetes.io/docs/concepts/workloads/controllers/deployment/