Windows

This page describes running the Canvus Server Linux containers on Windows, inside a Linux VM managed by Podman Desktop (WSL2 backend) or Docker Desktop. For installation without containers, see Windows standalone installation.

Note

For production, deploy on a Linux host. Podman Desktop on Windows is supported for development, evaluation, and test deployments, but WSL2 networking (especially UDP for WebRTC) and resource limits are less predictable than a native Linux server. The Linux container install is the reference deployment.

Supported Windows versions: Windows 10/11 and Windows Server 2019/2022 (64-bit) with WSL2 enabled.

System requirements

RAM: 8 GB minimum (16 GB recommended) on the host. Allocate at least 4 GB to the WSL2 VM --- the combined container needs 4 GB minimum itself (see Linux page).
2 CPU cores minimum (4 recommended)
20 GB disk space minimum
WSL2 enabled (Podman Desktop handles this automatically on Windows 10/11)
Administrator access for installation

Install Podman Desktop

Download the Windows installer from podman-desktop.io/downloads.
Run the installer and follow the prompts.
Podman Desktop enables WSL2 and installs a Podman-optimized distribution automatically.
Launch Podman Desktop from the Start Menu and click Initialize and Start if prompted.

Verify in PowerShell:

podman --version
# Should show: podman version 4.x.x or higher

Install podman-compose

Podman Desktop does not include podman-compose. Choose one:

Option A: Built-in compose (Podman 4.0+, recommended)

podman compose version

If this works, use podman compose (with a space) in place of podman-compose for all commands on this page.

Option B: Install via Python

winget install Python.Python.3.11
# Close and reopen PowerShell to refresh PATH
pip install podman-compose

Docker Desktop alternative

The same images and compose file work with Docker Desktop. Docker Desktop requires a paid subscription for organizations with more than 250 employees or more than \$10M annual revenue. Podman Desktop avoids that licensing exposure, but if Docker Desktop is already approved in your environment, nothing prevents you from using it.

Allocate resources to WSL2

Create C:\Users\YourUsername\.wslconfig before you start the containers:

[wsl2]
memory=8GB
processors=4
swap=2GB
localhostForwarding=true

Apply with wsl --shutdown (WSL2 restarts on next use). Allocating less than 4 GB to WSL2 will cause canvus-combined to be OOM-killed.

Container registry access

Canvus Server images are hosted on the MultiTaction public container registry and pull anonymously --- no registry login is required.

Download the compose file

mkdir C:\canvus-server
cd C:\canvus-server

Invoke-WebRequest -Uri "https://canvus-downloads.multitaction.com/server/podman-compose.yml" -OutFile "podman-compose.yml"

Note

The 26.4.0 compose file deploys two services by default: canvus (container canvus-combined) and postgres (container canvus-postgres). A third service, canvus-media, ships commented out --- it only applies once you enable the coming-soon WebRTC feature, and then exposes UDP 40000-40100; make sure Windows Firewall allows those ports if you enable it and clients outside the host need video streaming. See the Linux page for the full architecture.

Configure the deployment

Edit podman-compose.yml in Notepad or your preferred text editor. At minimum, change these 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

And match the same POSTGRES_PASSWORD in the postgres service.

Note

The compose file uses Linux-style paths (/canvus-data/...). Podman Desktop creates these inside the WSL2 VM automatically. Do not change these to Windows paths.

Start services

cd C:\canvus-server
podman compose -f podman-compose.yml up -d

Verify

podman compose -f podman-compose.yml ps

Both containers (canvus-combined, canvus-postgres) should be running (plus canvus-media if you have enabled WebRTC). Open https://localhost in your browser --- the request is served by the in-process gateway inside canvus-combined, which serves the unified React web-client directly. Accept the self-signed certificate warning and login with the admin credentials you set above.

Backup, restore, and migration

For routine backups, see Server backup and restore. To move a 3.x or 26.x standalone server into containers, use the following procedure. Run the container commands in PowerShell, from C:\canvus-server as used above.

Before you start

Use a container release that includes PostgreSQL 18 and the same or a newer Canvus Server version than your standalone installation. See migration prerequisites.

1. Back up the standalone server

Ask users to finish editing. On the old server, open Services (services.msc) and stop the Canvus Server service, leaving its PostgreSQL service running. Canvus saves automatically; there is no manual save step.

Run the existing server's backup command in PowerShell as Administrator, adjusting the installation path if necessary:

& "C:\Program Files\MT Canvus Server\bin\mt-canvus-server.exe" --backup

For a Linux source, use the Linux backup commands.

Wait for the backup to complete successfully and note the folder printed by the command. Copy the whole backup folder to a safe location outside the old installation, for example C:\CanvusMigration\backup-folder. It must include mt-canvus-backup-metadata.json, db_dump.sql and the backed-up assets.

Save mt-canvus-server.ini, the license file and any TLS certificate/key files separately in C:\CanvusMigration. These are not included in the Canvus backup; see file locations.

2. Remove the old installation if reusing the machine

If reusing the same Windows machine, uninstall the old Canvus Server and any legacy Canvus Dashboard through Programs and Features, then reboot. For 26.x, follow the standalone uninstall/reboot instructions, stopping before the reinstall step. Keep your backup and saved files; do not delete the old data folders as part of this move.

