【備忘録】Docker Composeで構築したquay.ioのKeycloakを本番モードで動かすためのメモ書き

はじめに

この記事はDocker Composeで構築したquay.ioベースのKeycloakを本番モードで実行するためのメモ書きです。

まずは通常の開発モードからオレオレ証明書を発行してHTTPS対応させて本番モードで動かせるようにします。

環境

OS: NixOS 23.11
Docker Compose: Docker Compose version 2.19.1
Keycloak: quay.io/keycloak/keycloak:22.0.1

Keycloakを本番モードで動かすために

まずはKeycloakを開発モードで動かすためのcompose.ymlファイルです。

compose.yml

services:
  # keycloak
  keycloak:
    image: quay.io/keycloak/keycloak:22.0.1
    tty: true
    stdin_open: true
    ports:
        - 8080:8080
    environment:
      KEYCLOAK_ADMIN: admin
      KEYCLOAK_ADMIN_PASSWORD: password
    command:
      - start-dev

こちらのcompose.ymlファイルをもとにKeycloakを本番モードで動かすことができるようにします。

Keycloakを本番モードで動かすためのコマンドは、Configuring Keycloak
Starting Keycloak in production mode
で紹介されているように、startです。これはcompose.ymlファイルのcommandの部分を書き換えることで実現できます。

しかし現状の設定のままで本番モードを動かそうとするとエラーが発生してしまいます。

ERROR: Unexpected error when starting the server in (production) mode
ERROR: Failed to start quarkus
ERROR: Strict hostname resolution configured but no hostname setting provided

これは、上記のサイトにもありますが、起動時にホスト名が設定されており、HTTPS/TLS設定が利用可能であることを期待されているためです。

Keycloakを本番モードで動かせるようにする

ホスト名の設定

まずはホスト名の設定を行います。

ホスト名の設定に関しては、

のページで詳しく解説されています。

今回はDocker Composeを使用していますので、KC_HOSTNAMEという環境変数にホスト名を渡してあげるだけで良いです。

HTTPS対応

続いてHTTPS対応を行います。

こちらの設定に関しては、

と、

のページで詳しく解説されています。

証明書と秘密鍵を用意し、KC_HTTPS_CERTIFICATE_FILE環境変数とKC_HTTPS_CERTIFICATE_KEY_FILE環境変数の場所にそれぞれ配置します。今回はオレオレ証明書を使用します。

$ openssl req -x509 -out keycloak.crt -keyout keycloak.key -newkey rsa:2048 -nodes -sha256 -subj '/C=JP'
$ chmod 640 keycloak.key

なお証明書の発行時に空のサブジェクトDNを渡すと怒られてしまいます。

2023-08-11 13:08:50,633 ERROR [org.keycloak.quarkus.runtime.cli.ExecutionExceptionHandler] (main) ERROR: Failed to start server in (production) mode
2023-08-11 13:08:50,634 ERROR [org.keycloak.quarkus.runtime.cli.ExecutionExceptionHandler] (main) ERROR: Unable to start HTTP server
2023-08-11 13:08:50,634 ERROR [org.keycloak.quarkus.runtime.cli.ExecutionExceptionHandler] (main) ERROR: io.vertx.core.VertxException: java.security.cert.CertificateParsingException: Empty issuer DN not allowed in X509Certificates
2023-08-11 13:08:50,634 ERROR [org.keycloak.quarkus.runtime.cli.ExecutionExceptionHandler] (main) ERROR: java.security.cert.CertificateParsingException: Empty issuer DN not allowed in X509Certificates
2023-08-11 13:08:50,634 ERROR [org.keycloak.quarkus.runtime.cli.ExecutionExceptionHandler] (main) ERROR: Empty issuer DN not allowed in X509Certificates
2023-08-11 13:08:50,634 ERROR [org.keycloak.quarkus.runtime.cli.ExecutionExceptionHandler] (main) For more details run the same command passing the '--verbose' option. Also you can use '--help' to see the details about the usage of the particular command.

また秘密鍵にはグループ読み込み権限を与える必要がありました。

2023-08-11 13:02:46,186 ERROR [org.keycloak.quarkus.runtime.cli.ExecutionExceptionHandler] (main) ERROR: Failed to start server in (development) mode
2023-08-11 13:02:46,186 ERROR [org.keycloak.quarkus.runtime.cli.ExecutionExceptionHandler] (main) ERROR: /etc/x509/https/keycloak.key
2023-08-11 13:02:46,187 ERROR [org.keycloak.quarkus.runtime.cli.ExecutionExceptionHandler] (main) For more details run the same command passing the '--verbose' option. Also you can use '--help' to see the details about the usage of the particular command.

--verboseオプションを付けて詳細を確認してね！と、ありますがヘルプを確認してもこのオプションは存在しないという罠....

compose.ymlファイルの修正

最終的なcompose.ymlファイルは以下のようになります。証明書と秘密鍵のマウント先に関しては、Keycloak SSL setup using docker imageを参考にしました。

compose.yml

services:
  # keycloak
  keycloak:
    image: quay.io/keycloak/keycloak:22.0.1
    tty: true
    stdin_open: true
    volumes:
      - ./certs/keycloak.crt:/etc/x509/https/keycloak.crt
      - ./certs/keycloak.key:/etc/x509/https/keycloak.key
    ports:
        - 8443:8443
    environment:
      KEYCLOAK_ADMIN: admin
      KEYCLOAK_ADMIN_PASSWORD: password
      KC_HOSTNAME: localhost
      KC_HTTPS_CERTIFICATE_FILE: /etc/x509/https/keycloak.crt
      KC_HTTPS_CERTIFICATE_KEY_FILE: /etc/x509/https/keycloak.key
    command:
      - start

docker compose upコマンドを実行することで、Keycloakが本番モードで動くようになります。
https://localhost:8443にアクセスするとKeycloakのページが表示されるはずです。

まとめ

今回の記事ではDocker Composeで構築したKeycloakを本番モードで動かすための方法をまとめました。

--verboseオプションが見当たらず、秘密鍵の権限周りで苦戦したため、記事にまとめることを決めました。KC_LOG_LEVELという環境変数が用意されていることを道中で見つけたのですが、こちらを設定しても解決策を見つけることができず。

なおデータベースなど、その他の設定については、

のページから確認することができます。