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.

Automated migration is not yet available

mtcs-migrate, the tool intended to automate this move, is still under development. Its export, import, and run subcommands currently print "not implemented yet" and exit without doing anything --- there is no automated path from a bare-metal install to the containerised deployment today. Until it ships, treat this as a manual migration and contact MultiTaction support for guidance specific to your deployment.

This is one option, not a requirement

Moving to containers is a choice, not a prerequisite for staying current. A legacy installation can equally be replaced with a standalone install, which keeps the server as a native service and needs no container runtime. This guide covers the container route specifically.

What migration will look like

mtcs-migrate is planned as a single cross-platform Go binary that moves a legacy mt-canvus-server installation onto the containerised canvus-server stack, 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.

The command-line surface (export, import, run, version, help) already exists as a stub, but the underlying read/write logic has not been implemented. Do not rely on any specific flag surviving unchanged once the tool is finished --- this page will be rewritten with real steps and worked examples once mtcs-migrate ships.

Doing it manually today

Until mtcs-migrate is available, a manual migration follows the same shape as any other backup/restore move, using the server binary's own --backup / --restore commands:

  1. On the legacy install, take a backup with the legacy server binary (see Backup and restore).
  2. Copy the backup, plus your TLS certificates, license file, and any custom mt-canvus-server.ini settings you need to re-apply, to the target host.
  3. Install the containerised deployment on the target host (see Install on Linux or Install on Windows) but do not start it with real data yet.
  4. Restore the backup into the container per the containerised restore procedure in Backup and restore.
  5. Re-apply operator configuration --- external URL, SSL certificates, SMTP, authentication --- as environment variables in podman-compose.yml. See Configuration file for the env-var equivalents.

PostgreSQL version note

The container images are pinned to PostgreSQL 17.11. Both standalone installers (Linux and Windows) instead bundle PostgreSQL 18.6. These are different major versions, so a database dump moved between a container deployment and a standalone deployment crosses a major PostgreSQL version --- for example, restoring a container's backup (17.11) into a standalone install (18.6) is a cross-major-version restore, and so is the reverse. PostgreSQL dumps generally restore cleanly into a newer major version, but a newer dump is not guaranteed to load into an older one. If you are migrating between deployment types, or from a legacy install on an older PostgreSQL major version, consult MultiTaction support if you are unsure your source PostgreSQL version can restore cleanly into the target.

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 while you take the backup, 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 with real data yet.
  • Note any custom configuration you will need to re-apply (external URL, SSL certificates, SMTP, authentication).

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.

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 until you are satisfied the migration is complete — typically one full backup cycle after cutover.

Rollback

Because a manual migration only reads from the legacy install (via backup), 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 against it.

Troubleshooting

Contact MultiTaction support with the output of mt-canvus-server --version from both the legacy install and the containerised deployment, plus the container logs (sudo podman-compose logs canvus-combined).