m0rph3us1987/10Backward
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update documentation to OKF v0.1 format

Browse Source
This commit is contained in:
OpenVelo Agent
2026-08-04 20:48:13 +00:00
parent 3545b81546
commit abbfad76dc
8 changed files with 193 additions and 87 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/operations/environment-setup.md
+14 -23
View File
@@ -18,26 +18,21 @@ full set before the container will boot.
|--------------------------|--------------------------------|---------------------------------------------------|
| `MASTODON_BASE_URL` | `https://mastodon.social` | Mastodon instance to post against. |
| `MASTODON_ACCESS_TOKEN` | _(from your Mastodon account)_ | OAuth access token. |
| `VISIBILITY` | `public` | Post visibility (`public` or `unlisted`). |
| `SITE_URL` | `https://blog.example.com` | Source blog URL (used by the future clone step). |
| `HASHTAGS` | `#throwback,#10backward` | Hashtags appended to every throwback post. |
| `THROWNBACK_PREFIX` | `Heute vor 10 Jahren:` | Prefix prepended to every Mastodon status. |
| `MAX_RETRIES` | `3` | Non-negative retry count for the pipeline. |
| `RUN_AT` | `09:00` | Daily fire time (HH:MM, 24-hour). |
| `TZ` | `Europe/Berlin` | IANA timezone for cron + container clock. |
| `MASTODON_VISIBILITY` | `public` | Post visibility (`public` or `unlisted`). |
| `SITE_URL` | `https://blog.example.com` | Source blog URL. |
| `HASHTAGS` | `#throwback,#10backward` | Hashtags appended to every throwback post. |
| `THROWBACK_PREFIX` | `Heute vor 10 Jahren:` | Prefix prepended to every Mastodon status. |
| `MAX_RETRIES` | `5` | Maximum number of pipeline attempts. |
| `RUN_AT` | `09:00` | Daily fire time (`HH:MM`, 24-hour). |
| `TZ` | `Europe/Berlin` | IANA timezone for cron and application. |
| `BLOG_REPO_URL` | project default | Optional source repository URL. |
| `BLOG_DIR` | `blog` | Optional clone directory, relative to `DATA_DIR` unless absolute. |
# Where Each Name Is Enforced
* `entrypoint.sh` — exports `TZ`, validates all nine are non-empty,
and validates `RUN_AT` matches `^([01][0-9]|2[0-3]):[0-5][0-9]$`
before writing the cron file. A missing var aborts the container
with `ERROR: missing required environment variable(s): ...` and
exits `1`.
* `tenbackward.config.validate_config` — same set, plus URL/visibility/
TZ/MAX_RETRIES validation. Failures surface as a single
`ConfigError` listing every problem.
* The `kilo.json` config file is **not** an env-var file — it is the
agent runtime configuration.
* `entrypoint.sh` — validates all nine required keys, validates `RUN_AT`, and installs the cron file as root. The cron-launched wrapper then drops privileges to `bot` before Python runs.
* `tenbackward.config.validate_config` — validates the merged raw required keys plus URL, visibility, timezone, and retry syntax. Defaults are applied only after required-key validation.
* `docker-compose.yml` — supplies development environment values and mounts `./data` at `/app/data`.
# Setup Steps
@@ -80,13 +75,9 @@ If you have an existing `.env` from the scaffold, rename these
manually. The renamed variables are **not** backwards compatible — the
container will refuse to start with both versions set.
# Defaults That Can Be Removed
# Defaults
`DEFAULTS` provides fallbacks for `VISIBILITY`, `THROWNBACK_PREFIX`,
`MAX_RETRIES`, `TZ`, and `RUN_AT`. You may leave them out of your
`.env`, but the operator contract is "every required key is set" —
prod deployments should set them explicitly so a missing key is
caught at boot instead of silently used as a default.
`MAX_RETRIES` defaults to `5`; `BLOG_REPO_URL` and `BLOG_DIR` also have application defaults. Other application-facing required keys must be present in the raw merged dotenv/process environment. The Docker image supplies `TZ=Europe/Berlin`, and Compose supplies development fallbacks, but production deployments should set every required value explicitly.
# Related