Run in Docker

The server and the bridge are also container images, for Linux on x86_64. They run the same build as the .deb packages. Anyone can pull them, no login needed:

Image	What it is
`registry.livematrix.io/livematrix/server`	The server, with its web client and management page.
`registry.livematrix.io/livematrix/bridge`	The bridge, for sound cards on another machine than the server.

Docker Desktop on macOS and Windows can’t give a container the computer’s network or its sound cards. Use the installers there.

Install with one command

On a Linux machine, this installs Docker if the machine has none, sets up the server and starts it:

curl -fsSL https://console.livematrix.io/install-docker.sh | bash

At the end it prints the address of the management page, which opens on the setup wizard. Go through it right away: until it has an administrator, anyone who opens the page can create one. The command also opens the server’s ports if ufw or firewalld is on, passes in the sound cards, and gives the container the Docker socket, so the server can update itself. The setup is in /opt/livematrix/server/compose.yaml; everything below applies to it, in that folder.

Add options after bash -s --:

curl -fsSL https://console.livematrix.io/install-docker.sh | bash -s -- --bridge --nightly

Option	What it does
`--bridge`	Installs a bridge instead, in `/opt/livematrix/bridge`.
`--nightly`	Follows the nightly builds instead of stable releases.
`--no-auto-update`	Leaves out the Docker socket. Update by hand then.
`--no-firewall`	Opens no ports.
`--dir <folder>`	Puts `compose.yaml` somewhere else.

Running it again on the same machine pulls the image again and starts it. It keeps the compose.yaml and the data as they are.

To set it up by hand instead, read on.

Choose a tag

Tag	What you get
`latest`	The latest stable release.
`1.4.0`	That release. Releases are kept.
`nightly`	The latest nightly build. Don’t use it for a production.
`0.0.2-dev.<time>.<commit>`	That nightly, while it is one of the last 14.

Use a version tag, such as 1.4.0, to decide yourself when the server changes. With latest, every docker compose pull can bring a new release.

Run the server

Create a folder with this compose.yaml:

services:
  server:
    image: registry.livematrix.io/livematrix/server:latest
    restart: unless-stopped
    network_mode: host
    environment:
      # Creates the administrator `admin` with this password on the first start.
      LIVEMATRIX_ADMIN_PASSWORD: change-me
    volumes:
      - server-data:/data
      # Keeps the machine's identity in the console when the container is replaced.
      - /etc/machine-id:/host/etc/machine-id:ro

volumes:
  server-data:

Start it with docker compose up -d and open http://<machine>:9080/admin/. Sign in as admin with the password from the file, then follow Get started.

network_mode: host puts the server on the machine’s own network, as an installed server is. Audio needs it: devices reach the server on the machine’s real addresses, over ports the server chooses as it goes. The images are tested this way. The server listens on the usual ports, 9080 for HTTP and 9443 for HTTPS and TURN, so open those in the machine’s firewall if it has one.

Settings from the environment

Most settings are made in the management page and kept on the volume. These can also come from environment::

Variable	What it does
`LIVEMATRIX_ADMIN_PASSWORD`	Creates the administrator `admin` when the server has none, so nobody else can take over a new server first. Never changes an existing account. `LIVEMATRIX_ADMIN_PASSWORD_FILE` reads it from a file instead, for example a Docker secret.
`LIVEMATRIX_LICENSE`	A licence the server loads when it holds none. It never replaces one the server already has.
`LIVEMATRIX_HTTP_PORT`, `LIVEMATRIX_HTTPS_PORT`	The HTTP and HTTPS ports. The management page then shows them as fixed.
`LIVEMATRIX_TURN_PORT`	The TURN port, when it should not follow the HTTPS port.

Sound cards on the server

The server’s built-in bridge can use the machine’s sound cards. Give the container the machine’s audio devices:

services:
  server:
    # … as above
    devices:
      - /dev/snd:/dev/snd

