docs: update documentation to OKF v0.1 format
This commit is contained in:
OpenVelo Agent
@@ -0,0 +1,96 @@
|
||||
---
|
||||
type: operations
|
||||
title: Cron Lifecycle
|
||||
description: How entrypoint.sh validates env, renders /etc/cron.d/tenbackward from RUN_AT/TZ, and hands off to cron -f.
|
||||
tags: [cron, entrypoint, ops]
|
||||
timestamp: 2026-08-04T17:51:00Z
|
||||
---
|
||||
|
||||
# Purpose
|
||||
|
||||
`entrypoint.sh` is the first process inside the container. Its job is
|
||||
to refuse to boot when something is wrong with env config and to
|
||||
materialise a cron file from the templated values.
|
||||
|
||||
# Sequence
|
||||
|
||||
1. Set `DEBIAN_FRONTEND=noninteractive`.
|
||||
2. Set `TZ` (default `Europe/Berlin`) and link `/etc/localtime` if
|
||||
`/usr/share/zoneinfo/${TZ}` exists and `/etc/localtime` does not.
|
||||
3. Iterate over `required_vars`. Any empty variable aborts with
|
||||
`ERROR: missing required environment variable(s): ...` and exits
|
||||
`1`. The current required set is listed in
|
||||
[Environment Variable Setup](/operations/environment-setup.md).
|
||||
4. Validate `RUN_AT` against
|
||||
`^([01][0-9]|2[0-3]):[0-5][0-9]$`. Invalid input exits `1` with
|
||||
`ERROR: RUN_AT='X' must be in HH:MM (24-hour) format`.
|
||||
5. Render `/etc/cron.d/tenbackward` into a `mktemp` file with:
|
||||
|
||||
```cron
|
||||
SHELL=/bin/bash
|
||||
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
|
||||
TZ=${TZ}
|
||||
${minute} ${hour} * * * cd /app && /usr/local/bin/python -m tenbackward >> /app/data/cron.log 2>&1
|
||||
```
|
||||
|
||||
6. Install the rendered file with mode `0644`, root:root.
|
||||
7. Run `crontab/install-cron.sh /etc/cron.d/tenbackward`. The helper
|
||||
refuses files that still contain the `__RUN_AT__` placeholder and
|
||||
files that do not start with an `^[A-Z_]+=` cron env line.
|
||||
8. Print a one-line confirmation: `tenbackward: starting cron
|
||||
(RUN_AT=..., TZ=...)`.
|
||||
9. `exec cron -f`.
|
||||
|
||||
# Output Files
|
||||
|
||||
| Path | Owner / Mode | Purpose |
|
||||
|------------------------------|--------------|------------------------------------------------------|
|
||||
| `/etc/cron.d/tenbackward` | root / 0644 | The rendered cron file. |
|
||||
| `/app/data/cron.log` | container user / append | `python -m tenbackward` stdout+stderr. |
|
||||
| `/app/data/posted.json` | container user / rw | Persisted state from `tenbackward.state`. |
|
||||
|
||||
# Cron Helpers
|
||||
|
||||
| File | Purpose |
|
||||
|---------------------------------|------------------------------------------------------------------------|
|
||||
| `crontab/tenbackward.cron` | Static template (env + PATH) shipped in the image. |
|
||||
| `crontab/install-cron.sh` | Validates and installs a rendered cron file with mode 0644. |
|
||||
|
||||
# Operator Recipes
|
||||
|
||||
* **Trigger a manual run** without waiting for the cron tick:
|
||||
|
||||
```bash
|
||||
docker compose exec tenbackward /usr/local/bin/python -m tenbackward
|
||||
```
|
||||
|
||||
* **Inspect the rendered cron file** (the file the container actually
|
||||
installed):
|
||||
|
||||
```bash
|
||||
docker compose exec tenbackward cat /etc/cron.d/tenbackward
|
||||
```
|
||||
|
||||
* **Tail the structured logs** produced by the bot:
|
||||
|
||||
```bash
|
||||
docker compose exec tenbackward tail -n 100 /app/data/cron.log
|
||||
```
|
||||
|
||||
Expect one JSON object per line (`startup`, optional `run_complete`,
|
||||
or `pipeline_error` / `pipeline_failed`).
|
||||
|
||||
# Build Script Notes
|
||||
|
||||
`build.sh` now `cd`s into its own script directory (so it works
|
||||
no matter where it is invoked from) and, when possible, symlinks
|
||||
itself to `/usr/local/bin/build.sh` so the build can also be run as a
|
||||
plain `build.sh` command inside the build context. The symlink is a
|
||||
best-effort `|| true`, so a read-only filesystem will not break the
|
||||
build.
|
||||
|
||||
# Related
|
||||
|
||||
* [Environment Variable Setup](/operations/environment-setup.md)
|
||||
* [Pipeline Runner](/architecture/pipeline-runner.md)
|
||||
* [Logging & Run Summary](/architecture/logging.md)
|
||||
@@ -0,0 +1,95 @@
|
||||
---
|
||||
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)
|
||||
Reference in New Issue
Block a user