Skip to main content

Installation

This page takes a clean server to a StreamVault Engine installation that is broadcasting, with its licence activated.

The whole installation is done by sve, the tool that lives on the server. There is no graphical installer and there will not be one: updating or reinstalling from the panel would mean giving Docker access to a process exposed to the internet, and a flaw in that process would be total control of your machine. That is why installing and updating ask for a session on the server.

Before you start​

You need three things:

  1. A clean server, with nothing else running on ports 80 and 443.

  2. Your licence key, six groups of five characters. Your provider gave it to you:

    9F2K7-M4XQ8-3TRWZ-P6HDY-C5NJ2-8VBRT

    It carries no prefix and no product marking. If yours starts with letters that look like a name, it is not a key for this product.

  3. Outbound internet from the server. The engine needs it to download its images, to activate the licence and to renew it every few hours. Your viewers do not need internet: they connect to this server.

A key is activated once and binds to that server. If you are going to install for testing and then move to the final machine, say so before activating: moving an installation is a step that exists, but it is easier not to have to take it.

Server requirements​

MinimumRecommended
Operating systemUbuntu 22.04, 24.04 or 26.04 · Debian 12 or 13Ubuntu 24.04
Architecturex86_64x86_64
Cores24 or more
Memory4 GB8 GB or more
Free disk on /—50 GB or more
Free ports80 and 44380 and 443

Other distributions may work, but only Ubuntu and Debian are tested.

Disk is what surprises people most: video segments being broadcast are written to disk constantly and take up space for as long as they are alive. The 50 GB is not for storing anything, it is working room.

Graphics card. Optional. With an NVIDIA card the engine can transcode in hardware if your licence includes that feature; without one, it transcodes on the processor. It is detected automatically — nothing to configure.

DVB adapters. Optional. If the server has /dev/dvb, the installer enables the matching layer.

Check the server first​

There is a script that reviews all of the above, installs Docker if it is missing and tells you whether this server will do. It does not install the engine and does not need your key:

curl -fsSL https://streamvault.fyi/install.sh | sudo bash

It ends with a summary of system, resources, GPU and ports. If anything comes up red, that server does not qualify: fix it before going on.

Step 1 · Install​

One command, in the directory where you want to install:

sudo mkdir -p /opt/streamvault/deploy && cd /opt/streamvault/deploy
curl -fsSL https://sync.streamvault.fyi/install.sh | sudo sh -s -- --key 9F2K7-M4XQ8-3TRWZ-P6HDY-C5NJ2-8VBRT

Replace the example key with yours.

Nothing has to be fetched by hand. Your licence key is the credential for everything: it downloads the tool, the version's package and the images. A suspended licence downloads nothing, which is exactly what you are buying.

The other script, at https://streamvault.fyi/install.sh, does not install: it is a pre-flight check of the server that ends by asking you to send us the summary, and it does not even accept --key. To install, use the one on sync..

What that command does​

The script does not install anything itself: it checks the essentials, downloads the sve tool using your licence key as the credential, verifies its checksum and hands over the work. All the logic is in sve, which is tested and knows how to roll back; a shell installer doing the same would be a second implementation, untested, that would diverge at the first version.

If you would rather not pipe curl into an interpreter — a reasonable precaution — read it first:

curl -fsSL https://sync.streamvault.fyi/install.sh -o install.sh
less install.sh
sudo sh install.sh --key 9F2K7-M4XQ8-3TRWZ-P6HDY-C5NJ2-8VBRT

What it does, in order​

  1. Checks everything before touching anything: root, key present, curl and docker installed, docker compose v2 available, x86_64 architecture. All together and at once: finding out Docker is missing after having written files leaves a machine that was clean half done.
  2. Downloads sve from sync.streamvault.fyi authenticating with your key, checks the sha256 by asking for it in a separate request, and installs it at /usr/local/bin/sve.
  3. Calls sve install --key …, which does the rest from here:
    • Pre-flight checks: that there is no .env already (if there is, that installation exists and what you want is sve update).
    • Fetches the published version's package (deploy-X.Y.Z.tar.gz, a few kilobytes) and unpacks it: the service definitions, the optional layers, the configuration template and the public key used to verify the images. The version installed is the package's, the one your provider published, not the tool's.
    • Writes the .env starting from .env.example, generating a database password, a session secret and an initial panel password. It starts from the example rather than an internal template so that new variables in future versions arrive with their comment and their default.
    • Decides the layers: looks for /dev/nvidiactl and /dev/dvb and adds only the layers that apply. They are separate because declaring a card that is not there stops the container from starting; if everything were in one file, the most common installation would be exactly the one that fails to come up.
    • Creates the data tree at /opt/streamvault/data and assigns it to the user the containers run as. The installer creates it because the containers do not run as root and cannot create anything under /opt.
    • Logs in to the image registry with your licence key. The key is the credential: a suspended licence does not download images, which is exactly what the subscription buys.
    • Downloads the images. This takes a while; they are several gigabytes.
    • Starts up and waits for every service to become healthy.
    • Activates the licence against the API it has just brought up.

When it finishes it prints the panel address, the admin user and a password. The password is shown once and the panel makes you change it on first login.

