Skip to content

macOS

Canvus Server 26.4.0 is Linux-only on the server side --- there is no native macOS server binary. On macOS hosts the three Canvus images (combined, postgres, media) run inside a Linux VM managed by Podman Machine (or Docker Desktop).

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:

  1. Launch Podman Desktop.
  2. Click Initialize and Start to create the Podman Machine.
  3. 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.

Login to the container registry

podman login docker.multitaction.com -u canvus-deploy -p gldt-synTX_NnF8LcmnktR1xK

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 three services: canvus (container canvus-combined), postgres (container canvus-postgres), and canvus-media. The media service exposes UDP 40000-40100 for WebRTC. 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

All three containers (canvus-combined, canvus-postgres, canvus-media) should be running. Open https://localhost --- the request is served by the web-proxy gateway inside canvus-combined, which serves the unified React web-client directly. Accept the self-signed certificate warning and login.

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

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-media
podman-compose logs -f canvus-postgres

# 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.