The container sees the cards through ALSA. A card that a desktop sound server such as PulseAudio or PipeWire holds is busy for livematrix, so use a machine without a desktop session, or a card the desktop doesn’t use.

Run a bridge

For sound cards on another machine, run the bridge image there:

services:
  bridge:
    image: registry.livematrix.io/livematrix/bridge:latest
    restart: unless-stopped
    network_mode: host
    devices:
      - /dev/snd:/dev/snd
    volumes:
      - bridge-data:/data

volumes:
  bridge-data:

Start it, open http://<bridge machine>:5678 and connect it as in Connect a remote bridge. On the same machine as the server, the server URL is ws://127.0.0.1:9080/ws.

The bridge keeps its configuration, with its bridge key, on its volume. livematrix-bridge-ctl works inside the container:

docker compose exec bridge livematrix-bridge-ctl --status
docker compose exec bridge livematrix-bridge-ctl --reset-ui-password

Your data

Everything the server keeps is on its /data volume: the database with its users, keys and party lines, its settings, backups and certificates. Replacing the container keeps all of it; deleting the volume deletes it.

The backups on the volume go with it. To keep copies elsewhere, set a backup Destination: S3-compatible storage works as it is. For a Server directory, mount the directory into the container first, outside /data, for example - /mnt/backup/livematrix:/backup, and enter /backup.

livematrix-server-ctl works inside the container too, for example to change the ports without signing in:

docker compose exec server livematrix-server-ctl --status
docker compose exec server livematrix-server-ctl --set-ports 9080 9443

Update

There are two ways: let the server update its own container from the management page, or pull the new image yourself.

From the management page

Give the container the Docker socket and use the latest or nightly tag:

services:
  server:
    image: registry.livematrix.io/livematrix/server:latest
    # … as above
    volumes:
      - server-data:/data
      - /etc/machine-id:/host/etc/machine-id:ro
      - /var/run/docker.sock:/var/run/docker.sock

The server then updates like an installed one. The tag is its release channel: latest follows Stable and nightly follows Nightly, so the channel on the Settings page shows as fixed. When a new version is out, the server pulls its image in the background, and a banner offers Install and restart. Installing takes a backup of the database first, then replaces the container with one of the new image, with the same volumes, devices, network and settings. Users are disconnected for the few seconds that takes.

If the new container doesn’t start, the old one comes back by itself, and Settings › Updates says why. The helper container that did the update stays behind, named after the server’s container with -update at the end, so docker logs can show what happened. A container pinned to a version, such as 1.4.0, never updates itself; change the tag to update it.

The bridge does the same with the same two settings, from its own page.

The Docker socket gives the container full control of Docker on the machine, which is as much as root. Mount it only on a machine where that is acceptable, such as one that runs nothing but livematrix.

By hand

Without the socket, or with a version tag, the release channel on the Settings page is off. An installed server takes a backup before every upgrade; here, take one yourself:

Under Setup → Backups, press Create backup, for example Before 1.5.0. It stays on the volume, under /data/backups/manual/. Download full backup saves a copy to your computer as well.
Pull the new image and replace the container:
Terminal window
```
docker compose pull
docker compose up -d
```

Users are disconnected for the few seconds the server takes to restart.

Go back to an older version

A newer version upgrades the database, and an older version won’t start on it. Put back the backup from before the update while the newer version is still in place, then change the tag:

docker compose stop server
docker compose run --rm --entrypoint ls server /data/backups/pre-upgrade /data/backups/manual
docker compose run --rm server backup restore /data/backups/pre-upgrade/<file>.sqlite

An update from the management page leaves its backup in pre-upgrade; one you took yourself is in manual. Then put the older version tag in compose.yaml and start it with docker compose up -d. Everything changed since that backup is lost.

Remove it

docker compose down stops and removes the containers and keeps the volumes, so a later docker compose up -d picks everything up again. docker compose down --volumes deletes the volumes too: the server’s database and backups, and the bridge’s configuration.