In this section, we will assume that you are using Kerko through KerkoApp. Some elements may not apply if you have integrated Kerko into your own custom Flask application (see Configuration in custom applications).
When looking at Kerko configuration options, you will quickly notice two styles of parameter names, uppercase names and lowercase names.
Uppercase names, such as
BABEL_DEFAULT_LOCALE, follow the usual convention for environment variables.
Most Flask and Flask extensions parameter names follow this convention. Some
Kerko parameters have uppercase names too, but only those parameters that may
usefully be set as environment variables. Internally, those parameters are
stored into a flat Python dictionary.
Most of Kerko parameters use lowercase names. They are also organized into a
hierarchy, and are usually referenced using dot-separated paths. Examples are:
kerko.facets.item_type.enabled. Internally, those parameters are stored into
nested Python dictionaries.
In this manual, we will generally refer to a hierarchical parameter using
its full dot-separated path, for example
kerko.meta.title, except when
context makes repeating the full path redundant.
KerkoApp provides two ways to set configuration parameters:
- As parameters in one or more TOML files.
- As environment variables.
The above list is in ascending order of precedence. This means that a given parameter set in a TOML file can be overridden by an environment variable.
We do not recommend configuring the same parameter in multiple places, as that might confuse systems administrators, but a layered approach is useful in implementing the Twelve-factor App methodology.
TOML files are the preferred and most convenient way of configuring KerkoApp.
Environment variables, however, are still supported, as some parameters cannot
be set in TOML files, such as
The TOML syntax allows organizing parameters under headers to avoid
repetition and to make the file more readable. Therefore, two following two
examples are equivalent ways of setting the
kerko.meta.title = "My Awesome Bibliography"
[kerko.meta] title = "My Awesome Bibliography"
Note that if headers are used in a TOML file, any top-level parameter must be set above the first header:
ZOTERO_LIBRARY_ID = "123456" [kerko.meta] title = "My Awesome Bibliography"
[kerko.meta] title = "My Awesome Bibliography" ZOTERO_LIBRARY_ID = "123456"
By default, KerkoApp will look for a series of TOML files:
For each of those, KerkoApp first looks for the file into the current working directory. If it does not find it there, it searches by traversing directories upwards until it finds the file or reaches the root directory. At this point, if the file is still not found, the same scanning process is reapplied, but this time starting from the instance path. After that, whether the file was found or not, KerkoApp continues with the next filename in the list.
The files are loaded in the specified order. The parameters from each file get merged into the previously known configuration. If a given parameter was already set, its value is overwritten by the one from the later file.
This approach allows a layered configuration where:
config.tomlcontains general (public) parameters. It is safe (and wise) to manage this file in a code repository.
instance.tomlcontains server-specific parameters such as those that might refer to paths or systems that only exist on the server. This file is usually not put into a code repository.
.secrets.tomlcontains secrets (private parameters) that ought to be known only to the server, such as API keys. This file should never be added to a code repository.
You do not have to use all three files. One might, for example, use just
.secrets.toml, and not create
You may replace the default list of TOML file paths by setting the
KERKOAPP_CONFIG_FILES environment variable.
In the example below, the default list of TOML files is replaced by a list of two file paths, one relative and the other absolute:
KerkoApp requires environment variable names to be prefixed with
SECRET_KEY parameter, for example, becomes
specified as an environment variable.
For hierarchical parameters, each dot separator (
.) must be replaced by two
underscore characters (
kerko.meta.title parameter, for example,
KERKOAPP_kerko__meta__title when specified as an environment variable.
Such conversion is not necessary in TOML files.
Note that Windows does not allow lowercase environment variable names. Consequently, Windows users have no choice but to set lowercase parameters in TOML files.
Environment variables may be set from various locations, in the following order (refer to the Flask documentation for more details):
- As entries in a
- As entries in a
- As entries in a file specified by the
--env-filecommand line option.
- As environment variables.
The above list is in ascending order of precedence. This means that a given parameter set earlier can be overridden later as values get loaded. Files are located by scanning directories upwards from the directory you call flask from.
Configuration in custom applications¶
If you are using a custom Flask application instead of KerkoApp, some of the present documentation may not fully apply to you. For example:
- TOML files might not be supported at all.
- Environment variables might require a prefix other than
KERKOAPP_, or no prefix at all.
In a custom application, hierarchical parameters may be set in Python using the API provided by Kerko, as in the following example:
from kerko.config_helpers import config_set config_set(app.config, "kerko.meta.title", "My Awesome Bibliography")
Such assignments must be done during the initialization process. The application cannot change a setting while responding to a request.
Viewing the configuration¶
With configuration parameters potentially taking values from different sources (default values, configuration files, environment variables), you may sometimes want to verify the actual values taken by each parameter.
The following command will show the configuration parameters of the application and their values:
flask kerko config