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: Copy backup data into the container volume

The bare-metal backup maps directly onto the container data directory. Copy the assets across and restore the database dump:

# Copy canvas assets directly
sudo cp -r /path/to/backup/assets/. /canvus-data/assets/

# Start only the database container
sudo podman-compose up -d canvus-postgres

# Wait for postgres to be ready (~10 seconds), then restore the database
sudo podman exec -i canvus-postgres psql -U canvus canvus < /path/to/backup/db_dump.sql

# Stop the database container
sudo podman-compose stop

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.