The Quarkus distribution can be configured through:

• Configuration files (Java properties file, keycloak.properties)
• CLI arguments
• Environment variables

There is two issues with this that could be improved:

• 3 different configuration key formats
• Java-based configuration file format

3 different configuration key formats

There are 3 different formats for the configuration key, for example:

• File: db.pool.initial-size
• CLI: db-pool-initial-size
• Env: KC_DB_POOL_INITIAL_SIZE

This results in having to understand 3 different formats, and translate between them when needed. However, there is a issue with the file format as it can only be translated from, not to.

As an example File format can be translated to CLI format by replacing . with -. However, it is not possible to translate from CLI format to File, as replacing - with . would result in db.pool.initial.size, which doesn't match db.pool.initial-size.

In the CLI help and the documentation the CLI option is extensively used, as that is the most convenient way to document, as well as the easiest approach to try out new configuration, and as the CLI format can't be translated to the File format, the only way to find the key required in the configuration files would be to look it up in a table in the documentation, or perhaps with a tool in the CLI.

An example from the work in progress documentation for configuring a database in the Quarkus distribution:

It would be much more convenient if one format was removed, and the configuration key was the same in the CLI argument as in the configuration file, so the above example would be:

• File: db-pool-initial-size
• CLI: db-pool-initial-size
• Env: KC_DB_POOL_INITIAL_SIZE

Java-based configuration file format

Most Java developers are familiar with standard Java property files. Although, even for Java developers that can be confusing as the traditionally used ISO-8859-1 encoding rather than the much more internationalization friendly utf-8 encoding.

However, non-Java developers are not familiar with the Java properties format, which is an issue as Keycloak should be friendly and easy to use regardless of what programming language you are familiar with.

There's a few options to choose from here:

• YAML
• TOML
• Basic config file

YAML and TOML adds some structure to the configuration file, but at the cost that they are harder to create initially and are not translatable easily to/from CLI arguments and Environment variables. As Keycloak supports configuration through both CLI and Env it is important that configuration is kept simple, and does not require a complex structure. This means the additional overhead of YAML or TOML is really not needed, and we should stick with a basic config file.

The proposal here is to have a basic configuration file (keycloak.conf) that is utf-8 encoded, and is simply a list of configuration options following the style from the CLI:

# db config
db-pool-initial-size 10
db-url-host mydatabase
db-username myuser

Configuration files like these are common-place in Unix systems, and should be easy to understand by anyone new to Keycloak.

Configuration profiles

One side-effect of this is that we would loose the support for profiles. Profiles can be convenient, but comes at the cost of more complex configuration file formats, which are hard to write, as well as understand. Profiles also overlap with the ability to specify the configuration file.

Profiles are also not supported when using CLI or Env to configure Keycloak, which can be confusing as only 1 out of 3 configuration sources support profiles.

Profiles as a feature directly doesn't make all that much sense, as it will be very uncommon that the same Keycloak installation has different sets of configuration, and if this is required it can more easily be achieved by having two separate configuration files.

However, profiles are also used by Keycloak to select between developer and production modes. It may not be needed to support configuration files at all in developer mode, and simply ignore the configuration files when start-dev is used. Alternatively, a separate config file can be used for this purpose keycloak-dev.conf.