Skip to content

Standalone Linux install

This guide installs Canvus Server natively on Ubuntu from a single .deb package. No containers, no Docker. The package bundles everything the server needs and registers it as systemd services that start on boot:

  • mt-canvus-server --- the Canvus Server itself.
  • canvus-postgres --- a dedicated, bundled PostgreSQL 18 cluster, listening on localhost only.
  • the web client and the web/auth gateway, both served directly by the server process, with no separate Node.js runtime.

Which install do I want?

This is the standalone install: a native install for a single Ubuntu host. If you already run containers, see the Linux container install. Both are current, supported options --- see Choosing an installation method.

System requirements

  • Ubuntu 24.04 LTS, 64-bit (amd64)
  • Root access, or an account with sudo
  • Inbound TCP 443 (HTTPS) and TCP 80 (redirects to HTTPS)

The bundled PostgreSQL cluster listens on 127.0.0.1:5433 and is not reachable from outside the host. Port 5433 is used rather than the PostgreSQL default so the bundled cluster cannot collide with a system PostgreSQL you already run.

Dependencies are resolved by apt from the package metadata; you do not need to install PostgreSQL, Node.js, or a web server yourself.

What gets installed where

Path Contents
/opt/canvus/bin/ mt-canvus-server and the gateway
/opt/canvus/postgres/ bundled PostgreSQL 18 binaries
/etc/MultiTaction/canvus/mt-canvus-server.ini server configuration
/var/lib/canvus/postgres/ PostgreSQL data directory
/var/lib/mt-canvus-server/assets/ media assets
/var/lib/mt-canvus-server/backups/ server backups
/var/lib/mt-canvus-server/logs/server/ server logs
/etc/MultiTaction/canvus/server/certificates/ TLS certificates

/var/lib/canvus/ and /var/lib/mt-canvus-server/ hold all persistent data and are preserved across uninstall and upgrade.

Install

Download canvus-server_<version>_amd64.deb from the Canvus downloads page, then install it:

sudo apt install ./canvus-server_<version>_amd64.deb

Install from the local file path (note the leading ./) so apt resolves the dependencies rather than searching your configured repositories for a package of that name.

Installation provisions the canvus service account, initialises the bundled PostgreSQL 18 cluster, creates the canvus database, generates the database password and session secret, renders the configuration file, and enables and starts both services. It is idempotent, so it is safe to re-run.

Post-install setup

Two steps are not performed by the installer.

1. Create an administrator account

sudo runuser -u canvus -- /opt/canvus/bin/mt-canvus-server --create-admin <email> <password>

2. Activate the license

Clients cannot connect until the server is licensed. See Licensing.

Verify the install

# Both services should be active (postgres first, then the server):
systemctl status canvus-postgres.service mt-canvus-server.service

# The server answers locally (-k skips the self-signed certificate check):
curl -kI https://127.0.0.1/

On first start the server generates a self-signed TLS certificate into /etc/MultiTaction/canvus/server/certificates/. To use a CA-issued certificate instead, set certificate-file, certificate-key-file and certificate-chain-file in the [certificates] section of /etc/MultiTaction/canvus/mt-canvus-server.ini, then restart the server.

Editing the configuration file

/etc/MultiTaction/canvus/mt-canvus-server.ini contains the generated database password and session secret and is mode 0600. Edit it as root and do not change its ownership or permissions. Restart mt-canvus-server after any change.

Upgrading

Upgrade by uninstalling the current version, rebooting, and installing the new one. Do not upgrade in place. See Updating a standalone deployment for the full procedure, including the additional step required when the bundled PostgreSQL major version changes.

Uninstalling

sudo apt remove canvus-server

apt remove stops and disables both services and removes the binaries. It preserves /var/lib/canvus/ and /var/lib/mt-canvus-server/ --- the database, assets, backups and configuration --- so a later reinstall finds the data intact.

Do not use apt purge

apt purge canvus-server deletes the PostgreSQL cluster, the generated secrets, the server state directory and the canvus service account. This destroys all canvases and cannot be undone without a restored backup. Use apt remove unless you intend to erase the server's data permanently.

Troubleshooting

The server does not start. Check the service and its logs:

systemctl status mt-canvus-server.service
sudo journalctl -u mt-canvus-server.service -n 50
sudo tail -n 50 /var/lib/mt-canvus-server/logs/server/*.log

mt-canvus-server requires canvus-postgres and waits for the cluster to accept connections before starting. If the cluster is not ready the server exits; check canvus-postgres first.

Checking the bundled cluster directly:

sudo -u canvus /opt/canvus/postgres/bin/pg_isready -h 127.0.0.1 -p 5433 -U canvus_admin