Installation¶

The Quick start takes one machine to a playing stream. This page is about what installation actually does and how to deploy Catena in production: what the delivery consists of, where the secrets live, how to attach an external PostgreSQL, and which ports open.

The packages¶

There are two packages, split along one line — who needs a database.

• catena goes on the first machine of the cluster. It is the control plane: the console, the viewer storefront and the central: section in the configuration. The package depends on PostgreSQL and sets the database up right there.
• catena-base goes on every other machine — the streamers, and the ones that will stand by for the central. It is the same server, without the console and without a database: the binary, the catena.service unit, the /etc/catena configuration directory and the /var/lib/catena state directory.

What a catena-base machine becomes is decided by two questions during installation, and both may be left unanswered:

• Connect to an existing PostgreSQL? The address is what a machine needs to become a second central instance: a central group is several machines over one database. The rest such a machine takes from its own configuration — see The central group. A streamer needs no database at all.
• Join a central cluster? The address of the central and a join token make the machine a streamer of that cluster — see Adding a streamer. What runs on it is from then on the central's decision.

The catena package is pinned to the exact version of the catena-base underneath it, so the two upgrade together.

The encoding plugins arrive as a recommended dependency: the server runs without them, but has nothing to encode with.

The catena package's post-install provisions the box: creates the catena role and database in PostgreSQL, generates the database and administrator passwords, and writes them into /etc/catena/secrets.env (root-owned, mode 0600):

DATABASE_URL=postgres://catena:...@127.0.0.1:5432/catena
EDIT_AUTH_PASSWORD=...

The unit attaches this file as an EnvironmentFile. Package upgrades do not rotate the secrets — once written, they survive any upgrade.

The installer asks for the license key itself and writes it into /etc/catena/license.txt (root-owned, mode 0600). Leaving the question empty still installs the package, but the service will not start — put the key into that same file (or pass the LICENSE_KEY variable) and run systemctl start catena. For rollouts the answer is preseeded with debconf-set-selections — see Unattended rollout.

The whole surface of the installation belongs to catena-base: the catena.service unit, the /etc/catena configuration directory and the /var/lib/catena state directory. A plain sapsan will not install next to it — the packages are declared as conflicting, because exactly one streamer must run on the box.

An external PostgreSQL¶

PostgreSQL is central's only state carrier, and in production it belongs on a managed cluster with backups, not on the same machine. It is enough to change DATABASE_URL in /etc/catena/secrets.env to the external database and restart the service: central applies the schema itself on start, there are no separate migration steps.

The ports¶

The package installs no configuration with a port. Out of the box, port 80 comes up (set in the INITIAL_HTTP_PORT variable) — and that is exactly an initial value: it acts only while no HTTP listeners are set by anything else. From then on the ports are owned by the streamer's config — edited from the console like on any cluster machine. The HTTP=<port> variable is the opposite — a permanent override on top of everything.

What opens and why:

Between cluster machines: all control traffic is initiated by the streamer — it needs HTTP(S) access to central; the way back, central only calls the streamer's api_url (media proxying and statistics). Viewers need HTTP(S) to central and, with redirects, to the streamers' public addresses.

Check¶

systemctl status catena
journalctl -u catena -n 50

Then — logging into the console and the first stream. The typical no-start causes — the license and an unreachable PostgreSQL — are covered in the Quick start troubleshooting.