Readme review v1 (#10082)

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
+├── server
-    ├── The server itself, only responsible for generating the server artifacts
+│   ├── 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 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`:
-
-To build the module and produce the artifacts to run a server:
 
     mvn -f ../pom.xml clean install -DskipTestsuite -DskipExamples -DskipTests
 
-### Building the Distribution
+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.
+
+## Building the Keycloak Quarkus distribution
+
+After the main codebase is built, you can build the quarkus distribution, including the zip and tar.gz files, by invoking the following command:
     
-To build the module as well as the distribution packages:
+    mvn clean install -DskipTests
 
-    mvn -f ../pom.xml clean install -DskipTestsuite -DskipExamples -DskipTests -Pdistribution
+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.
 
-The distribution packages (ZIP and TAR) should be available at [../distribution/server-x-dist](../distribution/server-x-dist/target).
+As an alternative, you can build the distribution artifacts directly without a rebuild of the code by running the following command:
 
-Alternatively, you can also build the distribution directly by running the following command:
+    mvn -f dist/pom.xml clean install
 
-    mvn -f ../distribution/server-x-dist/pom.xml clean install
+## 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. 
 
-## Running
+For development purposes, you can run the server in development mode instead using `start-dev`:
-
-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:
 
     java -jar server/target/lib/quarkus-run.jar start-dev
 
+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.
+
 ## Contributing
+Please make sure to read our [Contribution Guidelines](../CONTRIBUTING.md) before contributing.
 
-### Development Mode
+To run the server in Quarkus' development mode, invoke the following command:
-
-To run the server in development mode:
 
     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.
 
-NOTE: Although still very handy during development, there are some limitations when running in dev mode that
+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.
-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.
 
-NOTE: When developing custom providers, you should be able to benefit from live coding as long as you keep changes within the `server` module. 
+## Running tests
+Keycloaks Quarkus distribution module uses a new testsuite more integrated into the quarkus platform.
 
-Alternatively, you can run the server in development mode from your IDE. For that, run the `org.keycloak.quarkus._private.IDELauncher` main class.
+### 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`. 
+
+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. 
+
+    mvn clean install -Dkc.test.storage.database=true -Dtest=MariaDBStartDatabaseTest
+
+to spin up a MariaDB container and start Keycloak with it.

quarkus/dist/src/main/README.md

@@ -1,5 +1,5 @@
-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).
+To get started, check out the [configuration guides](https://www.keycloak.org/guides#server).

quarkus/dist/src/main/content/conf/README.md

@@ -1,4 +1,4 @@
 Configure the server
 ====================
 
-Use files in this directory to configure the server.
+Files in this directory are used to configure the server. Please consult the [configuration guides](https://www.keycloak.org/guides#server) for more information.

quarkus/dist/src/main/content/providers/README.md

@@ -7,4 +7,4 @@ Once you have your providers in this directory, run the following command to com
 
 ```
 ${kc.home.dir}/bin/kc.sh build
-```
+```

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
+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 prior to running the server.
+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.
 

quarkus/dist/src/main/version.txt

@@ -1 +1 @@
-Keycloak.X - Version ${product.version}
+Keycloak - Version ${product.version}

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 {