Rehearsing it without starting anything​

If you want to see what it would do before doing it:

sudo sve install --key 9F2K7-M4XQ8-3TRWZ-P6HDY-C5NJ2-8VBRT --dry-run

It writes the .env, creates the directories, says which layers would apply — and stops there, downloading and starting nothing.

Options​

OptionWhat for
--key KEYYour licence key. Required.
--domain example.comThe public name. Empty means access by IP.
--data-dir PATHWhere the data lives. Defaults to /opt/streamvault/data.
--no-gpuDo not use the graphics card even if there is one.
--no-dvbDo not use the DVB adapters even if there are any.
--dry-runPrepare and explain, without starting anything.
--dir PATHThe package directory. Defaults to the current one.

Step 2 · Log in to the panel​

With the installation finished:

http://YOUR-SERVER-IP:8080

It also answers on port 80. The panel and the API are served from the same origin: there is no need for a second name or a second certificate to get going, and the panel works the same by IP as by name.

Log in as admin with the password the installer printed, and change it — the panel is going to ask you anyway.

Check everything is where it should be:

sudo sve status

It shows the installed version, the licence state with its validity date, whether a newer version has been published, and one line per service with its health.

Step 3 · Name and certificate (optional, later)​

You can run by IP indefinitely. When you want a name with TLS: point the domain at this server, leave the certificate where SVE_CERTS_DIR says, add docker-compose.tls.yml to COMPOSE_FILE in the .env and fill in SVE_DOMAIN and SVE_PUBLIC_BASE_URL. From then on it also listens on 443 and 8443.

The HTTPS block is only generated if there is a readable certificate, on purpose: nginx refuses to start if the files of a certificate it declares are missing, and an installation without one — most of them, at the start — would lose the whole web server over a block it does not use.

If something fails​

"esto tiene que correr como root: use sudo"​

sudo is missing. The installer writes to /usr/local/bin and /opt, and needs to read hardware values only root can read.

"hace falta 'docker' y no esta instalado" or "hace falta el complemento docker compose (v2)"​

Install it and run again. The pre-flight script (curl -fsSL https://streamvault.fyi/install.sh | sudo bash) installs it if it is missing.

"el servidor no acepto esa clave"​

Three causes, in order of likelihood:

  1. A typing mistake. The key carries a check digit precisely to catch that before spending an attempt; if you mistyped it while copying, it never even tries.
  2. The key has already been activated on another server. Each key is good for one installation.
  3. The licence is suspended or has expired. Ask your provider.

There is an attempt limit: ten activations per hour per key. If you exceed it, wait; do not insist, because twenty failures in 24 hours lock the key pending review.

"no se pudo hablar con sync.streamvault.fyi"​

This server has no outbound internet, or something is filtering it. Check:

curl -sS -o /dev/null -w '%{http_code}\n' https://sync.streamvault.fyi/v1/public/health

"en . no hay ningun docker-compose.yml: descomprima ahi el paquete de la version"​

You are running the installer outside the package directory. Go to the deploy/ directory that appeared when unpacking deploy-X.Y.Z.tar.gz and run it again, or use --dir to point at it.

"ya hay un .env: esta instalacion existe, use sve update"​

This server already has an installation. Do not overwrite it: if you want to bring it up to date, use sve update. If you really want to start from scratch, that means deleting that installation's data and it is a different decision.

The images take forever or the download breaks​

They are several gigabytes. If it breaks, run the same command again: Docker resumes the layers already downloaded. Nothing has been deleted.

"no quedó sano" while waiting for start-up​

The installation is still standing: half an hour of downloading is not undone because one service is slow. Look at what is happening:

sudo sve doctor
sudo sve logs api

A cold start of an installation with many channels includes migrations and a staggered start-up, and it is given five minutes.

"la instalación está en marcha, pero la licencia no se activó"​

This is the anticipated case: the engine is running and only activation is missing. Go into the panel and activate it under System → Licence, pasting the same key.

If the error says pin_required, your licence is on the enterprise plan and also needs a six-digit PIN that reaches you through a channel other than email. That case can only be completed from the panel.

Once activated, sve status says the licence is not valid​

The licence binds to this machine through several hardware values. One of them lives in a file that sve install prepares before the first start-up, because the containers do not run as root and cannot read it from the system. To check the engine sees it:

# It has to be a FILE. If it says "directory", that is the problem.
docker compose exec api ls -ld /host/dmi.txt

# And return something.
docker compose exec api cat /host/dmi.txt

Coming back empty is not a fault: some virtual machines do not expose those values. The licence binds anyway, with one value fewer. Coming back as a directory is a fault, and can only happen on installations made before 1.12.2: stop the stack, delete that directory, run sve install again or create the file by hand, and bring it back up.

And now​

  • Verify the images are the ones we say they are. Every image is signed and so is its dependency inventory, and the public key comes in the package (keys/cosign.pub): the check runs from your machine, against the registry, without asking us anything.
  • Schedule backups. sve backup dumps the whole database. What really needs keeping is the database and your video files; the rest rebuilds itself.
  • Keep the system up to date. See Updating.