This section describes how to run Keycloak in Quarkus development mode. Before continuing, make sure you have already followed the main project build and prerequisites documentation, which explains all required tools (JDK, Maven, etc.).
This module holds the codebase to run Keycloak on top of Quarkus:
├── config-api
│ ├── Configuration API for modules to avoid direct Quarkus coupling (e.g. for REST services module)
│
├── container
│ ├── Dockerfile, e.g. used by the Testsuite
│
├── deployment
│ ├── Build-time codebase with all the necessary steps to build and configure the server
│
├── dist
│ ├── Packaging the Quarkus distribution
│
├── runtime
│ ├── Runtime codebase with all the runtime code
│
├── server
│ ├── The server itself, only responsible for generating the server artifacts
│
└── tests
├── Integration tests for the Quarkus distribution
Keycloak on Quarkus is basically a Quarkus Extension. For more details about extensions, please take a look at Writing Your Own Extension guide.
As an extension, the server can be embedded in any Quarkus application by adding the following dependency:
<dependencies>
<dependency>
<groupId>org.keycloak</groupId>
<artifactId>keycloak-quarkus-server</artifactId>
</dependency>
</dependencies>
Just like any other extension, the server extension has two main modules:
deploymentruntime
Within the deployment module you'll find the implementation for the build steps that run when (re)augmenting the application. This module
is responsible for all metadata processing, such as:
- Lookup SPIs and their providers and enable/disable them accordingly
- Create a closed-world assumption about the providers that should be registered to the
KeycloakSessionFactory - Customizations to how Hibernate, Quarkus REST, Liquibase, Infinispan, and other dependencies are configured and bootstrapped
- Creating Jandex indexes for some server dependencies
The output of this module is bytecode generated by Quarkus that improves the server startup time and memory usage so that any processing
done during (re)augmentation does not happen again when actually starting the server. Note that the code from this module does
not run at all at runtime (when running the server) but only when building the project (the server module in particular, more on that later) or when triggering
a re-augmentation when running the build command.
Within the runtime module you'll find the code that is run at runtime when starting and running the server. The main link between
the deployment and runtime modules is the org.keycloak.quarkus.runtime.KeycloakRecorder class. The KeycloakRecorder holds
a set of methods that are invoked from build steps that will end up in recorded bytecode. The recorded bytecode executes those methods at runtime
just like they were called when a build step was run, with the exact same arguments and values, if any.
As an example, let us look at how the SPIs and their providers are discovered and how the KeycloakSessionFactory is created.
Quarkus will run the org.keycloak.quarkus.deployment.KeycloakProcessor.configSessionFactory build step whenever you are (re)augmenting the server. The main outcome from this method
is to invoke the org.keycloak.quarkus.runtime.KeycloakRecorder.configSessionFactory so that the code from this method is executed at
runtime with a closed-world assumption about the providers that should be registered to the KeycloakSessionFactory. At runtime the code from that method is executed
and a KeycloakSessionFactory is created without any processing to discover SPIs and their providers.
There are a few reasons why we have Keycloak as a Quarkus extension:
- More control over the build-time augmentation and runtime stages.
- More flexibility when extending Quarkus itself and the extensions used by the server (e.g.: Hibernate, Quarkus REST, etc.)
- Make it easier to embed the server into Quarkus applications
- Make it possible to allow Keycloak developers to customize the server distribution
The server module holds the Keycloak Server itself. It is basically a regular Quarkus application using the keycloak-quarkus-server extension. If you look at the
pom.xml from this module you'll notice that it is a very simple Quarkus application with the bare minimum configuration
to actually build and run the server.
As Quarkus application, the server is a mutable application using the mutable-jar package type. As a mutable application, Keycloak is able to allow users to configure some aspects of the server without having to re-build this module, something impractical from a user perspective.
The mutability of the server is directly related to the build command. As mentioned before, the build steps from the deployment module
are only run when (re)augmenting the server and when running the build command, the server will indicate to Quarkus that the build steps
should re-run and the recorded bytecode should be updated to reflect any change to the server configuration.
From a Quarkus perspective, the server is also a Command Mode Application and provides
a CLI based on Picocli. As such, there is a single entrypoint that executes the code to execute the CLI and bootstrap the server. This entry point
is the org.keycloak.quarkus.runtime.KeycloakMain class from the runtime module.
The server distribution is created by build the dist module. This module basically consists of packaging the deployment, runtime,
and server modules artifacts and their dependencies to a ZIP or tarball file.
Within this directory you'll find the directory structure of the distribution and what is included in it.
Before using this module, make sure you have a compatible JDK installed. (See main build instructions). Your shell is located at the quarkus submodule:
<KEYCLOAK_HOME> $ cd quarkus
KEYCLOAK_HOMEis the directory where you cloned the Keycloak repository.
To build this module and produce the artifacts to run a server, you first need to build the main codebase once. This step will put required modules of keycloak into your local maven cache in package org.keycloak:
<KEYCLOAK_HOME>/quarkus $ ../mvnw -f ../pom.xml clean install -DskipTestsuite -DskipExamples -DskipTests
This build can take some time, usually around two to four minutes depending on your hardware, and even longer depending on the maven packages that need to be downloaded and installed to the cache.
After the main codebase is built, you can build the Quarkus distribution, including the zip and tar.gz files, by invoking the following command:
<KEYCLOAK_HOME>/quarkus $ ../mvnw clean install -DskipTests
This command produces the distribution artifacts as ZIP and TAR file. The artifacts for the Quarkus distribution will be available at the /dist/target subdirectory afterwards.
As an alternative, you can build the distribution artifacts directly without a rebuild of the code by running the following command:
<KEYCLOAK_HOME>/quarkus $ ~/keycloak/quarkus $ ../mvnw -f dist/pom.xml clean install
When you start Keycloak in production mode, the HTTP port is disabled by default, and you need to provide the key material to configure HTTPS, a hostname and other configuration suitable for production.
For development purposes, you can run the server in development mode instead using start-dev.
Alternatively, you can run the server in development mode from your IDE. For that, run the org.keycloak.Keycloak main class in the tests/junit5 directory.
If you have problems starting the server in debug mode, add following environment variables to your run config:
-Djava.util.logging.manager=org.jboss.logmanager.LogManager
-Djava.util.concurrent.ForkJoinPool.common.threadFactory=io.quarkus.bootstrap.forkjoin.QuarkusForkJoinWorkerThreadFactory
Set the kc.home.dir environment variable for keeping state between startups:
-Dkc.home.dir=.kc
To run the server in Quarkus' development mode, invoke the following command:
<KEYCLOAK_HOME>/quarkus $ ../mvnw -f server/pom.xml compile quarkus:dev -Dkc.config.built=true -Dquarkus.args="start-dev"
You will be able to attach your debugger to port 5005.
You can set any command or configuration option to the server by setting the quarkus.args environment variable.
For debugging the build steps right after start, you can suspend the JVM by running:
<KEYCLOAK_HOME>/quarkus $ ../mvnw -f server/pom.xml -Dsuspend=true compile quarkus:dev -Dkc.config.built=true -Dquarkus.args="start-dev"
Expected behavior: The server will start on http://localhost:8080.
There are currently limitations when running in development mode that block us to use all capabilities the Quarkus development mode has to offer. The main limitations you'll find at the moment are:
- Changes are only automatically reflected at runtime if you are changing resources from the quarkus
deployment,runtime, andservermodules. Non-quarkus modules, such askeycloak-services, still rely on Hot Swap in Java debuggers to reload classes. - There is nothing in the Dev UI related to the server itself, although you can still change some configuration from there.
- quarkus.args does not honor build time options. Those instead must also be set via -D arguments, or environment variables, and thus require rerunning the quarkus:dev command to change.
The kc.sh|bat script allows you to remotely debug the distribution. For that, you should run the server as follows:
kc.sh --debug start-dev
By default, the debug port is available at 8787 on localhost. Additionally, you can specify IPv4 or bracketed IPv6 addresses with optional ports, e.g. --debug 127.0.0.1:8786, --debug [::1]:8785. Make sure to exercise caution when setting IP addresses in the --debug parameter, since a value such as --debug 0.0.0.0:8787 will expose the debug port to all network interfaces!
An additional environment variable DEBUG_SUSPEND can be set to suspend the JVM, when launched in debug mode. The DEBUG_SUSPEND variable supports the following values:
y- The debug mode JVM launch is suspendedn- The debug mode JVM is started without suspending
Suspending the JVM when in debug mode is useful if you want to debug the early stages of the bootstrap code.
When making changes to the deployment, runtime, or server modules, you can update the distribution with the new artifacts by executing
the following command:
mvn -DskipTests clean install
After the quarkus module and sub-modules are built, you can update the distribution as follows:
cp -r server/target/lib ${KC_HOME_DIR}
In the example above, the ${KC_HOME_DIR} variable points to the root directory of the distribution.
You should also be able to update a server dependency directly. For that, copy the jar to the following location:
cp services/target/keycloak-services-${KC_VERSION}.jar ${KC_HOME_DIR}/lib/lib/main/org.keycloak.keycloak-services-${KC_VERSION}.jar
The documentation is a set of guides available from the docs module. Please, look at the guide about how to update and build the distribution guides.
Before contributing changes, make sure to read the main Keycloak Contributing Guide.
Please, make sure:
- Documentation is updated if you are introducing any new behavior or changing an existing one that needs to be communicated
- Make sure you have a test within the tests/integration module to cover the changes
- You probably want to run a full build of the
quarkusmodule, including running tests, to make sure you won't be surprised by failures in CI.
Keycloak Quarkus distribution module uses a new testsuite more integrated into the Quarkus platform.
The tests can also be run from an IDE GUI such as Intellij IDEA. There are different kinds of tests:
- Unit tests: Located in the respective module (
deployment,runtime) - Integration tests:
@CLITestannotated: These tests have no prerequisites and are whitebox tests, so you can easily debug them.@DistributionTestannotated: These tests need a build of the distribution artifacts first to run. These are blackbox tests, so not as easily debuggable as@CLITestannotated tests. Mostly used for scenarios when abuildis involved or build options need to change, as this invocation may happen in a different JVM.
The @DistributionTest annotated tests can use different runtimes, e.g. plain JVM or a Docker container. Per default, they use the plain JVM mode.
To run them from a container image instead, you need to build the distribution first. Then you can use the flag -Dkc.quarkus.tests.dist=docker. This builds a Docker image from the provided distribution archives and runs the @DistributionTest annotated tests for them.
There are some tests annotated @RawDistOnly which prevents them from running in Docker. You'll find a short reason in the respective annotation.
There are also some container based tests to check if Keycloak starts using one of the supported database vendors. They are annotated with @WithDatabase.
The storage tests are disabled by default but can be activated using the test-database profile.
They're using Quarkus development mode predefined database containers by default and can be run in the tests subdirectory by using e.g.
<KEYCLOAK_HOME>/quarkus $ ../mvnw clean install -Ptest-database -Dtest=MariaDBDistTest
to spin up a MariaDB container and start Keycloak with it.
To use a specific database container image, use the option -Dkc.db.postgresql.container.image to specify the image tag of the Postgres image to use or -Dkc.db.mariadb.container.image=<name:tag> for MariaDB.
Example:
<KEYCLOAK_HOME>/quarkus $ ../mvnw clean install -Ptest-database -Dtest=PostgreSQLDistTest -Dkc.db.postgresql.container.image=postgres:alpine
Changing to the help output will cause HelpCommandDistTest to fail. This test uses ApprovalTests which creates .received.txt files containing the actual output when tests fail. To update the expected output (see Approving The Result) run:
KEYCLOAK_REPLACE_EXPECTED=true ../mvnw clean install -Dtest=HelpCommandDistTest
then use a diff to ensure the changes look good.
Sometimes you might want to run the tests from the base test suite using the distribution. For that, make sure you have built the quarkus module
and then execute the following command from the project root directory:
mvn -f testsuite/integration-arquillian/pom.xml clean install -Pauth-server-quarkus -Dtest=OIDCProtocolMappersTest
In order to avoid using external services for DNS resolution, the tests are executed using a local host file by setting the -Djdk.net.hosts.file=${project.build.testOutputDirectory}/hosts_file system property.
Upgrading Quarkus requires a few steps:
- Change the Quarkus version
- Change the dependencies we are using from Quarkus
- Run a build to make sure the server extension is not broken
The steps still require a lot of manual work, and we should be improving this.
To change the Quarkus version, you can run the following script:
./set-quarkus-version.sh <version>The set-quarkus-version.sh script is enough to change the version for all dependencies we are
using from Quarkus.
The <version> should point to a branch or a tag from Quarkus repository.
It is also possible to change to a snapshot version by running:
./set-quarkus-version.shAfter setting the version, please verify that:
org.apache.mavendependencies used by the test suite (and arquillian) are the same from the new Quarkus version
After changing the dependency versions, you can run a local build to make sure the server extension is not broken by API changes and if all tests are passing:
mvn clean install
It might happen that when upgrading a version for any of the JDBC extensions (e.g.: quarkus-jdbc-postgresql) you also need to make sure the server extension is using the same JDBC Drivers.
For that, you should look at the deployment module of the corresponding JDBC extension from Quarkus (e.g.: https://github.com/quarkusio/quarkus/blob/main/extensions/jdbc/jdbc-postgresql/deployment/src/main/java/io/quarkus/jdbc/postgresql/deployment/JDBCPostgreSQLProcessor.java) to check if they match with the drivers used by the server extension by looking at the org.keycloak.config.database.Database class.
The perfect scenario is that after performing all the steps above the server extension will compile, the distribution can be built, and all tests will pass.
However, it is expected breaking changes between Quarkus upgrades that break the integration code we have in both deployment and runtime modules. When this happens, you should understand what is breaking and upgrade the integration code accordingly.