Keycloak на Quarkus

Модуль содержит кодовую базу для запуска Keycloak поверх Quarkus:

├── container
│   ├── Dockerfile, например, используется тестовым набором
│
├── deployment
│   └── Сборка кода во время сборки со всеми необходимыми шагами для сборки и настройки сервера
│
├── dist
│   └── Упаковка дистрибутива quarkus
│
├── runtime
│   └── Кодовая база времени выполнения со всем кодом времени выполнения
│
├── server
│   └── Сам сервер, отвечает только за генерацию артефактов сервера
│
└── tests
    └── Интеграционные тесты для дистрибутива quarkus

Необходимые условия

Убедитесь, что у вас установлен JDK 11 или более поздней версии. Ваша оболочка находится в подмодуле quarkus. (cd quarkus)

Активация модуля из корневого каталога

Когда запускается сборка из корневого каталога проекта, этот модуль включается только в том случае, если установленный JDK — 11 или новее.

Сборка проекта в первый раз

Чтобы собрать этот модуль и создать артефакты для запуска сервера, сначала необходимо один раз собрать основную кодовую базу. Этот шаг поместит необходимые модули keycloak в ваш локальный кэш maven в пакете org.keycloak:

../mvnw -f ../pom.xml clean install -DskipTestsuite -DskipExamples -DskipTests

Эта сборка может занять некоторое время, обычно около двух-четырёх минут в зависимости от вашего оборудования и даже дольше в зависимости от пакетов maven, которые необходимо загрузить и установить в кэш.

Создание дистрибутива Keycloak Quarkus

После сборки основной кодовой базы можно собрать дистрибутив quarkus, включая файлы zip и tar.gz, выполнив следующую команду:

../mvnw clean install -DskipTests

Эта команда создаёт артефакты дистрибутива в виде файлов ZIP и TAR. После этого артефакты для дистрибутива quarkus будут доступны в подкаталоге /dist/target.

В качестве альтернативы вы можете собрать артефакты дистрибутива напрямую без перестройки кода, выполнив следующую команду:

../mvnw -f dist/pom.xml clean install

Запуск в режиме разработки Keycloak

При запуске Keycloak в рабочем режиме порт HTTP по умолчанию отключён, и вам необходимо предоставить ключевой материал для настройки HTTPS, имя хоста и другую конфигурацию, подходящую для рабочего режима.

Для целей разработки вы можете запустить сервер в режиме разработки с помощью start-dev:

java -jar server/target/lib/quarkus-run.jar start-dev

Это запускает Keycloak с использованием базы данных разработки (h2-файл) и с включённым небезопасным HTTP.

Запуск из вашей IDE

Кроме того, вы можете запустить сервер в режиме разработки из своей IDE. Для этого запустите основной класс org.keycloak.quarkus._private.IDELauncher в каталоге server.

Вклад

Пожалуйста, перед тем как внести свой вклад, ознакомьтесь с нашими Руководящими принципами вклада.

Чтобы запустить сервер в режиме разработки Quarkus, выполните следующую команду:

../mvnw -f server/pom.xml compile quarkus:dev -Dquarkus.args="start-dev"

Вы сможете подключить отладчик к порту 5005.

Чтобы отладить шаги сборки сразу после запуска, вы можете приостановить JVM, запустив:

../mvnw -f server/pom.xml -Dsuspend=true compile quarkus:dev -Dquarkus.args="start-dev"

При работе с quarkus:dev вы можете выполнять живое кодирование всякий раз, когда вы изменяете / добавляете код в модуль server, например при создании нового пользовательского провайдера.

Существуют ограничения при работе в режиме разработки, которые не позволяют нам использовать все возможности, которые может предложить режим разработки Quarkus. Например, горячая перезагрузка временных зависимостей от keycloak (например: keycloak-* зависимости) не работает. Ожидайте больше улучшений в этой области и не стесняйтесь обращаться за помощью, используя наши обсуждения или список рассылки разработчиков.

Выполнение тестов

Модуль дистрибутива Quarkus Keycloak использует новый набор тестов, более интегрированный в платформу quarkus.

Выполнение тестов из вашей IDE

Тесты также можно запускать из графического интерфейса IDE, такого как Intellij IDEA. Есть Различные виды тестов:

• Модульные тесты: расположены в соответствующем модуле (развёртывание, время выполнения).
• Интеграционные тесты:
  • с аннотацией @CLITest: эти тесты не имеют предварительных условий и являются тестами «белого ящика», поэтому их легко отлаживать.
  • с аннотацией @DistributionTest: для запуска этих тестов сначала требуется сборка дистрибутивных артефактов. Это тесты «чёрного ящика», поэтому они не так легко поддаются отладке, как тесты с аннотацией @CLITest. В основном используются для сценариев, когда задействована сборка или необходимо изменить параметры сборки, поскольку этот вызов происходит в другой JVM.

Запуск контейнерных тестов

Тесты с аннотацией @DistributionTest могут использовать разные среды выполнения, например, обычную JVM или контейнер Docker. По умолчанию они используют режим обычной JVM.

Чтобы запустить их из образа контейнера, сначала нужно собрать дистрибутив. Затем можно использовать флаг -Dkc.quarkus.tests.dist=docker. Это создаст образ Docker из предоставленных архивов дистрибутива и запустит для них тесты с аннотацией @DistributionTest.

Есть несколько тестов с аннотацией @RawDistOnly, которая запрещает их запуск в Docker. Вы найдёте краткую причину в соответствующей аннотации.

Контейнерные тесты используют Testcontainers для развёртывания образа контейнера и могут считаться техническим предварительным просмотром.

Выполнение тестов базы данных

Также есть некоторые контейнерные тесты, чтобы проверить, запускается ли Keycloak с использованием одного из поддерживаемых поставщиков баз данных. Они аннотированы с помощью @WithDatabase.

Эти тесты по умолчанию отключены. Они используют предопределённые контейнеры базы данных режима разработки Quarkus по умолчанию и могут быть запущены в подкаталоге tests, используя, например:

../mvnw clean install -Dkc.test.storage.database=true -Dtest=MariaDBStartDatabaseTest

чтобы развернуть контейнер MariaDB и запустить с ним Keycloak.

Чтобы использовать конкретный образ контейнера базы данных, используйте опцию -Dkc.db.postgresql.container.image, чтобы указать тег образа postgres для использования, или -Dkc.db.mariadb.container.image=<name:tag> для mariadb.

Пример:

../mvnw clean install -Dkc.test.storage.database=true -Dtest=PostgreSQLDistTest -Dkc.db.postgresql.container.image=postgres:alpine

Обновление ожиданий

Переход к выводу справки приведёт к сбою HelpCommandDistTest. Можно использовать:

KEYCLOAK_REPLACE_EXPECTED=true ../mvnw clean install -Dtest=HelpCommandDistTest 

для замены ожидаемого вывода, а затем использовать diff, чтобы убедиться, что изменения выглядят хорошо.