Contents
KeycloakをDockerで構築するメリットと基本的な流れ
KeycloakをDocker環境で構築することで、開発・テスト環境の迅速なセットアップや、複数プロジェクト間での一貫した認証管理が可能になります。特にDevOpsエンジニアやシステム管理者にとっては、コンテナ技術の利便性とKeycloakの柔軟性を組み合わせた構成が実務に直結します。本記事では、docker-compose.ymlファイルを用いた簡単なセットアップ手順と、永続化設定の要点を解説します。
docker-compose.ymlファイルの基本構成と作成手順
KeycloakをDockerで構築する際、docker-compose.ymlは最も重要な設定ファイルです。このファイルでは、KeycloakコンテナとPostgreSQLデータベースとの連携を明確に定義します。
サービス定義の要点
docker-compose.ymlには、KeycloakとPostgreSQLそれぞれのサービスが含まれます。以下が基本的な構成例です：
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 |
version: '3.9' services: keycloak: image: jboss/keycloak:25.0 ports: - "8080:8080" environment: DB_VENDOR: POSTGRES DB_ADDR: postgres DB_PORT: 5432 DB_DATABASE: keycloak DB_USER: keycloak DB_PASSWORD: <your_password> volumes: - keycloak_data:/opt/jboss/keycloak postgres: image: postgres:16 environment: POSTGRES_DB: keycloak POSTGRES_USER: keycloak POSTGRES_PASSWORD: <your_password> volumes: - postgres_data:/var/lib/postgresql/data volumes: keycloak_data: postgres_data: |
注意:
-versionは常に最新のDocker Composeバージョンに合わせることを推奨します（例: '3.9'）。
-DB_PASSWORDなどの明文パスワード記述はセキュリティリスクです。実環境ではDocker Secretsや.envファイルで管理することを強く推奨します。
環境変数の設定方法
KeycloakとPostgreSQLの接続には、環境変数が不可欠です。以下に主な項目を一覧化しました：
| 項目 | 値 | 補足 |
|---|---|---|
DB_VENDOR |
POSTGRES |
使用するデータベースの種類 |
DB_ADDR |
postgres |
PostgreSQLコンテナ名（Docker内部） |
DB_PORT |
5432 |
PostgreSQLのデフォルトポート |
DB_DATABASE |
keycloak |
Keycloak用データベース名 |
DB_USER |
keycloak |
データベースユーザー |
DB_PASSWORD |
<your_password> |
DBアクセス用パスワード（推奨: セキュリティ管理で設定） |
セキュリティ注意:
実環境では、DB_PASSWORDは環境変数ファイルなどで管理し、明文での記述を避けるべきです。
ポートマッピング設定と外部アクセスの確認方法
KeycloakコンテナをホストOSからアクセスできるようにするためには、ポートマッピングが必須です。また、ファイアーウォールやネットワーク構成によっては、接続テストが失敗することがあります。
HTTP/HTTPSポートの違い
KeycloakはデフォルトでHTTPの8080ポートを使用します。HTTPSを有効にする場合は、証明書を設定し、443ポートにマッピングする必要があります。しかし、開発環境ではHTTP接続で十分な場合が多いため、初期構築時は8080ポートを指定するのが一般的です。
KeycloakとPostgreSQLの連携設定方法
KeycloakはPostgreSQLに認証情報を永続化するため、適切なデータベース接続設定が重要です。また、セキュリティを重視する場合は、環境変数でのパスワード管理やVolumeによるデータ保存が推奨されます。
永続化用Volumeの指定
KeycloakとPostgreSQLそれぞれにVolumeを指定することで、データがコンテナ再起動時でも保持されます：
keycloak_data: Keycloakの設定・ユーザーデータを永続化（公式イメージでは/opt/jboss/keycloakに保存されるため、このパスを明記する必要があります）postgres_data: PostgreSQLのデータベースファイルを永続化
管理画面へのアクセス確認手順と初期設定
Keycloak構築後は、管理画面にアクセスし、初期設定を行う必要があります。特に認証フローの構成やデフォルトユーザーの変更が重要です。
初期アカウントの変更方法
デフォルトで使用できるユーザーはadminで、パスワードはadminです。ただし、セキュリティ強化のために必ず初期パスワードを変更してください：
http://localhost:8080/auth/admin/にアクセス- ログイン画面で
adminユーザーと初期パスワードを入力 - 「Change Password」から新しいパスワードを設定
注意: 本番環境では、管理アカウントのパスワードポリシー（最小文字数・特殊文字含むなど）を厳格化する必要があります。
データ永続化のベストプラクティスとVolumeの活用
KeycloakとPostgreSQL共にデータ永続化がなければ、コンテナの停止や削除時にデータが失われる可能性があります。これを防ぐためにも、Volumeを上手く活用する必要があります。
コンテナ再起動時のデータ保持
Volumeを使用することで、コンテナを再起動・再構築してもデータが残ります：
- Keycloak:
/opt/jboss/keycloakに永続化された設定とユーザーデータが保存されます - PostgreSQL:
/var/lib/postgresql/dataにデータベースファイルが保存され、DBの再構築を必要としません
構築時のよくあるエラーとその解決策
Keycloak構築時に発生する代表的なエラーには、ポート競合やデータベース接続失敗があります。それぞれの原因と対処法を解説します。
ポート競合時の対処
docker-compose upで以下のようなエラーが発生した場合、すでに8080ポートを使用しているプロセスがある可能性があります：
|
1 2 |
ERROR: failed to create task for service keycloak: Could not attach to network |
解決法:
lsof -i :8080で使用中のアプリケーションを確認- 使用中であれば、ポート変更（例:
8081:8080）や停止する
データベース接続失敗の原因
KeycloakがPostgreSQLにアクセスできない場合は、以下の点を検証してください：
- PostgreSQLコンテナが起動しているか (
docker ps) - 環境変数
DB_ADDR,DB_PORTが正しく設定されているか - ネットワークの設定（デフォルトではDockerネットワークで自動接続される）
解決法:
- Keycloakコンテナ内でPostgreSQLにpingを送信 (
docker exec -it keycloak ping postgres) - 接続できなければ、
DB_ADDRをホスト名（例:postgres）に変更
トラブルシューティングのコツ: Dockerログは
docker logs keycloakで確認可能です。エラーメッセージから原因を特定しやすいので、まずはこれをチェックしましょう。