macOS

This page describes running the Canvus Server Linux containers on macOS, inside a Linux VM managed by Podman Machine (or Docker Desktop). There is no native macOS server binary.

Note

For production, deploy on a Linux host. macOS is supported for development, evaluation, and demo deployments. On Apple Silicon the x86_64 images run via Rosetta 2 emulation, which works but adds overhead and is not recommended for customer-facing deployments. The Linux container install is the reference deployment.

Supported: macOS 12 (Monterey) or later, Apple Silicon or Intel.

System requirements

RAM: 8 GB minimum (16 GB recommended) on the host. Allocate at least 4 GB to the Podman Machine VM --- canvus-combined requires 4 GB itself (see Linux page).
2 CPU cores minimum (4 recommended)
20 GB disk space minimum

Note

Container images are built for x86_64 (amd64). On Apple Silicon, Podman runs them via Rosetta 2 emulation. This works but may have minor performance overhead. Use macOS for development/testing and Linux for production.

Install Podman Desktop

Option A: Homebrew (recommended)

brew install podman podman-compose podman-desktop

Option B: Download installer

Download from podman-desktop.io/downloads.

After installation:

Launch Podman Desktop.
Click Initialize and Start to create the Podman Machine.
Wait for initialization to complete.

Verify:

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

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 is recommended to avoid that licensing exposure, but if Docker Desktop is already approved in your environment, nothing prevents you from using it.

Allocate resources to the Podman Machine

Size the VM before you start the containers:

podman machine stop
podman machine set --cpus 4 --memory 8192 --disk-size 50
podman machine start

Allocating less than 4 GB of memory 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 ~/canvus-server && cd ~/canvus-server

curl -L -O https://canvus-downloads.multitaction.com/server/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. See the Linux page for the full architecture.

Configure the deployment

Edit podman-compose.yml. 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

Volume paths use Linux-style paths (/canvus-data/...), created inside the Podman Machine VM. Do not change these to macOS paths.

Start services

cd ~/canvus-server
podman-compose up -d

Verify

podman-compose ps

Both containers (canvus-combined, canvus-postgres) should be running (plus canvus-media if you have enabled WebRTC). Open https://localhost --- 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.

Backup, restore, and migration

For routine backups, see Server backup and restore. You can also restore a backup from a 3.x or 26.x standalone server into this container deployment. The standalone source runs on Linux or Windows; there is no native macOS server to back up or uninstall.

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

On the source machine, ask users to finish editing and stop the Canvus Server service, leaving PostgreSQL running. Then run the source server's existing backup command: use the Linux commands or the Windows command.

Wait for the backup to complete successfully. Transfer the whole backup folder to your Mac, for example ~/CanvusMigration/backup-folder. It must contain mt-canvus-backup-metadata.json, db_dump.sql and the backed-up assets. Also transfer your saved mt-canvus-server.ini, license file and TLS certificate/key files; these are not included in the backup. See file locations.

Keep the original installation intact on its source machine, with its Canvus service stopped.

2. Install and configure the containers

Follow the 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 ~/canvus-server
podman-compose stop canvus

3. Copy the backup and saved files

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

podman cp "$HOME/CanvusMigration/backup-folder" canvus-combined:/var/lib/mt-canvus-server/backups/migration
podman cp "$HOME/CanvusMigration/mt-canvus-server.ini" canvus-combined:/etc/MultiTaction/canvus/mt-canvus-server.ini.standalone
podman cp "$HOME/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.

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. To edit on your Mac, copy the generated file out, edit it, then copy it back while Canvus is stopped:

podman cp canvus-combined:/etc/MultiTaction/canvus/mt-canvus-server.ini "$HOME/CanvusMigration/mt-canvus-server.container.ini"

After editing ~/CanvusMigration/mt-canvus-server.container.ini:

podman cp "$HOME/CanvusMigration/mt-canvus-server.container.ini" canvus-combined:/etc/MultiTaction/canvus/mt-canvus-server.ini

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.

4. Restore the Canvus backup

Run the server binary supplied by the image in a temporary container with the installed service's configuration and mounts:

podman-compose 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.

5. Restart and check

podman-compose start canvus
podman-compose 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.

macOS-specific notes

Data persistence

Container data lives inside the Podman Machine VM. To access:

podman machine ssh
ls /canvus-data/

Port conflicts

lsof -i :443

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

WebRTC and UDP ports

WebRTC video streaming is disabled by default in 26.4.0 (see the Linux page). If you have enabled it and uncommented canvus-media, note that Podman Machine forwards the UDP 40000-40100 range to canvus-media, but macOS firewall rules or corporate VPN clients may interfere with UDP traffic. If WebRTC video does not work from external clients, the fastest fallback is to move the deployment to a native Linux host.

Management

cd ~/canvus-server

# Start / stop / restart
podman-compose up -d
podman-compose stop
podman-compose restart

# View logs
podman-compose logs -f canvus-combined
podman-compose logs -f canvus-postgres
# podman-compose logs -f canvus-media   # only if you have enabled WebRTC

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

Troubleshooting

"Cannot connect to Podman":

podman machine start

Slow performance on Apple Silicon:

The x86_64 images run via Rosetta 2 emulation. For production, use a Linux server.

Container won't start:

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

canvus-combined exits with OOM:

Increase Podman Machine memory (see Allocate resources to the Podman Machine above). Canvus 26.4.0 requires 4 GB minimum inside the container.