Skip to content

Migrating from bare-metal to containers

This guide describes how to migrate an existing bare-metal Canvus server installation (Ubuntu .deb or Windows .exe) to the containerised deployment.

Warning

Migration is a one-way process. After migrating to containers, do not attempt to restore the data to a bare-metal installation of the same or older version.

Before you begin

  • Ensure the target host meets the container system requirements
  • Ensure you have enough disk space for both the old and new data during migration
  • Schedule a maintenance window — the server will be unavailable during migration

Step 1: Back up the existing bare-metal installation

On the current server, create a backup:

# Ubuntu
sudo -H -u mt-canvus-server /opt/mt-canvus-server/bin/mt-canvus-server --backup

# Windows (as Administrator)
"C:\Program Files\MT Canvus Server\bin\mt-canvus-server" --backup

Note the backup path. Default locations:

  • Ubuntu: /var/lib/mt-canvus-server/backups/<timestamp>_canvus_backup/
  • Windows: C:\ProgramData\MultiTaction\canvus\backups\<timestamp>_canvus_backup\

The backup folder contains:

File/folder Contents
db_dump.sql PostgreSQL database dump
assets/ All canvas asset files
mt-canvus-backup-metadata.json Version and timestamp metadata

Step 2: Note your configuration and copy certificates

Open your current mt-canvus-server.ini and note:

  • system/external-url
  • Any custom SSL certificate paths
  • Any custom authentication settings

If you are using custom TLS certificates, copy them to a safe location now, before stopping the bare-metal server:

# Ubuntu example
sudo cp /path/to/server.cert.pem ~/canvus-migration/server.cert.pem
sudo cp /path/to/server.key.pem  ~/canvus-migration/server.key.pem
sudo cp /path/to/server.chain.pem ~/canvus-migration/server.chain.pem

You will copy these into /canvus-data/certs/ in Step 6.

Step 3: Install Podman

Follow the container installation guide for your target OS and complete the Install Podman step only:

Step 4: Download and configure podman-compose.yml

Download the compose file and configure it with your existing settings before starting any containers:

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

Edit the file and set at minimum:

environment:
  CANVUS_EXTERNAL_URL: https://your-existing-server-url
  CANVUS_ADMIN_EMAIL: your-admin@example.com
  POSTGRES_PASSWORD: your-chosen-db-password

Set CANVUS_EXTERNAL_URL to match the system/external-url value you noted in Step 2. See configuration for all available options.

Step 5: Initialise the data directory structure

Start the stack once to create the /canvus-data/ subdirectory structure, then stop it:

sudo mkdir -p /canvus-data
sudo podman-compose up -d
# Wait ~60 seconds for first-time initialisation
sudo podman-compose down

Step 6: Restore the backup

Copy the entire backup folder into the container data directory, then use the Canvus server binary to restore both the database and assets in one operation:

# Copy the backup folder into the mapped volume
sudo cp -r /path/to/<backup-name> /canvus-data/backups/

# Start all containers
sudo podman-compose up -d

# Run the restore — Canvus handles restoring both assets and database
sudo podman exec canvus-combined mt-canvus-server --restore --backup-path /canvus-data/backups/<backup-name>

Warning

Do not log in or make any changes between starting the containers and the restore completing. The server is briefly accessible but contains empty initialisation data that will be replaced by the restore.

Step 7: Copy TLS certificates (if applicable)

If you were using custom TLS certificates, copy them into the container data directory:

sudo cp ~/canvus-migration/server.cert.pem  /canvus-data/certs/server.cert.pem
sudo cp ~/canvus-migration/server.key.pem   /canvus-data/certs/server.key.pem
sudo cp ~/canvus-migration/server.chain.pem /canvus-data/certs/server.chain.pem

Then reference the paths in /canvus-data/config/mt-canvus-server.ini or via environment variables in podman-compose.yml.

Step 8: Start the containerised server

sudo podman-compose up -d

Step 9: Verify

  1. Open https://your-server in a browser
  2. Log in with your administrator account
  3. Confirm canvases and users are present
  4. Check logs: sudo podman-compose logs -f canvus-combined

Step 10: Decommission the bare-metal installation

Once you have verified the container deployment is working correctly, stop and remove the bare-metal services:

# Ubuntu — stop services
sudo systemctl stop mt-canvus-server mt-canvus-dashboard
sudo systemctl disable mt-canvus-server mt-canvus-dashboard

Keep the original backup files until you are satisfied the migration is complete.