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.serviceunit, the/etc/catenaconfiguration directory and the/var/lib/catenastate 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 prompts for a license key and saves a non-empty answer to /etc/catena/license.txt with mode 0600. If the answer is blank, the service starts in maintenance mode after successful provisioning. On the central server, open the recovery page and upload the key through the interface. As a fallback, place the key manually in /etc/catena/license.txt or set LICENSE_KEY; the service retries activation when the file appears. For unattended installation, use debconf-set-selections. A non-empty LICENSE_KEY takes precedence over the file.
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:
| Port | Set by | Purpose |
|---|---|---|
| HTTP (initially 80) | INITIAL_HTTP_PORT, then the streamer's config |
The console, the API, the viewer front /streaming, streamer sync |
| RTSP, RTMP (TCP), WebRTC (UDP) | Listeners in the streamer settings | Ingest and serving over these protocols |
| SRT (UDP) | A listener per stream: the port from SRT play | Serving a stream over SRT |
| UDP inputs | The port of each multicast source | MPEG-TS ingest |
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. Typical startup and license problems — are covered in the Quick start troubleshooting.