Configuration Reference¶

imbi.common.settings holds the settings classes that every Imbi service shares. Each class is a pydantic-settings BaseSettings class with an environment prefix. For each variable, its type, and its default, see the configuration reference. The field name is the variable name without the prefix, in lower case. For example, POSTGRES_MAX_POOL_SIZE is Postgres.max_pool_size.

Settings classes¶

Two more classes are outside imbi.common.settings:

Reading settings¶

Make an instance of a class. It reads the environment, then the .env file in the working directory, then its config.toml section (when the class has a Configuration field), then the defaults:

from imbi.common import settings

postgres = settings.Postgres()
print(postgres.url, postgres.max_pool_size)

For Auth and ConfigSecrets, use the getters. They keep one instance per process, so a generated development key stays the same in that process:

auth = settings.get_auth_settings()
config_secrets = settings.get_config_settings()

The library code (the graph client, the ClickHouse client, the Iggy client, the Valkey client, the plugin registry) makes its own instances in this way. So those clients also read config.toml, except the Iggy client, because Iggy has no Configuration field.

load_config() and config.toml¶

settings.load_config() returns a Configuration object. It reads config.toml from these places, in this order:

1. ./config.toml
2. ~/.config/imbi/config.toml
3. /etc/imbi/config.toml

A key in an earlier file wins over the same key in a later file. Each settings class with a Configuration field reads its own section through the ConfigFileSettings base class, so a direct settings.Postgres() and load_config().postgres give the same values. An environment variable wins over the same key in the file. The file supplies only the keys that the environment does not set.

The next example changes the graph client and the ClickHouse client, unless POSTGRES_URL, POSTGRES_MAX_POOL_SIZE, or CLICKHOUSE_URL is set:

[postgres]
url = "postgresql://imbi_app:secret@db-prod:5432/imbi"
max_pool_size = 20

[clickhouse]
url = "clickhouse+http://default:secret@clickhouse-prod:8123/imbi"

Configuration has no iggy field, so an [iggy] section has no effect. Use IGGY_URL.

Production keys¶

Auth and ConfigSecrets read the unprefixed ENVIRONMENT variable. When it is not development (the default), they raise a validation error unless these are set:

• IMBI_AUTH_JWT_SECRET
• IMBI_AUTH_ENCRYPTION_KEY
• IMBI_CONFIG_ENCRYPTION_KEY

In development, they generate a missing key and log a warning. A generated key is different in each process. Generate a Fernet key with:

python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

Values with a special format¶

Validation¶

A class raises pydantic.ValidationError when a value is not valid:

import pydantic

from imbi.common import settings

try:
    settings.Postgres(url='invalid-url')
except pydantic.ValidationError as err:
    print(f'Invalid configuration: {err}')