Quick start¶

This page takes one bare machine to a playing channel. Everything happens on that single machine: the catena package turns it into a complete installation — control plane and streamer in one process — and provisions its own database on the way.

You do not set up PostgreSQL, nodes or a cluster here. Those come later, when the installation grows beyond one box.

What you need¶

• A machine with Ubuntu 24.04 and root access.
• Outbound internet access — the license is activated online.
• A license key file (license.txt). Catena does not start without it.

Connect the repository¶

Packages come from the Flussonic repository:

curl -L http://apt.flussonic.com/repo/master/dev.key > /etc/apt/trusted.gpg.d/dev.gpg
echo "deb http://apt.flussonic.com/branch/sapsan/master repo/" > /etc/apt/sources.list.d/flussonic.list
apt update

Put the license in place¶

Place the license file before installing, so the service starts right after installation:

mkdir -p /etc/catena
cp license.txt /etc/catena/license.txt
chmod 600 /etc/catena/license.txt

If you do not have the file at hand, skip this step: the installer asks for the key and writes it itself.

Install¶

apt install --install-recommends catena

One package is enough. catena makes this machine a Catena installation, and it pulls in what that requires: the streaming server of the matching version and PostgreSQL.

--install-recommends matters: the transcoder plugins (sapsan-transcoder) are a recommended, not a required, dependency — the server runs without them, but nothing can be encoded. Apt installs recommended packages by default, so the flag changes nothing on a stock system; on a host configured with APT::Install-Recommends "false" it is what keeps transcoding available.

During installation the catena package:

• creates the catena PostgreSQL role and database;
• generates a database password and an administrator password, and writes both to /etc/catena/secrets.env (mode 0600, owned by root);
• starts catena.service, which applies the database schema on its first start.

Passwords are never printed to the terminal — you read them from the file. Reinstalling or upgrading the package reuses the existing secrets instead of rotating them.

Log in¶

Read the administrator password:

grep EDIT_AUTH_PASSWORD /etc/catena/secrets.env

Open http://<server-address>/ in a browser and log in as admin with that password. You land on the Dashboard: one streamer — this machine — and no channels yet.

Create the first channel¶

Go to Channels. A fresh installation has none yet.

Enter quickstart as the name and press Create. The channel opens on the Sources tab with nothing configured yet.

Press + Add Source and set its protocol to Synthetic — a built-in generator, so you can verify playback before connecting a real source. Tick both Generate video (SMPTE bars) and Generate audio (beep/bop): the defaults that appear (1280×720 at 25 fps, 48 kHz stereo) are what you want. Press Save.

The generator emits uncompressed frames, which no ordinary player reads, so the channel also needs a transcoder. Open the Process tab and press Standard ladder 1080/720/360 + AAC — one preset covers the whole job. Press Save.

Central writes the channel down and hands it to the streamer. Within a few seconds the channel shows up as running.

Play it¶

Go back to the Basic Settings tab. The channel page has a built-in player: test bars with a running clock mean the whole path works — source, transcoder, streamer, playback.

The same channel is available to any external player at http://<server-address>/streaming/v/quickstart/index.m3u8.

If something went wrong¶

Check the service and its log:

systemctl status catena
journalctl -u catena -n 50

• The service is not running and the log mentions the license. The license file was missing at installation time. Put it in /etc/catena/license.txt and run systemctl start catena.
• Installation reported that PostgreSQL was unreachable. The database was not provisioned. Create it yourself, write DATABASE_URL into /etc/catena/secrets.env and run systemctl restart catena.
• The player says it cannot load the video. The channel is running but nothing playable comes out of it — almost always a missing transcoder: the synthetic generator produces raw frames, and a player needs H.264 and AAC. Check the Process tab.
• The transcoder is configured but the channel still produces nothing. Check that the encoding plugins are installed: dpkg -l | grep sapsan-transcoder. If only the -base package is there, the box was installed without recommended packages — run apt install --install-recommends catena.
• The channel exists but does not start. Look at the channel page: it shows whether the channel has been placed on a streamer and whether its source is alive.

Where to go next¶

Everything on this one machine, no extra setup required:

• connect real sources, set up backup inputs and failover;
• add multi-bitrate transcoding, archive recording and nPVR;
• configure playback and its authorization.

When one machine is no longer enough, add a second one — the control plane you have now stays where it is, nothing gets dismantled.