Installation

katha ships as a container image at ghcr.io/dlepaux/katha. You need a running Kavita instance and an SMTP account to send from.

1. Configure

katha is configured entirely through environment variables. Grab the template from the repository and fill it in:

cp .env.example .env

At a minimum, set:

• KATHA_BASE_URL — the public URL katha's magic links point at.
• KATHA_HMAC_SECRET — the token signing key: openssl rand -hex 32.
• KATHA_SMTP_HOST / _USER / _PASS / _SENDER — your SMTP account.
• KATHA_KAVITA_DB, KATHA_COVERS_DIR — paths to Kavita's database and covers.
• KATHA_DB — where katha keeps its own database.

The full list, with defaults, is on the Configuration page.

2. Run the web server

docker run -d --name katha --env-file .env \
  -p 8792:8792 \
  -v /path/to/kavita:/kavita:rw \
  -v /path/to/katha-config:/config \
  ghcr.io/dlepaux/katha serve

Mount Kavita read-write, even though katha only reads

Kavita keeps its database in WAL mode. SQLite needs to create the -wal/-shm sidecar files to open a live database, so the directory must be writable — katha itself opens the database with a read-only connection and never modifies your library.

Put katha behind a reverse proxy that terminates HTTPS, so the magic-link tokens are never exposed in transit. Point KATHA_BASE_URL at the public HTTPS URL.

3. Schedule the sender

run-due is a one-shot: it sends to whoever is due, then exits. Run it daily — each reader's own frequency decides whether they actually get an email on a given day.

# crontab — every day at 09:00
0 9 * * *  docker run --rm --env-file /path/to/.env \
  -v /path/to/kavita:/kavita:rw \
  -v /path/to/katha-config:/config \
  ghcr.io/dlepaux/katha run-due >> /var/log/katha.log 2>&1

4. Preview before you send

Render a sample email to a file (no database needed) to eyeball the design, or --send it to yourself:

docker run --rm --env-file .env \
  -v /path/to/kavita:/kavita:rw -v /path/to/katha-config:/config \
  ghcr.io/dlepaux/katha preview --send you@example.com

Docker Compose

services:
  katha:
    image: ghcr.io/dlepaux/katha:latest
    command: serve
    env_file: .env
    ports:
      - "127.0.0.1:8792:8792"
    volumes:
      - /path/to/kavita:/kavita:rw
      - ./katha-config:/config
    restart: unless-stopped

Run run-due from your host scheduler with docker compose run --rm katha run-due (see the cron example above).