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 using the mtcs-migrate tool.

Warning

Migration is a one-way process. After migrating to containers, do not attempt to restore the exported bundle back onto a bare-metal installation. Keep the original bare-metal install and its backup files intact until you have verified the containerised deployment.

About mtcs-migrate

mtcs-migrate is a single cross-platform Go binary that moves a legacy mt-canvus-server installation onto the containerised canvus-server stack. It is distributed as:

  • A Linux .deb package (installs to /usr/bin/mtcs-migrate)
  • A signed Windows .exe

The tool operates in two phases:

  • Export — reads the legacy install and writes a self-contained bundle directory (config, assets, uploads, thumbnails, licenses, certs, and a PostgreSQL dump).
  • Import — reads the bundle and writes it into the /canvus-data/ layout used by the containerised server.

Safety guarantee: no-touch source

mtcs-migrate export is strictly read-only against the legacy install. The tool never modifies the source installation, so rollback is simply "do not run import" or "stop the new containers and start the legacy service again." The legacy data remains untouched until the operator decommissions it manually in the final step of this guide.

Transport modes

Choose the transport that matches your deployment:

  • same-host — the legacy install and the new container run on the same machine. Use mtcs-migrate run to chain export and import into a single command.
  • host-to-host — legacy and target are on two different machines sharing a network path (NFS, SMB, or a directory you rsync between them). Run export on the legacy host, import on the new host.
  • staged offline — the legacy machine will be wiped and reinstalled. Write the bundle to external storage (USB, external SSD), physically move it to the target, then import.

CLI surface

mtcs-migrate export --source <legacy-install-path> --bundle <output-dir> [flags]
mtcs-migrate import --bundle <bundle-dir> --target <canvus-data-path> [flags]
mtcs-migrate run    --source <legacy-install-path> --target <canvus-data-path> [flags]
mtcs-migrate version
mtcs-migrate help

