From ed9d6cc40a9f06323ff5dff3bfb221712a853bc2 Mon Sep 17 00:00:00 2001 From: Steven Hawkins Date: Tue, 11 Nov 2025 09:06:48 -0500 Subject: [PATCH] fix: adding the built system property to the README (#43850) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * fix: adding the built system property to the README closes: #43606 Signed-off-by: Steve Hawkins * removing the doc / note about directly launching from the jar Signed-off-by: Steve Hawkins * Update docs/building.md Co-authored-by: Václav Muzikář Signed-off-by: Steven Hawkins * removing one more reference to running the jar directly Signed-off-by: Steve Hawkins * Move a chapter in README Signed-off-by: Václav Muzikář --------- Signed-off-by: Steve Hawkins Signed-off-by: Steven Hawkins Signed-off-by: Václav Muzikář Co-authored-by: Václav Muzikář Co-authored-by: Václav Muzikář --- docs/building.md | 16 +--------------- quarkus/README.md | 16 +++++++--------- 2 files changed, 8 insertions(+), 24 deletions(-) diff --git a/docs/building.md b/docs/building.md index 42024c78798..08e23b2d816 100644 --- a/docs/building.md +++ b/docs/building.md @@ -65,21 +65,7 @@ To avoid this, you can skip this check by adding the following property: ### Starting Keycloak -To start Keycloak during development first build as specified above, then run: - - java -Dkc.config.built=true -jar quarkus/server/target/lib/quarkus-run.jar start-dev - -To stop the server press `Ctrl + C`. - -For more details, follow the [`quarkus` module documentation](../quarkus/README.md). - ---- -**NOTE** - -Direct use of the `quarkus-run.jar` assumes manual control over the augmentation process. -If you want to run Keycloak with changes to build time options it is easier to either use the full distribution and the relevant `bin/kc.[sh|bat]` script or run an embedded server via the `org.keycloak.Keycloak` class in the `quarkus/tests/junit5` module. - ---- +Follow the [`quarkus` module documentation](../quarkus/README.md#running-in-keycloak-development-mode) for instructions how to run Keycloak in dev environment. ## Working with the codebase diff --git a/quarkus/README.md b/quarkus/README.md index 9c6da944bd9..32b19026bb8 100644 --- a/quarkus/README.md +++ b/quarkus/README.md @@ -52,11 +52,7 @@ As an alternative, you can build the distribution artifacts directly without a r ## 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. -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 - -This spins up Keycloak using a development database (h2-file) and with insecure HTTP enabled. +For development purposes, you can run the server in development mode instead using `start-dev`. ### Running from your IDE 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. @@ -70,23 +66,25 @@ Set the `kc.home.dir` environment variable for keeping state between startups: -Dkc.home.dir=.kc -## Contributing -Please make sure to read our [Contribution Guidelines](../CONTRIBUTING.md) before contributing. +### Running from the command line To run the server in Quarkus' development mode, invoke the following command: - ../mvnw -f server/pom.xml compile quarkus:dev -Dquarkus.args="start-dev" + ../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`. For debugging the build steps right after start, you can suspend the JVM by running: - ../mvnw -f server/pom.xml -Dsuspend=true compile quarkus:dev -Dquarkus.args="start-dev" + ../mvnw -f server/pom.xml -Dsuspend=true compile quarkus:dev -Dkc.config.built=true -Dquarkus.args="start-dev" 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. +## Contributing +Please make sure to read our [Contribution Guidelines](../CONTRIBUTING.md) before contributing. + ## Running tests Keycloaks Quarkus distribution module uses a new testsuite more integrated into the quarkus platform.