96 lines
3.9 KiB
Markdown
96 lines
3.9 KiB
Markdown
---
|
|
type: operations
|
|
title: Environment Variable Setup
|
|
description: How to provide and validate the required env vars for the 10Backward container — .env, docker-compose, and the runtime check in entrypoint.sh.
|
|
tags: [env, ops, setup]
|
|
timestamp: 2026-08-04T17:51:00Z
|
|
---
|
|
|
|
# Purpose
|
|
|
|
Job 1083 promoted every previously-optional knob in `.env.example`
|
|
to required, and renamed three of them. Operators must populate the
|
|
full set before the container will boot.
|
|
|
|
# Required Variables
|
|
|
|
| Variable | Example value | Purpose |
|
|
|--------------------------|--------------------------------|---------------------------------------------------|
|
|
| `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` | `Throwback:` | Prefix prepended to every post. |
|
|
| `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. |
|
|
|
|
# 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.
|
|
|
|
# Setup Steps
|
|
|
|
1. Copy the template:
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
2. Replace placeholder values in `.env` (the example ships with
|
|
`MASTODON_ACCESS_TOKEN=replace-me` and `https://mastodon.example`).
|
|
|
|
3. Verify the file parses by running the validator directly:
|
|
|
|
```bash
|
|
python -m tenbackward
|
|
```
|
|
|
|
A successful validation run emits one `startup` JSON log line and
|
|
exits `0`. Missing/invalid config exits `2`.
|
|
|
|
4. Bring up the container:
|
|
|
|
```bash
|
|
docker compose up --build
|
|
```
|
|
|
|
The required-var check in `entrypoint.sh` runs first; if any
|
|
variable is empty, the container exits before `cron` starts.
|
|
|
|
# Renames vs. Job 1082
|
|
|
|
| Old key | New key |
|
|
|------------------------|--------------------------|
|
|
| `MASTODON_VISIBILITY` | `VISIBILITY` |
|
|
| `THROWBACK_PREFIX` | `THROWNBACK_PREFIX` |
|
|
| `RETRY_COUNT` | `MAX_RETRIES` |
|
|
|
|
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` 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.
|
|
|
|
# Related
|
|
|
|
* [Config Schema](/architecture/config-schema.md)
|
|
* [System Architecture](/architecture/system-overview.md)
|
|
* [Cron Lifecycle](/operations/cron-lifecycle.md)
|