bin/kc.[sh|bat] build --helpThis guide describes underlying core concepts of Keycloak configuration. It includes configuration guidelines for optimizing Keycloak for faster startup and low memory footprint.
You can view the server options by adding the help option for individual commands:
bin/kc.[sh|bat] build --helpbin/kc.[sh|bat] start --helpAlternatively, you can see the server options at All configuration .
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:
| Source | Format |
|---|---|
CLI |
--db-url-host=<value> |
Environment Variable |
KC_DB_URL_HOST |
|
db-url-host=<value> |
Given the db-url-host option as an example, you would set this property as follows:
bin/kc.[sh|bat] start --db-url-host=mykeycloakdbexport KC_DB_URL_HOST=mykeycloakdbconf/keycloak.confdb-url-host=mykeycloakdbThe 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.
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:
Configuration performed before starting the server in order to build an optimized server image for use at runtime
Configuration performed as part of starting the server
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 All configuration
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:
bin/kc.[sh|bat] build --helpThe 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
build command to set the database to PostgreSQL before startup:bin/kc.[sh|bat] build --db=postgresOnce you run the build command, you do not need to set the same build options when you start the server.
The second stage involves starting the server by using the start command and including configuration options with the appropriate values.
start command to start the server while setting various database optionsbin/kc.[sh|bat] start --db-url-host=keycloak-postgres --db-username=keycloak --db-password=change_me --hostname mykeycloak.acme.comNote 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.
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 or environment variables.
bin/kc.[sh|bat] build --db=postgresconf/keycloak.confdb-url-host=keycloak-postgres
db-username=keycloak
db-password=change_me
hostname=mykeycloak.acme.combin/kc.[sh|bat] startBy using the keycloak.conf file, the server can omit some steps at startup. As a result, the server starts faster.
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. Using the auto-build option, you can perform the two configuration stages by using a single command. Note that using auto-build is very likely to double the startup time for Keycloak. For most environments, this approach is not optimal.
You start the server by entering the following command:
auto-build optionbin/kc.[sh|bat] start --auto-build --db postgres --db-url-host keycloak-postgres --db-username keycloak --db-password change_me --hostname mykeycloak.acme.comBy including the auto-build option, the server calculates the build options that have changed and runs the build command, if necessary, before starting the server.
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:
build command using a custom configuration filebin/kc.[sh|bat] -cf myconfig.conf buildstart command using a custom configuration filebin/kc.[sh|bat] -cf myconfig.conf startChanges 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.
The server supports the following operating modes:
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.
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.
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.
You are able to use placeholders to resolve the configuration option value from environment variables.
db-url-host=${MY_DB_HOST}You are also able to default to a specific value if the environment variable can not be resolved:
db-url-host=${MY_DB_HOST:mydb}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.
As much as possible, avoid using properties directly from Quarkus. If your need is essential, consider opening an issue first and help us to improve the server configuration.
If that’s not possible for you, you can configure the server using Quarkus properties, perform the following steps:
Create a conf/quarkus.properties file and define any property you need.
For a complete list of Quarkus properties, see the Quarkus documentation .
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.
Note that some quarkus properties are mapped to internally 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 value in the actual Keycloak configuration.