Common flags:

  • --dry-run — validates every step and logs what would happen without writing anything. Available on both export and import.
  • --keep-bundle — retains the temporary bundle directory after run finishes (useful for debugging).
  • --force — allows import to overwrite a non-empty target /canvus-data/postgres/ directory. Without this, import refuses to run against a partially-populated target.
  • --stop-service — requests that the legacy service be stopped before export (off by default; operator's choice).

Before you begin

  • Ensure the target host meets the container system requirements.
  • Ensure you have enough free disk space on the target for the full data set — at minimum, 1.1x the size of the legacy /var/lib/mt-canvus-server/ (or Windows equivalent).
  • Schedule a maintenance window. The legacy server should be stopped or placed in a read-only state during export to guarantee a consistent snapshot.
  • Install the container runtime and pull the canvus-server images on the target host, but do not start the stack yet. See Install on Linux or Install on Windows.
  • Note any custom configuration you will need to re-apply (external URL, SSL certificates, SMTP, authentication). The mtcs-migrate tool carries the legacy mt-canvus-server.ini across in the bundle, but the containerised server reads most values from environment variables set in podman-compose.yml.

PostgreSQL version bridging

The containerised server runs PostgreSQL 15. Legacy installs may be on PG 12, 13, 14, or 15. mtcs-migrate handles the bridge automatically:

  • At export, the tool invokes the legacy install's own pg_dump binary to produce a custom-format dump compatible with PG 15 pg_restore. It does not ship its own pg_dump.
  • At import, the tool restores into the running canvus-postgres container.

PG 12 through PG 15 sources are supported in v1. If your legacy install uses an older PostgreSQL version, mtcs-migrate will refuse with a clear error. Contact MultiTaction support for guidance.

Step 1: Install mtcs-migrate

Linux (source host)

Download the .deb from the MultiTaction downloads portal and install:

sudo apt install ./mtcs-migrate_<version>_amd64.deb
mtcs-migrate version

Windows (source host)

Download the signed mtcs-migrate.exe and place it somewhere on PATH, or invoke it by full path. Run from an elevated PowerShell:

& "C:\Tools\mtcs-migrate.exe" version

Target host (host-to-host or staged offline)

Install mtcs-migrate on the target host too. The same binary handles both export and import.

Step 2: Put the legacy server in maintenance

Stop the server binary (or confirm it is idle and not accepting new connections) so pg_dump sees a consistent snapshot.

Ubuntu:

sudo systemctl stop mt-canvus-server mt-canvus-dashboard

Windows (as Administrator):

Stop-Service "MT Canvus Server"
Stop-Service "MT Canvus Dashboard"

Alternatively, pass --stop-service to mtcs-migrate export and the tool will stop the service for you using systemctl (Linux) or the Service Control Manager (Windows).

Step 3: Export the bundle

Same-host migration

Combine export and import in one command:

sudo mkdir -p /canvus-data
sudo mtcs-migrate run \
  --source /var/lib/mt-canvus-server \
  --target /canvus-data

Skip ahead to Step 5: Start the containerised server.

Host-to-host or staged offline migration

Run export on the legacy host, writing to shared storage or external media:

Linux:

sudo mtcs-migrate export \
  --source /var/lib/mt-canvus-server \
  --bundle /mnt/migration/canvus-bundle

Windows:

& "C:\Tools\mtcs-migrate.exe" export `
  --source "C:\ProgramData\MultiTaction\canvus" `
  --bundle "E:\canvus-bundle"

export validates the source, invokes the legacy pg_dump, copies assets / uploads / thumbnails / certs / licenses / config into the bundle directory, writes a manifest.json, and computes a checksums.sha256 file covering every file in the bundle.

Expected output: "Export complete" and exit code 0. Verify the bundle contains manifest.json, postgres/dump.sql, and the expected asset count.

Step 4: Import the bundle on the target

Prepare the target data directory:

sudo mkdir -p /canvus-data

If using staged offline transport, mount the external media on the target host and ensure the bundle directory is readable.

Run import:

sudo mtcs-migrate import \
  --bundle /mnt/migration/canvus-bundle \
  --target /canvus-data

import performs pre-flight checks (manifest well-formed, checksums match, target paths writable, enough disk space, target PostgreSQL empty) before touching anything. If you want to see what would happen without writing:

sudo mtcs-migrate import \
  --bundle /mnt/migration/canvus-bundle \
  --target /canvus-data \
  --dry-run

The import phase starts the canvus-postgres container (but not the rest of the stack), runs pg_restore from the bundle, copies assets and uploads into /canvus-data/, and writes an overlay file that the container entrypoint picks up on first boot.

Expected output: "Import complete. Run podman-compose up -d to start the stack."

Step 5: Start the containerised server

Change into the directory containing your podman-compose.yml and start the stack:

cd /opt/canvus-server
sudo podman-compose up -d

Follow the logs until the server reports ready:

sudo podman-compose logs -f canvus-combined

Step 6: Re-apply operator configuration

The bundle carries the legacy mt-canvus-server.ini inside config/, but the containerised server sources most values from environment variables in podman-compose.yml. Review and re-apply any of the following that applied to your legacy install:

  • CANVUS_EXTERNAL_URL — must match the URL clients use to reach the server.
  • Custom SSL certificate paths — copy certs into /canvus-data/certs/ and set the matching env vars, or let mtcs-migrate carry them over from the bundle.
  • SMTP settings, authentication providers, DRM license keys.

See Configuration file for the full reference and the env-var equivalents.

Step 7: Verify

  1. Open https://your-server in a browser.
  2. Log in with an existing administrator account from the legacy install.
  3. Confirm canvases, folders, users, and groups are present.
  4. Open a canvas and confirm assets (images, videos, PDFs) render.
  5. Check container logs for warnings: sudo podman-compose logs canvus-combined | grep -i warn.

If you spot missing data, keep the legacy install intact and contact MultiTaction support before decommissioning — the original bundle directory and the legacy install together are enough to re-run the migration.

Step 8: Decommission the bare-metal installation

Once you have verified the containerised deployment end-to-end, stop and disable the legacy services:

Ubuntu:

sudo systemctl stop mt-canvus-server mt-canvus-dashboard
sudo systemctl disable mt-canvus-server mt-canvus-dashboard

Windows (as Administrator):

Set-Service "MT Canvus Server" -StartupType Disabled
Set-Service "MT Canvus Dashboard" -StartupType Disabled
Stop-Service "MT Canvus Server"
Stop-Service "MT Canvus Dashboard"

Retain the original backup files and the exported bundle until you are satisfied the migration is complete — typically one full backup cycle after cutover.

Rollback

Because mtcs-migrate export is read-only against the source, rollback is straightforward:

  1. Stop the containerised stack: sudo podman-compose down.
  2. Start the legacy services back up (systemctl start / Start-Service).
  3. Point clients at the legacy URL again (if you changed DNS).

The legacy install has not been modified, so no restore is required. If you want to free the target disk, delete /canvus-data/ after confirming rollback.

Troubleshooting

Export refuses with "unsupported PostgreSQL version"

Your legacy install runs a PostgreSQL version outside the supported bridge matrix (PG 12 – PG 15). Upgrade the legacy PostgreSQL in place to PG 12 or newer before running export, or contact MultiTaction support.

Import refuses with "target postgres non-empty"

Something already wrote into /canvus-data/postgres/. Either delete the directory (if this is a fresh target) and re-run, or pass --force to overwrite. The tool will not destroy data without the explicit flag.

Checksum validation fails during import

The bundle was corrupted in transit. Re-run export, or re-copy the bundle from the source host if you still have it.

"Not implemented" or unexpected exit code

Capture stdout/stderr and the exact command line, and open a support ticket with MultiTaction. Include the output of mtcs-migrate version and the legacy install's mt-canvus-server --version.