From 858107233f62c41cd76c4876695b03e35ddecee4 Mon Sep 17 00:00:00 2001 From: Dominik Guhr Date: Wed, 9 Feb 2022 10:36:52 +0100 Subject: [PATCH 1/2] Readme review v1 Overhaul of the quarkus readme file and others Closes #9216 --- quarkus/README.md | 95 +++++++++++++------ quarkus/dist/src/main/README.md | 4 +- quarkus/dist/src/main/content/conf/README.md | 2 +- .../dist/src/main/content/providers/README.md | 4 +- .../dist/src/main/content/themes/README.md | 10 +- quarkus/dist/src/main/version.txt | 2 +- .../database/MariaDBStartDatabaseTest.java | 4 - 7 files changed, 78 insertions(+), 43 deletions(-) diff --git a/quarkus/README.md b/quarkus/README.md index 271cc29a6725..cffc1f266e48 100644 --- a/quarkus/README.md +++ b/quarkus/README.md @@ -3,66 +3,105 @@ The module holds the codebase to run Keycloak on top of [Quarkus](https://quarkus.io/): ``` +├── 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 +├── server +│   ├── The server itself, only responsible for generating the server artifacts +│ +└── tests + ├── Integration tests for the quarkus distribution ``` -## Activating the Module +## Prerequisites +Ensure you have at least JDK 11 installed. +Your shell is located at the `quarkus` submodule. (`cd quarkus`) -When build from the project root directory, this module is only enabled if the installed JDK is 11 or newer. +### Activating the Module from the root directory +When a build from the project root directory is started, this module is only enabled if your installed JDK is 11 or newer. -## Building +## Building the project the first time -Ensure you have JDK 11 (or newer) installed. - -To build the module and produce the artifacts to run a server: +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`: mvn -f ../pom.xml clean install -DskipTestsuite -DskipExamples -DskipTests -### Building the Distribution - -To build the module as well as the distribution packages: +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. - mvn -f ../pom.xml clean install -DskipTestsuite -DskipExamples -DskipTests -Pdistribution +## Building the Keycloak Quarkus distribution -The distribution packages (ZIP and TAR) should be available at [../distribution/server-x-dist](../distribution/server-x-dist/target). +After the main codebase is built, you can build the quarkus distribution, including the zip and tar.gz files, by invoking the following command: + + mvn 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. -Alternatively, you can also build the distribution directly by running the following command: +As an alternative, you can build the distribution artifacts directly without a rebuild of the code by running the following command: - mvn -f ../distribution/server-x-dist/pom.xml clean install + mvn -f dist/pom.xml clean install -## Running +## Running in Keycloak development mode +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. -By default, the HTTP port is disabled and you need to provide the key material to configure HTTPS. If you want to enable -the HTTP port, run the server in development mode as follows: +For development purposes, you can run the server in development mode instead using `start-dev`: java -jar server/target/lib/quarkus-run.jar start-dev -## Contributing +This spins up Keycloak using a development database (h2-file) and with insecure HTTP enabled. + +### Running from your IDE +Alternatively, you can run the server in development mode from your IDE. For that, run the `org.keycloak.quarkus._private.IDELauncher` main class in the `server` directory. -### Development Mode +## Contributing +Please make sure to read our [Contribution Guidelines](../CONTRIBUTING.md) before contributing. -To run the server in development mode: +To run the server in Quarkus' development mode, invoke the following command: mvn -f server/pom.xml compile quarkus:dev -Dquarkus.args="start-dev" -You should be able to attach your debugger to port `5005`. +You will be able to attach your debugger to port `5005`. -For debugging the build steps, you can suspend the JVM by running: +For debugging the build steps right after start, you can suspend the JVM by running: mvn -f server/pom.xml -Dsuspend=true compile quarkus:dev -Dquarkus.args="start-dev" -When running using `quarkus:dev` you should be able to do live coding whenever code changes within the `server` module. Changes you make to transient dependencies from the server extension (e.g: services, model, etc) won't be reflected into the running server. However, you can still leverage the hot swapping capabilities from your IDE to make changes at runtime. +When running using `quarkus:dev` you are able to do live coding whenever you change / add code in the `server` module, for example when creating a new custom provider. + +There are currently limitations when running in development mode that block us to use all capabilities the Quarkus development mode has to offer. For instance, hot-reload of transient dependencies from keycloak (e.g.: keycloak-* dependencies) do not work. Expect more improvements in this area, and feel free to reach out if you want to help, using our [discussions](https://github.com/keycloak/keycloak/discussions/categories/keycloak-x-quarkus-distribution) or the development mailing list. + +## Running tests +Keycloaks Quarkus distribution module uses a new testsuite more integrated into the quarkus platform. + +### Running tests from your IDE +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: + * `@CLITest` annotated: These tests have no prerequisites and are whitebox tests, so you can easily debug them. + * `@DistributionTest` annotated: These tests need a build of the distribution artifacts first to run. These are blackbox tests, so not as easily debuggable as `@CLITest` annotated tests. Mostly used for scenarios when a `build` is involved or build options need to change, as this invocation happens in a different JVM. + +### Running container-based tests +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. + +The container based tests are using Testcontainers to spin up the container image and can be considered tech preview. + +### Running database tests +There are also some container based tests to check if Keycloak starts using one of the supported database vendors. They are annotated with `@WithDatabase`. -NOTE: Although still very handy during development, there are some limitations when running in dev mode that -blocks us to leverage all the capabilities from Quarkus dev mode. For instance, hot-reload of transient dependencies from the server extension (e.g.: keycloak-* dependencies) does not work. More improvements should be expected to improve the experience. +These tests are disabled by default. They using Quarkus development mode predefined database containers by default and can be run in the `tests` subdirectory by using e.g. -NOTE: When developing custom providers, you should be able to benefit from live coding as long as you keep changes within the `server` module. + mvn clean install -Dkc.test.storage.database=true -Dtest=MariaDBStartDatabaseTest -Alternatively, you can run the server in development mode from your IDE. For that, run the `org.keycloak.quarkus._private.IDELauncher` main class. +to spin up a MariaDB container and start Keycloak with it. \ No newline at end of file diff --git a/quarkus/dist/src/main/README.md b/quarkus/dist/src/main/README.md index e68a1c0eff1f..b8da78007524 100644 --- a/quarkus/dist/src/main/README.md +++ b/quarkus/dist/src/main/README.md @@ -1,4 +1,4 @@ -Keycloak.X +Keycloak ========== To get help configuring Keycloak via the CLI, run: @@ -23,4 +23,4 @@ on Windows: After the server boots, open http://localhost:8080 in your web browser. The welcome page will indicate that the server is running. -To get started, check the [Server Administration Guide](https://www.keycloak.org/docs/latest/server_admin). \ No newline at end of file +To get started, check out the [configuration guides](https://www.keycloak.org/guides#server). \ No newline at end of file diff --git a/quarkus/dist/src/main/content/conf/README.md b/quarkus/dist/src/main/content/conf/README.md index e352dce68b87..9d25889308c1 100644 --- a/quarkus/dist/src/main/content/conf/README.md +++ b/quarkus/dist/src/main/content/conf/README.md @@ -1,4 +1,4 @@ Configure the server ==================== -Use files in this directory to configure the server. \ No newline at end of file +Files in this directory are used to configure the server. Please consult the [configuration guides](https://www.keycloak.org/guides#server) for more information. \ No newline at end of file diff --git a/quarkus/dist/src/main/content/providers/README.md b/quarkus/dist/src/main/content/providers/README.md index d47220d0a55d..a5eb4e395525 100644 --- a/quarkus/dist/src/main/content/providers/README.md +++ b/quarkus/dist/src/main/content/providers/README.md @@ -3,8 +3,8 @@ Installing Custom Providers Add your custom provider JAR files in this directory. -Once you have your providers in this directory, run the following command to complete the installation: +Once you have your providers files in this directory, run the following command to complete the installation: ``` ${kc.home.dir}/bin/kc.sh build -``` \ No newline at end of file +``` diff --git a/quarkus/dist/src/main/content/themes/README.md b/quarkus/dist/src/main/content/themes/README.md index ce6c1ba9b40f..e0669e326bf8 100644 --- a/quarkus/dist/src/main/content/themes/README.md +++ b/quarkus/dist/src/main/content/themes/README.md @@ -3,13 +3,13 @@ Creating Themes Themes are used to configure the look and feel of login pages and the account management console. -Custom themes packaged in a JAR file should be deployed to the `${kc.home.dir}/providers` directory and you should run -the `build` command to install them prior to running the server. +Custom themes packaged in a JAR file should be deployed to the `${kc.home.dir}/providers` directory. After that, run +the `build` command to install them before starting the server. You are also able to create your custom themes in this directory, directly. Themes within this directory do not require -the `build` command to install them. +the `build` command to be installed. -When running the server in development mode, themes are not cached so that you can easily work on them without any need to restart +When running the server in development mode using `start-dev`, themes are not cached so that you can easily work on them without a need to restart the server when making changes. See the theme section in the [Server Developer Guide](https://www.keycloak.org/docs/latest/server_development/#_themes) for more details about how to create custom themes. @@ -17,7 +17,7 @@ See the theme section in the [Server Developer Guide](https://www.keycloak.org/d Overriding the built-in templates --------------------------------- -While creating custom themes especially when overriding templates it may be useful to use the built-in templates as +While creating custom themes, especially when overriding templates, it may be useful to use the built-in templates as a reference. These can be found within the theme directory of `../lib/lib/main/org.keycloak.keycloak-themes-${project.version}.jar`, which can be opened using any standard ZIP archive tool. diff --git a/quarkus/dist/src/main/version.txt b/quarkus/dist/src/main/version.txt index cdf94764a47c..64db51aec24b 100644 --- a/quarkus/dist/src/main/version.txt +++ b/quarkus/dist/src/main/version.txt @@ -1 +1 @@ -Keycloak.X - Version ${product.version} +Keycloak - Version ${product.version} diff --git a/quarkus/tests/integration/src/test/java/org/keycloak/it/storage/database/MariaDBStartDatabaseTest.java b/quarkus/tests/integration/src/test/java/org/keycloak/it/storage/database/MariaDBStartDatabaseTest.java index e403aaecd7c1..bfb0d5d4b0be 100644 --- a/quarkus/tests/integration/src/test/java/org/keycloak/it/storage/database/MariaDBStartDatabaseTest.java +++ b/quarkus/tests/integration/src/test/java/org/keycloak/it/storage/database/MariaDBStartDatabaseTest.java @@ -17,14 +17,10 @@ package org.keycloak.it.storage.database; -import org.junit.jupiter.api.Test; import org.keycloak.it.junit5.extension.CLIResult; import org.keycloak.it.junit5.extension.CLITest; import org.keycloak.it.junit5.extension.WithDatabase; -import io.quarkus.test.junit.main.Launch; -import io.quarkus.test.junit.main.LaunchResult; - @CLITest @WithDatabase(alias = "mariadb") public class MariaDBStartDatabaseTest extends AbstractStartDabataseTest { From 1da663854b4761ebb0237df6052995886632814c Mon Sep 17 00:00:00 2001 From: Dominik Guhr <[email protected]> Date: Wed, 9 Feb 2022 14:34:28 +0100 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: Stian Thorgersen --- quarkus/dist/src/main/README.md | 2 +- quarkus/dist/src/main/content/providers/README.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/quarkus/dist/src/main/README.md b/quarkus/dist/src/main/README.md index b8da78007524..a13d3f53d658 100644 --- a/quarkus/dist/src/main/README.md +++ b/quarkus/dist/src/main/README.md @@ -1,5 +1,5 @@ Keycloak -========== +======== To get help configuring Keycloak via the CLI, run: diff --git a/quarkus/dist/src/main/content/providers/README.md b/quarkus/dist/src/main/content/providers/README.md index a5eb4e395525..c30bf4762b19 100644 --- a/quarkus/dist/src/main/content/providers/README.md +++ b/quarkus/dist/src/main/content/providers/README.md @@ -3,7 +3,7 @@ Installing Custom Providers Add your custom provider JAR files in this directory. -Once you have your providers files in this directory, run the following command to complete the installation: +Once you have your providers in this directory, run the following command to complete the installation: ``` ${kc.home.dir}/bin/kc.sh build