If moving to a different machine, leave the old installation intact and its Canvus service stopped.

3. Install and configure the containers

Follow the installation steps above through Start services and Verify. Do not add real content to the new server: restore replaces its existing Canvus data.

Then stop only Canvus, leaving its PostgreSQL container running:

cd C:\canvus-server
podman compose -f podman-compose.yml stop canvus

4. Copy the backup and saved files

On Windows, /canvus-data/ is inside the Podman VM, not on C:. Use podman cp to copy into the stopped container's mounted folders. The following creates a new backup folder named migration; adjust the source paths to your saved files:

podman cp "C:\CanvusMigration\backup-folder" canvus-combined:/var/lib/mt-canvus-server/backups/migration
podman cp "C:\CanvusMigration\mt-canvus-server.ini" canvus-combined:/etc/MultiTaction/canvus/mt-canvus-server.ini.standalone
podman cp "C:\CanvusMigration\license-file" canvus-combined:/var/lib/mt-canvus-server/MultiTaction/Licenses/

These files persist in the VM at /canvus-data/backups/migration/, /canvus-data/config/mt-canvus-server.ini.standalone and /canvus-data/licenses/ respectively. The backup metadata must be directly inside migration, not inside another nested backup folder.

Open \\wsl$\podman-machine-default\canvus-data\config\ in Explorer, as described under Data persistence. Use the saved .ini.standalone file as a reference to bring your site settings into the generated mt-canvus-server.ini. Keep the container's database settings and filesystem paths rather than replacing its INI wholesale. A license tied to the old machine may need reactivation.

If using your own TLS certificate/key, copy the saved files into canvus-combined:/etc/MultiTaction/canvus/server/certificates/ with podman cp, using the certificate filenames from the Linux instructions. These persist under /canvus-data/certs/ in the VM.

5. Restore the Canvus backup

Run the Linux server binary supplied by the image, not the Windows .exe, in a temporary container with the installed service's configuration and mounts:

podman compose -f podman-compose.yml run --rm --no-deps --entrypoint /opt/canvus/bin/mt-canvus-server canvus --restore --backup-path /var/lib/mt-canvus-server/backups/migration

--backup-path is the path inside the container, mapped from /canvus-data/backups/migration in the VM. Canvus restores the database and assets together. Wait for the command to finish successfully; if it reports an error or does not return, leave Canvus stopped and contact MultiTaction support with the output.

6. Restart and check

podman compose -f podman-compose.yml start canvus
podman compose -f podman-compose.yml ps

Sign in with an account from the old server and check your canvases, folders and media before reconnecting clients. When migrating from 3.x, update the clients to 26.x too. Keep the original backup until you have checked the new server.

Windows-specific notes

Data persistence

Container data lives inside the WSL2 VM at /canvus-data/. To access from Windows Explorer:

\\wsl$\podman-machine-default\canvus-data\

Firewall configuration

Windows Firewall may block incoming connections from other machines:

# Run as Administrator
New-NetFirewallRule -DisplayName "Canvus HTTPS" -Direction Inbound -Protocol TCP -LocalPort 443 -Action Allow
New-NetFirewallRule -DisplayName "Canvus HTTP" -Direction Inbound -Protocol TCP -LocalPort 80 -Action Allow
New-NetFirewallRule -DisplayName "Canvus WebRTC" -Direction Inbound -Protocol UDP -LocalPort 40000-40100 -Action Allow  # only needed if you have enabled WebRTC

Port conflicts

If ports 80/443 are already in use (IIS, Apache):

netstat -ano | findstr :443

Stop the conflicting service, or use unprivileged ports in podman-compose.yml (see the Linux page).

Management

cd C:\canvus-server

# Start / stop / restart
podman compose -f podman-compose.yml up -d
podman compose -f podman-compose.yml stop
podman compose -f podman-compose.yml restart

# View logs
podman compose -f podman-compose.yml logs -f canvus-combined
podman compose -f podman-compose.yml logs -f canvus-media
podman compose -f podman-compose.yml logs -f canvus-postgres

# Update to latest version
podman compose -f podman-compose.yml pull
podman compose -f podman-compose.yml down
podman compose -f podman-compose.yml up -d

Windows Server

For Windows Server Core (no GUI), enable WSL2 and follow the Linux guide from within a WSL2 Ubuntu session:

# Enable WSL2 (requires reboot)
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
Restart-Computer

# After reboot
wsl --set-default-version 2
wsl --install -d Ubuntu

Then follow the Linux container install from within the WSL2 Ubuntu session --- that is the canonical deployment guide; the Windows path above is a convenience wrapper only.

Troubleshooting

"Cannot connect to Podman":

podman machine stop
podman machine start

"WSL2 not found":

wsl --status
wsl --set-default-version 2

Container won't start:

podman logs canvus-combined
podman logs canvus-media
podman logs canvus-postgres

WebRTC video not working from external clients:

WSL2 port forwarding for UDP ranges can be unreliable. If clients cannot receive media, the first fallback is to move the deployment to a native Linux host. See Linux troubleshooting for the full WebRTC diagnostic flow.