Skip to content

Components and reliability

A Catena installation is made of few parts, and each has its own state carrier and its own guarantees. This page is the map: what is stored where, what survives the loss of what, and what upgrade compatibility rests on. The cluster's behavior during a central outage is covered separately — Streamer autonomy.

What the installation consists of

  • The catena service on the central machine — the control plane and the local streamer in one process.
  • PostgreSQL — central's state store. The only one: central has no state directory of its own.
  • The streamer services — broadcasting; each with its own state directory and its own archive disks.
  • The metrics store — built-in, in process memory, with a horizon of a few hours; history for the charts, not an archive.

What lives in PostgreSQL

Everything that makes up the installation's desired state and records:

  • channel configurations and streamer configs;
  • the streamer registry — records with the machines' identity and keys;
  • the channel placement, the decision journal and the layouter runs;
  • the CDN zones;
  • the closed sessions journal;
  • central's TLS material — the ACME account and the issued certificates.

The consequence is simple: an intact database backup is an intact installation. Taking and restoring it — Backup and restore.

What lives on a streamer

The /var/lib/catena state directory of every machine:

  • server.id and the activation cache — the machine's licensing identity;
  • the streamer's cluster identity — the key it presents itself to central with;
  • the cache of the applied configuration slice — what powers the warm start without central;
  • the local journal of closed sessions until central harvests it.

The DVR archive lives elsewhere — on the dedicated disks set in the streamer settings.

What survives the loss of what

Lost What happens What to do
The central process The air and recording continue; management and the viewer path through central freeze Streamer autonomy; bring the process up — the cluster knits itself
The PostgreSQL database As above, plus the desired state is lost Restore from a dump — the streamers reconnect on their own
The database, and there is no backup The air continues; the streamers are orphaned Re-attach each one: a state reset plus a fresh token
A streamer's state directory The machine loses its identity — both licensing and cluster Join the machine anew; the channels re-place
A DVR disk That disk's archive is lost; the air is untouched The disk indicators in diagnostics
The metrics store (a process restart) A few hours of chart history are lost Nothing — it accumulates again

Compatibility guarantees

  • Different versions coexist. The wire protocol only grows by addition: unknown fields must be ignored by both sides, so central and streamers of neighboring versions work together.
  • The database schema is compatible within a two-version window. A newer schema under older code is the norm; that enables both a staged upgrade and a binary rollback without a database rollback.
  • Registration is deliberately non-idempotent. Joining the same machine again creates a new registry record, and server_id duplicates are marked by the registry with the decision left to the operator — see the streamer list.