From 22e1c4854d589834d906cfd932de2ca674322888 Mon Sep 17 00:00:00 2001 From: Dominik Guhr Date: Wed, 27 Jul 2022 09:33:54 +0200 Subject: [PATCH] changed config guide (#13137) Closes #13135 --- .../guides/src/main/server/configuration.adoc | 355 ++++++++++-------- 1 file changed, 196 insertions(+), 159 deletions(-) diff --git a/docs/guides/src/main/server/configuration.adoc b/docs/guides/src/main/server/configuration.adoc index 7f9024eb81..88dad321d0 100644 --- a/docs/guides/src/main/server/configuration.adoc +++ b/docs/guides/src/main/server/configuration.adoc @@ -4,202 +4,239 @@ <@tmpl.guide title="Configuring Keycloak" -summary="An overview of the server configuration"> +summary="Understand how to configure and start Keycloak"> -This guide describes underlying core concepts of Keycloak configuration. It includes configuration guidelines for optimizing Keycloak for faster startup and low memory footprint. +This guide explains the configuration methods for Keycloak and how to start and apply the preferred configuration. It includes configuration guidelines for optimizing Keycloak for faster startup and low memory footprint. -== Server options +== Configuration Sources for Keycloak +Keycloak loads the configuration from four different configuration sources: -You can view the server options by adding the `help` option for individual commands: +* command-line parameters +* environment variables +* user-created `.conf` file +* `keycloak.conf` file located in the `conf` directory. -.Listing build options -<@kc.build parameters="--help"/> +Configuration sources have a descending ordinal: command-line parameters take precedence over environment variables. Environment variables take precedence over options set by using a specific configuration file. Options from a specific config file take precedence over options defined in `conf/keycloak.conf`. When the same configuration key is found in multiple configuration sources, the applied value is taken from the configuration source with the highest ordinal. -.Listing configuration options -<@kc.start parameters="--help"/> - -Alternatively, you can see the server options at <@links.server id="all-config"/>. - -Server options are loaded from different sources in a specific order and they use different formats. If an option is defined in different sources, the order of resolution is the order in the following table: +=== Example: Configuring the db-url-host parameter. |=== |*Source* | *Format* |CLI -|--db-url-host= +|--db-url=cliValue |Environment Variable -|KC_DB_URL_HOST +|KC_DB_URL=envVarValue -|`conf/keycloak.conf` -|db-url-host= +|Configuration file +|db-url=confFileValue |=== -Given the `db-url-host` option as an example, you would set this property as follows: +In the example above, the `db-url` value is set in all three configuration sources. The actual value that is used at startup would be the `cliValue`. If `--db-url=cliValue` is not used, the used value would be `KC_DB_URL=envVarValue`, and last but not least the `db-url=confFileValue` would be used when no environment variable with the same Key is present. When this value is specified in a user defined configuration file and in `conf/keycloak.conf`, the value from the user defined configuration file takes precedence. -.Command-line argument +== Configuration Format +The configuration follows a "unified-per-source" format, that is easily translatable from one configuration source to another: + +.Command-line parameter format +Values for the command-line are following the `--=` format. For some values, there's also a `-=value` shorthand. + +.Environment variable format +Values for environment variables are following the uppercased `KC_=` format. + +.Configuration file format +Values that go into the configuration file are following the `=` format. + +You can easily translate a Key/Value pair from one configuration source to the other. + +You will find the relevant configuration options for a specific guide in all three formats on the table at the bottom of each guide. You can find all available options at the <@links.server id="all-config"/> guide. + +The configuration source and the corresponding format you should use is use-case specific. + +=== Example - Configure `db-url-host` on different configuration sources: +The following example shows how the configuration for the db url host looks for all three configuration sources: + +.command-line parameter <@kc.start parameters="--db-url-host=mykeycloakdb"/> -.Environment variable -``` +.environment variable +[source] +---- export KC_DB_URL_HOST=mykeycloakdb -``` +---- -.`conf/keycloak.conf` -``` +.conf/keycloak.conf +[source] +---- db-url-host=mykeycloakdb -``` +---- -The configuration source and the corresponding format you should use is use-case specific. That decision depends on the platform where the server is deployed and the runtime optimizations you are seeking. For instance, if you deploy the server into Kubernetes, you would probably rely -on environment variables to configure the server. However, you are not limited to a single configuration source or format. +=== Using environment variables for configuration values +It is possible to use placeholders to resolve an environment specific value from environment variables inside the keycloak.conf file by using the `${r"${ENV_VAR}"}` syntax: -== Starting the server - -You start the server by entering the following command: - -.Starting the server -<@kc.start parameters="--db postgres --db-url-host keycloak-postgres --db-username keycloak --db-password change_me --hostname mykeycloak.acme.com"/> - -Under certain circumstances, you might prefer to allow a longer startup time in favor of updating the values of build options when starting the server, hence performing the two configuration stages -when starting the server. - -By default, running the `start` command is going to automatically run the `build` command prior to starting the server. While this is a handy way to start the server with any available option, -including **build options** that otherwise are only available to the `build` command, it introduces an additional overhead in the server startup time. For most environments, this approach is not optimal. - -== Configuration commands and stages - -The server options are narrowed to a specific command or configuration stage. The goal is to perform a series of optimizations in a specific order to achieve optimal startup and runtime performance. This configuration occurs in two stages: - -First stage:: Configuration performed before starting the server in order to build an optimized server image for use at runtime -Second stage:: Configuration performed as part of starting the server - -=== First stage: Build an optimized Keycloak image - -The first stage involves running the `build` command and setting any **build option** available from this command to configure the server. - -The configuration options at <@links.server id="all-config"/> include options that are marked with a tool icon. This icon indicates they are build options. Build options take effect only when you apply them to the `build` command. - -You can also check which options require a build by looking at the `help` message of the `build` command: - -<@kc.build parameters="--help"/> - -The `build` command can produce an immutable and optimized server image, which is similar to building a container image. In addition to persisting build options, this command also performs optimizations for the best startup and runtime performance. The result is that much processing for starting and running the server is performed before starting Keycloak, so Keycloak is able to start up and run faster later on. - -The following are some optimizations performed by the `build` command: - -* Closed-world assumption about installed providers, which means that no need exists to re-create the registry at every startup -* Configuration files are pre-parsed to reduce I/O when starting the server -* Database specific resources are configured and prepared to run against a certain database vendor -* By persisting build options into the server image, the server does not perform any additional step to interpret configuration options and (re)configure itself - -.Run the `build` command to set the database to PostgreSQL before startup: -<@kc.build parameters="--db=postgres"/> - -Once you run the `build` command, you do not need to set the same **build options** when you start the server. - -=== Second stage: Starting an optimized server instance - -In order to achieve an optimal startup time when the server was previously built with any **build option**, you should run the `start` command together with the `--optimise` option and including any **configuration option** you want to set. - -.Run the `start` command to start the server while setting various database options -<@kc.start parameters="--optimise --db-url-host=keycloak-postgres --db-username=keycloak --db-password=change_me --hostname mykeycloak.acme.com"/> - -The `--optimise` indicates that the server was previously configured with any build option so that it no longer need to run the `build` command prior to start the server. - -Note that if you invoke commands containing special shell characters such as `;` using the CLI, you need to escape those characters. In that situation, you might choose to use the `keycloak.conf` file to set configuration options instead. - -== Optimization by using a configuration file - -Most optimizations to startup and memory footprint can be achieved by using the `build` command. Additionally, you can use the `conf/keycloak.conf` file to set configuration options. Using this file avoids some necessary parsing steps when providing configuration options using the CLI. - -.Set any build option -<@kc.build parameters="--db=postgres"/> - -.Set any configuration option to `conf/keycloak.conf` -``` -db-url-host=keycloak-postgres -db-username=keycloak -db-password=change_me -hostname=mykeycloak.acme.com -``` - -.Start the server -<@kc.start parameters="--optimise"/> - -By using the `keycloak.conf` file, the server can omit some steps at startup. As a result, the server starts faster. - -== Configuring the server by using configuration files - -By default, the server always fetches configuration options from the `conf/keycloak.conf` file. For a new installation, -this file holds only the recommended settings for running in production and those settings are commented out. - -You can also specify a different configuration file by using the `[-cf|--config-file] option by entering the following command: - -.Running the `build` command using a custom configuration file -<@kc.build rootParameters="-cf myconfig.conf"/> - -.Running the `start` command using a custom configuration file -<@kc.start rootParameters="-cf myconfig.conf"/> - -Changes to any *build option* defined in the `keycloak.conf` file that is targeted for the `build` command are ignored -if the value differs from the value for the last `build` command. In this case, make sure you run the `build` command again so that -any build option is updated accordingly. - -=== Development versus production mode - -The server supports the following operating modes: - -Development mode:: This mode is activated every time you run the `start-dev` command. In this mode, some key configuration options are set to make it possible to start the -server for development purposes without the burden of having to define additional settings that are mandatory for production. - -Production mode:: This mode is activated when you run the `build` or `start` command. Use this mode to set any configuration option that -is needed for deploying Keycloak in production. - -By default, the configuration options for the production mode are commented out in the `conf/keycloak.conf`. These examples - are meant to give you an idea about the main settings to consider when running in production. - -== Setup of the initial admin user - -The initial admin user can be added manually using the web frontend when accessed from localhost or automatically using environment variables. - -To add the initial admin user using environment variables, set `KEYCLOAK_ADMIN` for the initial admin username and `KEYCLOAK_ADMIN_PASSWORD` for the initial admin password. -Keycloak uses them at the first startup to create an initial user with administration rights. -Once the first user with administrative rights exists, you can use the UI or the command line tool `kcadm.[sh|bat]` to create additional users. - -== Using placeholders - -You are able to use placeholders to resolve the configuration option value from environment variables. - -.Using a placeholder to resolve the host from an environment variable -[source, bash] +[source] ---- db-url-host=${r"${MY_DB_HOST}"} ---- -You are also able to default to a specific value if the environment variable can not be resolved: - -.Setting a default value +To specify a fallback value in case the environment variable can not be resolved, use a `:`: [source, bash] ---- db-url-host=${r"${MY_DB_HOST:mydb}"} ---- -== Unsupported server options +=== Configuring the server using a specific configuration file -In most cases, the available options from the server configuration should suffice to configure the server. -However, you might need to use properties directly from Quarkus to enable a specific behavior or capability that is missing in the keycloak configuration. +By default, the server always fetches configuration options from the `conf/keycloak.conf` file. For a new installation, this file holds only commented settings as an idea of what you want to set when running in production. -As much as possible, avoid using properties directly from Quarkus. If your need is essential, consider opening an https://github.com/keycloak/keycloak/issues/new?assignees=&labels=kind%2Fenhancement%2Cstatus%2Ftriage&template=enhancement.yml[issue] first and help us -to improve the server configuration. +You can also specify an explicit configuration file location using the `[-cf|--config-file]` option by invoking the following command: -If that's not possible, you can configure the server using Quarkus properties. Perform the following steps: +<@kc.start rootParameters="--config-file=/path/to/myconfig.conf"/> -. Create a `conf/quarkus.properties` file and define any property you need. +=== Using the command-line help +Keycloak is packed with a CLI that helps you to configure Keycloak. To find out about the available configuration, invoke the following command: -For a complete list of Quarkus properties, see the https://quarkus.io/guides/all-config[Quarkus documentation] . +<@kc.start parameters="--help"/> -When a raw quarkus property is a runtime property, it is also handled as runtime property for keycloak. When a quarkus property is a build time property, you have to invoke a new keycloak build first for the property to apply. +Alternatively, you can find all server options at the <@links.server id="all-config"/> guide. -Note that some quarkus properties are mapped by the Keycloak configuration, for example `quarkus.http.port` and similar properties that are needed to configure Keycloak. If the property is used by Keycloak, and you define the same property key in the quarkus.properties file, the keycloak configuration value takes precedence over the raw quarkus configuration value, so the value you set in `quarkus.properties` will be ignored when there is a matching value in the actual Keycloak configuration. +=== Using raw Quarkus properties +In most cases, the available configuration options should suffice to configure the server. +However, you might need to use properties directly from the underlying Quarkus framework to enable a specific behavior or capability that is missing in the keycloak configuration. - +If possible, avoid using properties directly from Quarkus. These are considered unsupported by Keycloak. If your need is essential, consider opening an https://github.com/keycloak/keycloak/issues/new?assignees=&labels=kind%2Fenhancement%2Cstatus%2Ftriage&template=enhancement.yml[enhancement request] first and help us +to improve Keycloak's configuration to fit your needs. + +If that's not possible, you can configure the server using raw Quarkus properties: + +* Create a `quarkus.properties` file in the `conf` directory and define any property you need. + +For a complete list of Quarkus properties, see the https://quarkus.io/guides/all-config[Quarkus documentation]. Be aware that Keycloak uses a https://github.com/keycloak/keycloak/blob/main/quarkus/runtime/pom.xml#L17[subset] of quarkus extensions, so not all properties will be available. + +When a quarkus property is a runtime property (no lock icon shown in the quarkus guide), it is also handled as runtime property for Keycloak. When a quarkus property is a build time property, you have to invoke a `build` for the property to be applied. See the sections below for further information around the build command. + +Note that some quarkus properties are mapped by the Keycloak configuration, for example `quarkus.http.port` and similar properties that are needed to configure Keycloak. If the property is used by Keycloak, defining the same underlying property key in `quarkus.properties` will have no effect, as the keycloak configuration value takes precedence over the quarkus property value. + +== Starting Keycloak +Keycloak can be started in two operating modes, `development mode` and `production mode`. Both modes offer a different set of defaults for the environment they are intended to be used. + +=== Starting Keycloak in development mode +The development mode is targeted for people trying out Keycloak the first time and get it up and running quickly. It also offers convenient defaults for developers, for example to develop a new Keycloak theme. + +The development mode is started by invoking the following command: + +<@kc.startdev parameters=""/> + +.Defaults +The development mode sets the following default configuration: + +* HTTP is enabled +* Strict hostname resolution is disabled +* Cache is set to local (No distributed cache mechanism used for high availability) +* Theme- and Template-caching is disabled + +=== Starting Keycloak in production mode +The production mode is targeted for deployments of Keycloak into production environments and follows a "secure by default" principle. + +The production mode is started by invoking the following command: + +<@kc.start parameters=""/> + +Without further configuration, this command will not start Keycloak and show you an error instead. This is done on purpose, because Keycloak follows a "secure by default" principle in this mode and expects to have a hostname setup and a HTTPS/TLS setup available when started in production mode. + +.Defaults +The production mode sets the following defaults: + +* HTTP is disabled as transport layer security (HTTPS) is essential +* Hostname configuration is expected +* HTTPS/TLS configuration is expected + +Make sure to follow the steps outlined in the <@links.server id="configuration-production"/> guide before deploying Keycloak to production environments. + +By default, example configuration options for the production mode are commented out in the default `conf/keycloak.conf` file. These give you an idea about the main configuration to consider when running Keycloak in production. + +== Setup of the initial admin user +The initial admin user can be added manually using the web frontend. It needs to be accessed using a local connection (localhost) or using environment variables: + +To add the initial admin user using environment variables, set `KEYCLOAK_ADMIN=` for the initial admin username and `KEYCLOAK_ADMIN_PASSWORD=` for the initial admin password. +Keycloak parses these values at first startup to create an initial user with administrative rights. +Once the first user with administrative rights exists, you can use the admin UI or the command line tool `kcadm.[sh|bat]` to create additional users. + +If the initial administrator already exists and the environment variables are still present at startup, an error message stating the failed creation of the initial administrator is shown in the logs. Keycloak ignores the values and starts up correctly. + +== Optimize the Keycloak startup +It is highly recommended to optimize Keycloak for better startup times and memory consumption before deploying into production environments. This section shows you how to apply a set of optimizations for Keycloak to get the best performance and runtime behavior possible. + +=== Create an optimized Keycloak build +By default, when the `start` or `start-dev` commands are used, Keycloak runs a `build` command under the covers for convenience reasons. +This `build` command performs a set of optimizations to achieve an optimized startup- and runtime-behavior. The build process can take some time, usually a few seconds. Especially when running Keycloak in containerized environments like Kubernetes or OpenShift, startup time is important. +So in order to avoid the time that gets lost when running a `build` as part of Keycloaks first startup, it is possible and recommended to invoke a `build` explicitly before starting up, for example as a separate step in a CI/CD pipeline. + +==== First step: Run a build explicitly +To run a `build`, invoke the following command: + +<@kc.build parameters=""/> + +As you may notice, the command above shows `build options` that should be invoked. Keycloak distinguishes between **build options**, that are usable when invoking the `build` command, and **configuration options**, that are usable when starting up the server. + +For a non-optimized startup of Keycloak, this distinction has no effect, but when a build is invoked beforehand, there's only a subset of Options available to the build command. The reason is, that build options get persisted into Keycloaks classpath, so configuration for e.g. credentials like `db-password` must not get persisted for security reasons. + +Build options are marked in the <@links.server id="all-config"/> guide with a tool icon. +Find available build options either by looking at the https://www.keycloak.org/server/all-config?f=build[All configuration page with build options selected] or by invoking the following command: + +<@kc.build parameters="--help"/> + +.Example: Run the `build` command to set the database to PostgreSQL before startup: +<@kc.build parameters="--db=postgres"/> + +==== Second step: Start Keycloak using `--optimized` +After a successful build, you can start Keycloak and turn off the default startup behavior by invoking the following command: + +<@kc.build parameters="--optimized "/> + +The `--optimized` parameter tells Keycloak to assume a pre-built, already optimized Keycloak image is used. As a result, Keycloak avoids checking for and running a build directly at startup to save the time to walk through this process. + +You can invoke all configuration options at startup - these are all options in the <@links.server id="all-config"/> guide that are **not** marked with a tool icon. + +If a build option is found at startup with an equal value to the value used when invoking the `build`, it gets silently ignored when using the `--optimized` flag. If it has a different value than the value used when a build was invoked, a warning is shown in the logs and the previously built value is used. In order for this value to take effect, you have to run a new `build` before starting. + +The following example shows how to create an optimized build, then start Keycloak using the --optimized parameter: + +.Create an optimized build +Set build option for the postgresql database vendor using the build command + + <@kc.build parameters="--db=postgres"/> + +.Set the runtime configuration options to keycloak.conf +Set configuration options for postgres inside `conf/keycloak.conf` + +[source] +---- +db-url-host=keycloak-postgres +db-username=keycloak +db-password=change_me +hostname=mykeycloak.acme.com +https-certificate-file +---- + +.Start the server with the optimized parameter + + <@kc.start parameters="--optimized"/> + +Most optimizations to startup and runtime behavior can be achieved by using the `build` command. By using the `keycloak.conf` file as a source for configuration options, Keycloak avoids some steps at startup that are needed when invoking the configuration using the command line, for example initialising the CLI itself. As a result, the server starts up even faster. + +== Underlying concepts +This section gives an overview around the underlying concepts Keycloak uses, especially when it comes to optimizing the startup. + +Keycloak uses the Quarkus framework and it's re-augmentation/mutable-jar approach under the covers. This process is started when a `build` is invoked. + +The following are some optimizations performed by the `build` command: + +* A new closed-world assumption about installed providers is created, meaning that no need exists to re-create the registry and initialize the factories at every Keycloak startup +* Configuration files are pre-parsed to reduce I/O when starting the server +* Database specific resources are configured and prepared to run against a certain database vendor +* By persisting build options into the server image, the server does not perform any additional step to interpret configuration options and (re)configure itself + +You can read more at the specific https://quarkus.io/guides/reaugmentation[Quarkus guide] + + \ No newline at end of file