---
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)