Quick start¶

This page takes one bare machine to a playing stream. 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. Copy it from the client area on my.flussonic.com: the installer asks for the key itself, there is no license.txt to create by hand.

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

Install¶

apt install --install-recommends catena

The installation asks for the license key — paste the one you copied from the client area. The package writes it into /etc/catena/license.txt (owned by root, mode 0600) itself. The answer may be left empty: the package installs, but the service does not start until the key is there. If the license file is already on the machine, the question is not asked — an upgrade re-asks nothing.

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 streams yet.

Create the first stream¶

Go to Streams. A fresh installation has none yet.

Enter quickstart as the name and press Create. The stream 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 stream also needs a transcoder. Open the Transcoder tab and press Standard ladder 1080/720/360 + AAC — one preset covers the whole job. Press Save.

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

Play it¶

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

The same stream 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 key was not entered during installation. 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 stream 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 Transcoder tab.
• The transcoder is configured but the stream 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 stream exists but does not start. Look at the stream page: it shows whether the stream 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.