Configuration

fabrica reads a single TOML file, layered over built-in defaults and overridable by the environment. A fully-commented starting point ships as fabrica.example.toml; copy it, keep only the keys you change, and validate with fabrica config check.

Resolution order

Sources are merged in the following order; a later source overrides an earlier one key-by-key:

1. Built-in defaults (every key has one — a bare config is valid).
2. /etc/fabrica/fabrica.toml
3. $XDG_CONFIG_HOME/fabrica/fabrica.toml (falls back to $HOME/.config/fabrica/fabrica.toml)
4. --config <path> passed on the command line
5. FABRICA__* environment variables

Missing files are skipped silently, so the same binary serves a first-run machine and a fully-configured one.

Environment overrides

Environment variables are prefixed FABRICA__ and nest with double underscores; single underscores inside a key are preserved:

FABRICA__SERVER__PORT=8080              # -> server.port
FABRICA__INSTANCE__DEFAULT_BRANCH=trunk # -> instance.default_branch
FABRICA__LOG__LEVEL=debug               # -> log.level

Secret files (*_file)

Any key ending in _file reads its value from that file and takes precedence over its inline sibling. This keeps secrets out of the config file for agenix / systemd-creds / Docker secrets:

Inline key	File key	Contents
auth.secret	auth.secret_file	HS256 session-signing key
mail.password	mail.password_file	SMTP password

A single trailing newline is trimmed from the file. Secrets are never logged, never appear in error messages, and render as <redacted> in fabrica config show.

Validation

Validation is strict and fails fast with actionable messages:

• Unknown keys are an error. A typo (prot for port, a misplaced section) aborts the load rather than being ignored.
• instance.url must be a valid URL and must not have a trailing slash.
• instance.default_branch must not be empty.
• storage.data_dir and storage.repo_dir must exist or be creatable (they may be created on first run).
• mail.backend = "smtp" requires mail.host and mail.from.

Some conditions are warnings — printed to stderr but non-fatal:

• auth.cookie_secure = true with a non-https instance.url: browsers will drop the session cookie. Use this only for local development.

Sections

Each section maps one-to-one to a [table] in the TOML file. See fabrica.example.toml for the default value and a comment on every key.

Section	Purpose
[instance]	Identity, canonical URL, default branch, anonymous access.
[server]	HTTP bind address/port, proxy trust, body-size and drain limits.
[ssh]	SSH bind address/port, host key path, advertised clone endpoint.
[storage]	Data and repository directories on disk.
[database]	Connection URL (sqlite:/postgres:) and pool size.
[auth]	Session/token lifetimes, cookie settings, Argon2id cost, signing key.
[mail]	Backend (smtp/stdout/none), sender, SMTP endpoint and encryption.
[ui]	Theme, asset/theme directories, diff/highlight limits.
[git]	git binary path and pack-transport limits.
[log]	Level and format (pretty/json).

Commands

• fabrica config check — validate the effective configuration and exit. Prints configuration ok and exits 0 on success; prints the problems and exits 1 otherwise. Warnings are printed but do not change the exit status.
• fabrica config show — print the effective, merged configuration with secrets redacted. Add --json for machine-readable output.

Both honour the global --config <path> flag.