Skip to content

Linux

This section describes how to deploy Canvus server using containers on Linux.

Note

Supported distributions: Ubuntu 22.04+, Debian 12+, RHEL 9+, Fedora 38+, CentOS Stream 9+.

System requirements

  • 4 GB RAM minimum (8 GB recommended)
  • 2 CPU cores minimum (4 recommended)
  • 20 GB disk space minimum (50 GB recommended for production)
  • Internet connection for initial image download

Install Podman

Ubuntu / Debian:

sudo apt update
sudo apt install -y podman podman-compose

RHEL / Fedora / CentOS Stream:

sudo dnf install -y podman podman-compose

Verify:

podman --version
# Should show podman version 3.0+ (4.0+ recommended)

Login to the container registry

Canvus Server images are hosted on the MultiTaction container registry.

sudo podman login docker.multitaction.com -u canvus-deploy -p gldt-synTX_NnF8LcmnktR1xK

Note

sudo is required for all Podman commands. Podman uses separate container namespaces for root and non-root users. Since we need sudo for privileged port binding (ports 80/443), all commands must use sudo consistently.

Download the compose file

wget https://canvus-downloads.s3.amazonaws.com/server/podman-compose.yml

Configure the deployment

Edit podman-compose.yml before starting. At minimum, change these values:

In the canvus service:

environment:
  CANVUS_EXTERNAL_URL: https://canvus.example.com
  CANVUS_ADMIN_EMAIL: admin@yourcompany.com
  CANVUS_ADMIN_PASSWORD: YourSecurePassword123!
  POSTGRES_PASSWORD: a-strong-database-password

In the postgres service (must match the password above):

environment:
  POSTGRES_PASSWORD: a-strong-database-password

For testing, https://localhost works as the external URL. The server generates a self-signed certificate automatically.

Create data directory

sudo mkdir -p /canvus-data

The containers create subdirectories automatically on first start.

Start services

sudo podman-compose up -d

Note

sudo is required for two reasons:

  1. Privileged port binding --- rootless Podman cannot map host ports below 1024 (ports 80 and 443). External Canvus clients require HTTPS on port 443.
  2. Namespace consistency --- containers started with sudo are only visible to sudo commands.

The first startup takes longer because it pulls images, generates a TLS certificate, creates the database schema, and creates the admin user.

Verify

Check that containers are running:

sudo podman-compose ps

Both canvus-postgres and canvus-combined should be running. The health check for canvus-combined may take up to 2 minutes on first start (subsequent starts are faster).

Open https://localhost in your browser. Accept the self-signed certificate warning and login with the admin credentials you set above.

Backup, restore, and migration

See the configuration reference for full backup/restore procedures, including filesystem backups, the server binary\'s --backup/--restore commands, and migrating from bare-metal installations.

SSL certificates

Self-signed (default): The server generates a self-signed certificate on first startup. Browsers will show a security warning.

Production certificates: Place your CA-signed certificates in /canvus-data/certs/ before starting:

sudo cp your-certificate.pem /canvus-data/certs/server.cert.pem
sudo cp your-private-key.pem /canvus-data/certs/server.key.pem
sudo cp your-chain.pem /canvus-data/certs/server.chain.pem

Then start (or restart) the containers.

License activation

Via dashboard (recommended):

  1. Navigate to https://your-server/admin/settings/license
  2. Login with admin credentials
  3. Enter your activation key and click Activate

Via environment variable:

Set CANVUS_LICENSE_KEY in podman-compose.yml before first startup.

Offline activation:

Place .cslicense files in /canvus-data/licenses/ and restart.

Management

# Start / stop / restart
sudo podman-compose up -d
sudo podman-compose stop
sudo podman-compose restart

# View logs
sudo podman-compose logs -f canvus-combined

# Check status
sudo podman-compose ps

# Update to latest version
sudo podman-compose pull
sudo podman-compose down
sudo podman-compose up -d

Behind a reverse proxy

If another service (Traefik, nginx) already uses ports 80/443, use unprivileged ports:

environment:
  CANVUS_HTTPS_PORT: 8443
  CANVUS_EXTERNAL_URL: https://canvus.example.com

ports:
  - "8080:80"      # HTTP redirect (always port 80 inside container)
  - "8443:8443"    # HTTPS (matches CANVUS_HTTPS_PORT)

Note

The HTTP-to-HTTPS redirect always listens on port 80 inside the container. The left side of the port mapping controls the host port.

Configure your reverse proxy to forward to these ports.

Troubleshooting

Port already in use:

sudo ss -tlnp | grep :443

Stop the conflicting service or use unprivileged ports.

Permission denied on /canvus-data:

sudo chown -R $(id -u):$(id -g) /canvus-data

On RHEL/Fedora/CentOS, the :Z suffix on volume mounts handles SELinux relabeling automatically.

Container not found:

If podman ps shows nothing but sudo podman ps shows your containers, you have a namespace mismatch. Use sudo consistently.

Database connection issues:

sudo podman exec -it canvus-postgres pg_isready -U canvus -d canvus