1
<#import "/templates/guide.adoc" as tmpl>
2
<#import "/templates/kc.adoc" as kc>
3
<#import "/templates/links.adoc" as links>
6
title="Configuring {project_name}"7
summary="Understand how to configure and start {project_name}">9
This {section} explains the configuration methods for {project_name} and how to start and apply the preferred configuration. It includes configuration guidelines for optimizing {project_name} for faster startup and low memory footprint.11
== Configuring sources for {project_name}12
{project_name} loads the configuration from four sources, which are listed here in order of application.14
. Command-line parameters
15
. Environment variables
16
. Options defined in the `conf/keycloak.conf` file, or in a user-created configuration file.
17
. Sensitive options defined in a user-created Java KeyStore file.
19
When an option is set in more than one source, the one that comes first in the list determines the value for that option. For example, the value for an option set by a command-line parameter has a higher priority than an environment variable for the same option.
21
=== Example: Configuring the db-url-host parameter
23
The following example shows how the `db-url` value is set in four configuration sources:
29
|Command line parameters
33
|`KC_DB_URL=envVarValue`
36
|`db-url=confFileValue`
39
|`kc.db-url=keystoreValue`
42
Based on the priority of application, the value that is used at startup is `cliValue`, because the command line is the highest priority.
44
If `--db-url=cliValue` had not been used, the applied value would be `KC_DB_URL=envVarValue`. If the value were not applied by either the command line or an environment variable, `db-url=confFileValue` would be used. If none of the previous values were applied, the value `kc.db-url=confFileValue` would be used due to the lowest priority among the available configuration sources.
46
== Formats for configuration
47
The configuration uses a _unified-per-source_ format, which simplifies translation of a key/value pair from one configuration source to another. Note that these formats apply to spi options as well.
49
Command-line parameter format:: Values for the command-line use the `--_<key-with-dashes>_=_<value>_` format. For some values, an `-_<abbreviation>_=_<value>_` shorthand also exists.
51
Environment variable format:: Values for environment variables use the uppercased `KC++_++__<key_with_underscores>__=_<value>_` format.
53
Configuration file format:: Values that go into the configuration file use the `_<key-with-dashes>_=_<value>_` format.
55
KeyStore configuration file format:: Values that go into the KeyStore configuration file use the `kc._<key-with-dashes>_` format. `_<value>_` is then a password stored in the KeyStore.
57
At the end of each configuration {section}, look for the _Relevant58
options_ heading, which defines the applicable configuration
59
formats. For all configuration options, see <@links.server
60
id="all-config"/>. Choose the configuration source and format that applies to your use case.
62
=== Example - Alternative formats based on configuration source
63
The following example shows the configuration format for `db-url-host` for three configuration sources:
65
.command-line parameter
66
<@kc.start parameters="--db-url-host=mykeycloakdb"/>
71
export KC_DB_URL_HOST=mykeycloakdb
77
db-url-host=mykeycloakdb
80
=== Formats for command-line parameters
82
{project_name} is packed with many command line parameters for configuration. To see the available configuration formats, enter the following command:84
<@kc.start parameters="--help"/>
86
Alternatively, see <@links.server id="all-config"/> for all server options.
88
=== Formats for environment variables
89
You can use placeholders to resolve an environment specific value from environment variables inside the `keycloak.conf` file by using the `${r"++${ENV_VAR}++"}` syntax:93
db-url-host=${r"${MY_DB_HOST}"}96
In case the environment variable cannot be resolved, you can specify a fallback value. Use a `:` (colon) as shown here before `mydb`:
99
db-url-host=${r"${MY_DB_HOST:mydb}"}102
=== Format to include a specific configuration file
104
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.
106
You can also specify an explicit configuration file location using the `[-cf|--config-file]` option by entering the following command:
108
<@kc.start rootParameters="--config-file=/path/to/myconfig.conf"/>
110
Setting that option makes {project_name} read configuration from the specified file instead of `conf/keycloak.conf`.112
=== Setting sensitive options using a Java KeyStore file
114
Thanks to Keystore Configuration Source you can directly load properties from a Java KeyStore using the `[--config-keystore]` and `[--config-keystore-password]` options.
115
Optionally, you can specify the KeyStore type using the `[--config-keystore-type]` option. By default, the KeyStore type is `PKCS12`.
117
The secrets in a KeyStore need to be stored using the `PBE` (password-based encryption) key algorithm, where a key is derived from a KeyStore password.
118
You can generate such a KeyStore using the following `keytool` command:
121
keytool -importpass -alias kc.db-password -keystore keystore.p12 -storepass keystorepass -storetype PKCS12 -v
123
After executing the command, you will be prompted to *Enter the password to be stored*, which represents a value of the `kc.db-password` property above.
125
When the KeyStore is created, you can start the server using the following parameters:
127
<@kc.start parameters="--config-keystore=/path/to/keystore.p12 --config-keystore-password=storepass --config-keystore-type=PKCS12"/>
129
=== Format for raw Quarkus properties
130
In most cases, the available configuration options should suffice to configure the server.
131
However, for a specific behavior or capability that is missing in the {project_name} configuration, you can use properties from the underlying Quarkus framework.133
If possible, avoid using properties directly from Quarkus, because they are unsupported by {project_name}. 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. This approach helps us improve the configuration of {project_name} to fit your needs.135
If an enhancement request is not possible, you can configure the server using raw Quarkus properties:
137
. Create a `quarkus.properties` file in the `conf` directory.
138
. Define the required properties in that file.
140
You can use only a https://github.com/keycloak/keycloak/blob/main/quarkus/runtime/pom.xml#L17[subset] of the Quarkus extensions that are defined in the https://quarkus.io/guides/all-config[Quarkus documentation]. Also, note these differences for Quarkus properties:
142
* A lock icon for a Quarkus property in the https://quarkus.io/guides/all-config[Quarkus documentation] indicates a build time property. You run the `build` command to apply this property. For details about the build command, see the subsequent sections on optimizing {project_name}.143
* No lock icon for a property in the Quarkus guide indicates a runtime property for Quarkus and {project_name}.145
. Use the `[-cf|--config-file]` command line parameter to include that file.
147
Similarly, you can also store Quarkus properties in a Java KeyStore.
149
Note that some Quarkus properties are already mapped in the {project_name} configuration, such as `quarkus.http.port` and similar essential properties. If the property is used by Keycloak, defining that property key in `quarkus.properties` has no effect. The Keycloak configuration value takes precedence over the Quarkus property value.151
=== Using special characters in values
153
{project_name} depends upon Quarkus and MicroProfile for processing configuration values. Be aware that value expressions are supported. For example, `$\{some_key}` evaluates to the value of `some_key`.155
To disable expression evaluation, the `\` character functions as an escape character. In particular, it must be used to escape the usage of `$` characters when they appear to define an expression or are repeated. For example, if you want the configuration value `my$$password`, use `my\$\$password` instead. Note that the `\` character requires additional escaping or quoting when using most unix shells, or when it appears in properties files.
156
For example, bash single quotes preserve the single backslash `--db-password='my\$\$password'`. Also, with bash double quotes, you need an additional backslash `--db-password="my\\$\\$password"`. Similarly in a properties file, backslash characters must also be escaped: `kc.db-password=my\\$\\$password`
158
== Starting {project_name}159
You can start {project_name} in `development mode` or `production mode`. Each mode offers different defaults for the intended environment.161
=== Starting {project_name} in development mode162
Use development mode to try out {project_name} for the first time to get it up and running quickly. This mode offers convenient defaults for developers, such as for developing a new {project_name} theme.164
To start in development mode, enter the following command:
166
<@kc.startdev parameters=""/>
169
Development mode sets the following default configuration:
172
* Strict hostname resolution is disabled
173
* Cache is set to local (No distributed cache mechanism used for high availability)
174
* Theme-caching and template-caching is disabled
176
=== Starting {project_name} in production mode177
Use production mode for deployments of {project_name} in production environments. This mode follows a _secure by default_ principle.179
To start in production mode, enter the following command:
181
<@kc.start parameters=""/>
183
Without further configuration, this command will not start {project_name} and show you an error instead. This response is done on purpose, because {project_name} follows a _secure by default_ principle. Production mode expects a hostname to be set up and an HTTPS/TLS setup to be available when started.186
Production mode sets the following defaults:
188
* HTTP is disabled as transport layer security (HTTPS) is essential
189
* Hostname configuration is expected
190
* HTTPS/TLS configuration is expected
192
Before deploying {project_name} in a production environment, make sure to follow the steps outlined in <@links.server id="configuration-production"/>.194
By default, example configuration options for the production mode are commented out in the default `conf/keycloak.conf` file. These options give you an idea about the main configuration to consider when running {project_name} in production.196
== Creating the initial admin user
197
You can create the initial admin user by using the web frontend, which you access using a local connection (localhost). You can instead create this user by using environment variables. Set `KEYCLOAK_ADMIN=_<username>_` for the initial admin username and `KEYCLOAK_ADMIN_PASSWORD=_<password>_` for the initial admin password.
199
{project_name} parses these values at first startup to create an initial user with administrative rights.200
Once the first user with administrative rights exists, you can use the Admin Console or the command line tool `kcadm.[sh|bat]` to create additional users.
202
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. {project_name} ignores the values and starts up correctly.204
== Optimize the {project_name} startup205
We recommend optimizing {project_name} to provide faster startup and better memory consumption before deploying {project_name} in a production environment. This section describes how to apply {project_name} optimizations for the best performance and runtime behavior.207
=== Creating an optimized {project_name} build208
By default, when you use the `start` or `start-dev` command, {project_name} runs a `build` command under the covers for convenience reasons.210
This `build` command performs a set of optimizations for the startup and runtime behavior. The build process can take a few seconds. Especially when running {project_name} in containerized environments such as Kubernetes or OpenShift, startup time is important. To avoid losing that time, run a `build` explicity before starting up, such as a separate step in a CI/CD pipeline.212
==== First step: Run a build explicitly
213
To run a `build`, enter the following command:
215
<@kc.build parameters="<build-options>"/>
217
This command shows `build options` that you enter. {project_name} distinguishes between **build options**, that are usable when running the `build` command, and **configuration options**, that are usable when starting up the server.219
For a non-optimized startup of {project_name}, this distinction has no effect. However, if you run a build before the startup, only a subset of options is available to the build command. The restriction is due to the build options getting persisted into an optimized {project_name} image. For example, configuration for credentials such as `db-password` (which is a configuration option) must not get persisted for security reasons.222
All build options are persisted in a plain text. Do not store any sensitive data as the build options. This applies across all the available configuration sources, including the KeyStore Config Source. Hence, we also do not recommend to store any build options in a Java keystore. Also, when it comes to the configuration options, we recommend to use the KeyStore Config Source primarily for storing sensitive data. For non-sensitive data you can use the remaining configuration sources.
224
Build options are marked in <@links.server id="all-config"/> with a tool icon.
225
To find available build options, see https://www.keycloak.org/server/all-config?f=build[All configuration page with build options selected] or enter the following command:
227
<@kc.build parameters="--help"/>
229
.Example: Run a `build` to set the database to PostgreSQL before startup
230
<@kc.build parameters="--db=postgres"/>
232
==== Second step: Start {project_name} using `--optimized`233
After a successful build, you can start {project_name} and turn off the default startup behavior by entering the following command:235
<@kc.start parameters="--optimized <configuration-options>"/>
237
The `--optimized` parameter tells {project_name} to assume a pre-built, already optimized {project_name} image is used. As a result, {project_name} avoids checking for and running a build directly at startup, which saves time.239
You can enter all configuration options at startup; these options are the ones in <@links.server id="all-config"/> that are **not** marked with a tool icon.
241
* If a build option is found at startup with a value that is equal to the value used when entering the `build`, that option gets silently ignored when you use the `--optimized` parameter.
242
* If that option has a different value than the value used when a build was entered, a warning appears in the logs and the previously built value is used. For this value to take effect, run a new `build` before starting.
244
.Create an optimized build
246
The following example shows the creation of an optimized build followed by the use of the `--optimized` parameter when starting {project_name}.248
. Set the build option for the PostgreSQL database vendor using the build command
250
<@kc.build parameters="--db=postgres"/>
252
. Set the runtime configuration options for postgres in the `conf/keycloak.conf` file.
256
db-url-host=keycloak-postgres
259
hostname=mykeycloak.acme.com
260
https-certificate-file
263
. Start the server with the optimized parameter
265
<@kc.start parameters="--optimized"/>
267
You can achieve most optimizations to startup and runtime behavior by using the `build` command. Also, by using the `keycloak.conf` file as a configuration source, you avoid some steps at startup that would otherwise require command line parameters, such as initializing the CLI itself. As a result, the server starts up even faster.
269
== Underlying concepts
270
This section gives an overview of the underlying concepts {project_name} uses, especially when it comes to optimizing the startup.272
{project_name} uses the Quarkus framework and a re-augmentation/mutable-jar approach under the covers. This process is started when a `build` command is run.274
The following are some optimizations performed by the `build` command:
276
* 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 {project_name} startup.277
* Configuration files are pre-parsed to reduce I/O when starting the server.
278
* Database specific resources are configured and prepared to run against a certain database vendor.
279
* By persisting build options into the server image, the server does not perform any additional step to interpret configuration options and (re)configure itself.
281
You can read more at the specific https://quarkus.io/guides/reaugmentation[Quarkus guide]