---
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`      | `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.         |

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