OpenVelo Agent
98 lines
5.0 KiB
Markdown
98 lines
5.0 KiB
Markdown
---
|
|
type: api
|
|
title: Config Schema
|
|
description: Required/optional environment variables, validation rules, and the typed Config dataclass returned by tenbackward.config.load_config.
|
|
tags: [config, env, schema]
|
|
timestamp: 2026-08-04T17:51:00Z
|
|
---
|
|
|
|
# Purpose
|
|
|
|
`tenbackward.config.load_config()` is the single boundary that turns
|
|
process environment + optional `.env` file into a typed `Config`
|
|
dataclass. Job 1083 changes every variable that ships in
|
|
`.env.example` so that it is **explicitly required** at every layer
|
|
(`entrypoint.sh`, `config.validate_config`, and the rendered cron).
|
|
|
|
# Required Environment Variables
|
|
|
|
The following keys must be present and non-empty in the merged dotenv/process environment before application defaults are applied.
|
|
|
|
| Key | Purpose | Validation |
|
|
|---|---|---|
|
|
| `MASTODON_BASE_URL` | Mastodon instance to post against. | Valid `http` or `https` URL. |
|
|
| `MASTODON_ACCESS_TOKEN` | OAuth token used by the Mastodon client. | Required string; redacted in logs. |
|
|
| `MASTODON_VISIBILITY` | Post visibility. | `public` or `unlisted`. |
|
|
| `SITE_URL` | Source blog URL. | Valid `http` or `https` URL. |
|
|
| `HASHTAGS` | Comma-separated hashtags. | Required string. |
|
|
| `THROWBACK_PREFIX` | Prefix prepended to each status. | Required string. |
|
|
| `MAX_RETRIES` | Maximum number of pipeline attempts. | Non-negative integer; defaults to `5` when absent. |
|
|
| `RUN_AT` | Daily cron fire time. | `HH:MM` 24-hour format. |
|
|
| `TZ` | Cron and application timezone. | Valid IANA timezone. |
|
|
|
|
`BLOG_REPO_URL` and `BLOG_DIR` are optional and receive defaults after this required-key check. `DATA_DIR` is read separately from the process environment and defaults to `/app/data`.
|
|
|
|
# Defaults
|
|
|
|
Defaults are applied only after required-key validation. The current defaults are:
|
|
|
|
| Default key | Default value |
|
|
|---|---|
|
|
| `MAX_RETRIES` | `5` |
|
|
| `BLOG_REPO_URL` | `https://git.chaospott.de/Chaospott/site` |
|
|
| `BLOG_DIR` | `blog` (resolved relative to `data_dir`) |
|
|
|
|
Application-facing required values are not silently supplied by `config.py`; the container environment may still provide `TZ=Europe/Berlin` and Compose may provide development fallback values.
|
|
|
|
# `Config` Dataclass
|
|
|
|
| Field | Type | Source |
|
|
|-------------------------|-----------|----------------------------------------------|
|
|
| `mastodon_base_url` | `str` | `MASTODON_BASE_URL` |
|
|
| `mastodon_access_token` | `str` | `MASTODON_ACCESS_TOKEN` |
|
|
| `mastodon_visibility` | `str` | `MASTODON_VISIBILITY` |
|
|
| `site_url` | `str` | `SITE_URL` |
|
|
| `hashtags` | `str` | `HASHTAGS` |
|
|
| `throwback_prefix` | `str` | `THROWBACK_PREFIX` |
|
|
| `max_retries` | `int` | `MAX_RETRIES` (parsed as non-negative int) |
|
|
| `run_at` | `str` | `RUN_AT` |
|
|
| `tz` | `str` | `TZ` |
|
|
| `data_dir` | `Path` | `DATA_DIR`, default `/app/data` |
|
|
| `blog_repo_url` | `str` | `BLOG_REPO_URL` |
|
|
| `blog_dir` | `Path` | `BLOG_DIR` resolved against `data_dir` |
|
|
|
|
# Validation Behaviour
|
|
|
|
`validate_config(values)` collects all failures before raising so the
|
|
operator sees every problem at once. A single `ConfigError` lists each
|
|
problem joined with `"; "`. Validation covers:
|
|
|
|
* Required keys are non-empty.
|
|
* `RUN_AT` parses as `HH:MM`.
|
|
* `MASTODON_BASE_URL` and `SITE_URL` parse via `urllib.parse.urlparse`
|
|
with an `http`/`https` scheme and a non-empty `netloc`.
|
|
* `VISIBILITY` is one of `{"public", "unlisted"}` (`ALLOWED_VISIBILITY`).
|
|
* `BLOG_REPO_URL` (optional, has default) parses via `urllib.parse.urlparse`
|
|
with an `http`/`https` scheme and a non-empty `netloc` when present.
|
|
* `TZ` resolves via `zoneinfo.ZoneInfo`.
|
|
* `MAX_RETRIES` parses as a non-negative integer (rejects bools).
|
|
|
|
# Exit Codes
|
|
|
|
| Code | Source | Meaning |
|
|
|------|-----------------------------------------|----------------------------------------------------------------------|
|
|
| `1` | `main.main()` (retry budget exhausted) | Pipeline failed on every attempt after `MAX_RETRIES + 1` tries. |
|
|
| `2` | `main.main()` (`ConfigError`) | Configuration was present but invalid; details are logged. |
|
|
|
|
# Citations
|
|
|
|
* [1] `src/tenbackward/config.py` — `REQUIRED_KEYS`, `DEFAULTS`, `ALLOWED_VISIBILITY`, `Config`, `load_config`, `validate_config`.
|
|
* [2] `.env.example` — canonical env-var list.
|
|
* [3] `entrypoint.sh` — shell-side mirror of the required keys.
|
|
|
|
# Related
|
|
|
|
* [System Architecture](/architecture/system-overview.md)
|
|
* [Logging & Run Summary](/architecture/logging.md)
|
|
* [Environment Variable Setup](/operations/environment-setup.md)
|