Configuration

Andromeda reads one TOML file, then the ANDROMEDA__ environment variables, then two command-line flags. Every setting but database.connection has a built-in default, so the broker needs no file, only the database connection, which the environment can give.

Each section page starts with its keys and their defaults as TOML you can copy. Each setting then has its own card, with its default, its allowed values, its environment variable and what it changes.

Rather answer questions than read settings?

The planner writes a whole configuration from questions about your deployment, with the docs' recommendation for everything you leave out. It also checks an andromeda.toml or environment file you already have.

Open the deployment planner→

Where settings come from

Andromeda builds its configuration in four layers. Each layer overrides the one before it:

1. The built-in defaults.
2. The configuration file.
3. Environment variables starting with ANDROMEDA__.
4. The --host and --port flags, which set server.host and server.port.

Pass the file with -c or --configuration; --config also works. A file you name must exist, or the broker stops with configuration file not found. Without the flag, Andromeda looks for andromeda/andromeda.toml in $XDG_CONFIG_HOME, or in ~/.config when that isn't set, and uses it only if it's there. On Windows it looks under %APPDATA%.

andromeda --configuration /etc/andromeda/andromeda.toml

To get a starting file with every key, its default and a comment, run andromeda configuration generate -o andromeda.toml.

Environment variables

The variable name is ANDROMEDA__ followed by the key's path, with a double underscore between levels and a single underscore inside a key name:

ANDROMEDA__SERVER__PORT=8080
ANDROMEDA__DATABASE__MAINTENANCE__MODE=observe
ANDROMEDA__NOTIFICATIONS__PERIODIC__MAX_POLL_INTERVAL=45s

A variable sets one value. true and false are read as booleans, numbers as numbers, and anything else as text. A list takes its members separated by commas, each trimmed, and an empty value is the empty list:

ANDROMEDA__HTTP__COMPRESSION__ALGORITHMS=gzip,zstd
ANDROMEDA__HTTP__CSRF__TRUSTED_ORIGINS=https://dashboard.example.org

Only a key whose value is a list is split, so a comma inside a database URL stays as it is. A table, such as each [[jsonld.preloaded_contexts]] entry, can only be set in the file, with one exception. A database connection is a URL or a table of its parts, and each part can be its own variable, such as ANDROMEDA__DATABASE__CONNECTION__PASSWORD. A part other than port is read as text, so a password made of digits keeps its leading zeros.

Checking a configuration

andromeda configuration, or andromeda config for short, inspects a configuration without starting the broker. It reads the same file, environment and flags the broker would.

andromeda configuration validate loads and checks everything. It prints Configuration valid: with the file it read, or every rule the configuration breaks, one to a line, and exits with a non-zero status on failure. Run it before you deploy a change: a broker refuses to start on a configuration that validate refuses.

andromeda configuration show prints the configuration in effect after all four layers, as TOML or, with -f json, as JSON. Both database connections are replaced with postgres://redacted.invalid/redacted. Use it to confirm that a value you set is the one the broker will use.

andromeda configuration generate writes every key with its default and a comment, to standard output or to the file named by -o.

Check a configuration in your browser

Paste or drop an andromeda.toml or an environment file into the planner. It lists unknown keys, refused values, broken rules and settings that repeat their default, and nothing you paste leaves your browser.

Check my configuration→

A configuration that fails a check stops the broker at startup with the same message, for example:

invalid configuration:
  database.acquire_timeout (30s) must be below request_limits.timeout (30s)

Keys the broker doesn't know

A key the configuration doesn't define, whether in the file or as an ANDROMEDA__ variable, is ignored, so a file written for a later version still loads. At startup the broker logs one warning for each, with event = "configuration_setting_ignored". It names the key's path, such as server.unknown_key or jsonld.preloaded_contexts[1].unknown_key, and the file or variable that wrote it. A table the configuration doesn't define is reported once, as a whole. The ignored setting takes its default, so a misspelt key silently leaves the default in force. Look for these warnings after you change a file.

A key the configuration does define stays strict. A value of the wrong type, a malformed duration or size, or a choice the key doesn't offer is refused, because the broker can't tell what the value means.

The file carries no version key, and the loader translates nothing between versions. A file whose keys an older build doesn't know loads with warnings, never with a different meaning. andromeda configuration validate prints a warning for each ignored key, and ignored keys alone don't make it fail. andromeda configuration show prints the same warnings on standard error.

Value formats

Durations

A humantime string such as "500ms", "30s", "15m", "1h 30m" or "7days". configuration generate prints a day as "1day". Most durations must be above zero, and the temporal storage ones, such as temporal.storage.columnstore.convert_after, must be whole days.

Sizes

A bytesize string such as "512 KiB", "64 MiB" or "2 MB", or a bare number of bytes. configuration generate prints them with one decimal, such as "64.0 MiB".

Modes and choices

Lower-case tokens, such as "enabled", "disabled", "separate-port" or "remote-apply".

File paths

A relative jsonld.preloaded_contexts.path is read from the working directory, and when it doesn't resolve there, from the directory the configuration file is in.