| 1 | # Configuration |
| 2 | |
| 3 | fabrica reads a single TOML file, layered over built-in defaults and overridable |
| 4 | by the environment. A fully-commented starting point ships as |
| 5 | [`fabrica.example.toml`](../fabrica.example.toml); copy it, keep only the keys |
| 6 | you change, and validate with `fabrica config check`. |
| 7 | |
| 8 | ## Resolution order |
| 9 | |
| 10 | Sources are merged in the following order; a later source overrides an earlier |
| 11 | one key-by-key: |
| 12 | |
| 13 | 1. Built-in defaults (every key has one — a bare config is valid). |
| 14 | 2. `/etc/fabrica/fabrica.toml` |
| 15 | 3. `$XDG_CONFIG_HOME/fabrica/fabrica.toml` (falls back to |
| 16 | `$HOME/.config/fabrica/fabrica.toml`) |
| 17 | 4. `--config <path>` passed on the command line |
| 18 | 5. `FABRICA__*` environment variables |
| 19 | |
| 20 | Missing files are skipped silently, so the same binary serves a first-run |
| 21 | machine and a fully-configured one. |
| 22 | |
| 23 | ### Environment overrides |
| 24 | |
| 25 | Environment variables are prefixed `FABRICA__` and nest with double |
| 26 | underscores; single underscores inside a key are preserved: |
| 27 | |
| 28 | ``` |
| 29 | FABRICA__SERVER__PORT=8080 # -> server.port |
| 30 | FABRICA__INSTANCE__DEFAULT_BRANCH=trunk # -> instance.default_branch |
| 31 | FABRICA__LOG__LEVEL=debug # -> log.level |
| 32 | ``` |
| 33 | |
| 34 | ### Secret files (`*_file`) |
| 35 | |
| 36 | Any key ending in `_file` reads its value from that file and takes precedence |
| 37 | over its inline sibling. This keeps secrets out of the config file for |
| 38 | agenix / systemd-creds / Docker secrets: |
| 39 | |
| 40 | | Inline key | File key | Contents | |
| 41 | | --------------- | ------------------ | ---------------------------- | |
| 42 | | `auth.secret` | `auth.secret_file` | HS256 session-signing key | |
| 43 | | `mail.password` | `mail.password_file` | SMTP password | |
| 44 | |
| 45 | A single trailing newline is trimmed from the file. Secrets are never logged, |
| 46 | never appear in error messages, and render as `<redacted>` in |
| 47 | `fabrica config show`. |
| 48 | |
| 49 | ## Validation |
| 50 | |
| 51 | Validation is strict and fails fast with actionable messages: |
| 52 | |
| 53 | - **Unknown keys are an error.** A typo (`prot` for `port`, a misplaced section) |
| 54 | aborts the load rather than being ignored. |
| 55 | - `instance.url` must be a valid URL and must not have a trailing slash. |
| 56 | - `instance.default_branch` must not be empty. |
| 57 | - `storage.data_dir` and `storage.repo_dir` must exist or be creatable (they may |
| 58 | be created on first run). |
| 59 | - `mail.backend = "smtp"` requires `mail.host` and `mail.from`. |
| 60 | |
| 61 | Some conditions are **warnings** — printed to stderr but non-fatal: |
| 62 | |
| 63 | - `auth.cookie_secure = true` with a non-`https` `instance.url`: browsers will |
| 64 | drop the session cookie. Use this only for local development. |
| 65 | |
| 66 | ## Sections |
| 67 | |
| 68 | Each section maps one-to-one to a `[table]` in the TOML file. See |
| 69 | `fabrica.example.toml` for the default value and a comment on every key. |
| 70 | |
| 71 | | Section | Purpose | |
| 72 | | ------------ | ------------------------------------------------------------- | |
| 73 | | `[instance]` | Identity, canonical URL, default branch, anonymous access. | |
| 74 | | `[server]` | HTTP bind address/port, proxy trust, body-size and drain limits. | |
| 75 | | `[ssh]` | SSH bind address/port, host key path, advertised clone endpoint. | |
| 76 | | `[storage]` | Data and repository directories on disk. | |
| 77 | | `[database]` | Connection URL (`sqlite:`/`postgres:`) and pool size. | |
| 78 | | `[auth]` | Session/token lifetimes, cookie settings, Argon2id cost, signing key. | |
| 79 | | `[mail]` | Backend (`smtp`/`stdout`/`none`), sender, SMTP endpoint and encryption. | |
| 80 | | `[ui]` | Theme, asset/theme directories, diff/highlight limits. | |
| 81 | | `[git]` | `git` binary path and pack-transport limits. | |
| 82 | | `[log]` | Level and format (`pretty`/`json`). | |
| 83 | |
| 84 | ## Commands |
| 85 | |
| 86 | - `fabrica config check` — validate the effective configuration and exit. Prints |
| 87 | `configuration ok` and exits `0` on success; prints the problems and exits `1` |
| 88 | otherwise. Warnings are printed but do not change the exit status. |
| 89 | - `fabrica config show` — print the effective, merged configuration with secrets |
| 90 | redacted. Add `--json` for machine-readable output. |
| 91 | |
| 92 | Both honour the global `--config <path>` flag. |