Standalone Windows install

This guide installs Canvus Server natively on Windows Server as Windows Services, from a single signed MSI. No containers, no WSL2, no Docker. The MSI bundles everything the server needs and registers it as Windows Services that start on boot:

mt-canvus-server: the Canvus Server itself.
mt-canvus-postgres: a dedicated, bundled PostgreSQL instance, listening on localhost only.
the web client and the web/auth gateway, both served directly by the server process, with no separate Node.js runtime.

Which install do I want?

This is the standalone install: a native Windows Service install for a single Windows Server host. If you already run containers, see the Windows container install. Both are current, supported options --- see Choosing an installation method. To migrate an existing Canvus 3.4.x server, do the fresh install below first, then follow the migration steps at the end of this page.

System requirements

Windows Server 2019 or 2022, 64-bit (Desktop Experience or Server Core).
Administrator rights to run the installer.
4 GB RAM minimum (8 GB+ recommended) and 20 GB free disk.
Inbound TCP on the HTTPS port (443 by default) reachable by your Canvus clients. The installer opens a firewall rule for whichever port you configure.
A DNS name or static IP that clients use to reach the server. For production, a CA-issued TLS certificate whose name matches that host (see TLS certificate below); for initial bring-up the server's self-signed certificate is sufficient.

Client browsers need WebGL

The Canvus web client renders canvases with WebGL. Any modern desktop browser (Chrome, Edge, Firefox, Safari) on a machine with normal graphics works out of the box. On GPU-less environments (headless servers, some VDI or thin-client setups), WebGL may be disabled, in which case the canvas surface will not render even though the UI loads. This is a property of the viewing machine, not the server: open the web client from a normal GPU-capable desktop.

What gets installed where

Path	Contents
`%ProgramFiles%\MT Canvus Server\bin\`	`mt-canvus-server.exe`, dependency DLLs, the gateway
`%ProgramFiles%\MT Canvus Server\postgres\`	bundled PostgreSQL binaries
`%ProgramFiles%\MT Canvus Server\web-client\`	pre-built web client
`%ProgramData%\MultiTaction\canvus\mt-canvus-server.ini`	server configuration
`%ProgramData%\MultiTaction\canvus\postgres\`	PostgreSQL data directory
`%ProgramData%\MultiTaction\canvus\logs\`	server + installer logs

%ProgramData%\MultiTaction\canvus\ holds all persistent data and is preserved across uninstall and upgrade.

Option A: interactive install (wizard)

Double-click canvus-server_<version>_x64.msi.
Accept the license agreement.
On the Canvus Server Configuration page, enter:
- Public URL: the HTTPS URL clients use to reach this server, e.g. https://canvus.corp.example. Must match your TLS certificate name.
- HTTPS port: 443 (default).
- Administrator email / password: the first admin account. Required for a fresh install: if you leave these blank, no admin is created and no one can sign in (you would have to add one later with --create-admin, below). Leave blank only when migrating; the admin then comes from the restored backup.
Confirm the install location and click Install.
The installer initializes PostgreSQL, writes the configuration, opens the firewall, registers both services, creates the admin, and starts the server.

Option B: silent install (scripted / repeatable)

The same MSI installs unattended from an elevated PowerShell or cmd, the recommended path for repeatable enterprise deployment. Every wizard input is an MSI property:

msiexec /i canvus-server_<version>_x64.msi /qn /norestart `
  /l*v C:\canvus-install.log `
  CANVUS_EXTERNAL_URL=https://canvus.corp.example `
  CANVUS_HTTPS_PORT=443 `
  CANVUS_ADMIN_EMAIL=admin@corp.example `
  CANVUS_ADMIN_PASSWORD=<strong-password>

For a migration, omit the admin properties (the admin is restored from backup):

msiexec /i canvus-server_<version>_x64.msi /qn /norestart `
  /l*v C:\canvus-install.log `
  CANVUS_EXTERNAL_URL=https://canvus.corp.example

Property	Meaning	Default
`CANVUS_EXTERNAL_URL`	Public HTTPS URL clients connect to	`https://localhost`
`CANVUS_HTTPS_PORT`	HTTPS listen port	`443`
`CANVUS_ADMIN_EMAIL`	First admin account email (fresh install only)	(empty)
`CANVUS_ADMIN_PASSWORD`	First admin account password	(empty)

Non-default HTTPS port

If you set CANVUS_HTTPS_PORT to anything other than 443, include that port in CANVUS_EXTERNAL_URL (e.g. https://canvus.corp.example:8443) so the URL clients receive is reachable. The installer opens the firewall for whichever port you set.

A fresh silent install needs an admin account

On a fresh install the admin user is created only when CANVUS_ADMIN_EMAIL and CANVUS_ADMIN_PASSWORD are supplied. A /qn install without them leaves the server with no way to sign in. Either pass both properties, or create the admin afterward:

& "C:\Program Files\MT Canvus Server\bin\mt-canvus-server.exe" `
  --create-admin admin@corp.example "<strong-password>"

Post-install verification

# Both services should be Running (postgres first, then the server):
Get-Service mt-canvus-postgres, mt-canvus-server

# The installer's own log (each step is timestamped):
Get-Content "$env:ProgramData\MultiTaction\canvus\logs\installer.log"

# The server answers locally (curl -k skips the local/self-signed cert; HTTP
# redirects to HTTPS, so query HTTPS directly):
curl.exe -sk https://localhost/healthz

Then open https://<your-host>/ in a browser and sign in with the admin account.

TLS certificate

By default the server generates a self-signed certificate matching system/external-url on first start. Browsers and clients will warn until you install a CA-issued certificate; production deployments should supply their own.

Create a folder for the certificate material (e.g. %ProgramData%\MultiTaction\canvus\certs\), drop your certificate, key, and (optionally) chain into it, then point the [certificates] section of %ProgramData%\MultiTaction\canvus\mt-canvus-server.ini at them:

[certificates]
certificate-file=C:/ProgramData/MultiTaction/canvus/certs/server.cert.pem
certificate-key-file=C:/ProgramData/MultiTaction/canvus/certs/server.key.pem
; certificate-chain-file=C:/ProgramData/MultiTaction/canvus/certs/server.chain.pem

Use forward slashes in INI paths

The configuration file treats a backslash (\) as an escape character, so Windows paths must use forward slashes (C:/...). A backslash path makes the server fail to parse the file and refuse to start.

Then Restart-Service mt-canvus-server. The certificate's common name (or a Subject Alternative Name) must match the host in system/external-url: the DNS name or IP clients connect to, not the full URL.

SAML single sign-on (optional)

Canvus Server can authenticate users against your enterprise identity provider (Microsoft Entra ID, ADFS, Okta, and other SAML 2.0 IdPs). SSO is configured entirely in mt-canvus-server.ini, with no separate component to deploy.

1. Register Canvus as a SAML application with your IdP. Use these values:

IdP field	Value
Reply URL (Assertion Consumer Service)	`https://<your-host>/users/login/saml/callback`
Identifier (SP Entity ID)	a value you choose, e.g. `https://<your-host>`; must match `sp-entity-id` below
Name ID format	Email address (the assertion must carry the user's email as the Name ID)

Download the IdP's signing certificate (PEM) and note the IdP's Entity ID and sign-on URL.

2. Configure the server. Add to mt-canvus-server.ini:

[authentication]
saml-enabled=true
; Auto-create a Canvus user on first successful SSO login:
saml-sign-up-enabled=true

[saml]
sp-entity-id=https://<your-host>
idp-entity-id=<IdP Entity ID>
idp-target-url=<IdP sign-on URL>
idp-cert-file=C:/ProgramData/MultiTaction/canvus/certs/idp.pem

For Microsoft Entra ID, the IdP values are:

idp-entity-id → https://sts.windows.net/<tenant-id>/
idp-target-url → https://login.microsoftonline.com/<tenant-id>/saml2
idp-cert-file → the token-signing certificate downloaded from the Entra enterprise application

Name ID must be the user's email

Canvus identifies SSO users by an emailAddress-format Name ID, and the value must be the user's email address. In Entra the Unique User Identifier defaults to user.userprincipalname, which in many tenants is the email address. Where UPN and email differ, set the identifier to user.mail so Canvus receives a real email. With saml-sign-up-enabled=true, a matching Canvus account is created on the user's first login.

Then Restart-Service mt-canvus-server. Confirm the feature is on:

# Should report {"enabled":true}
curl.exe -sk https://localhost/auth/saml/enabled

That only proves SSO is enabled, not that the IdP round-trip works. Finish by opening https://<your-host>/ in a browser, choosing the SSO option the login page now shows, and completing a real sign-in. Use forward slashes for the idp-cert-file path, as with all INI paths.

License activation (required for client connections)

Canvus Server serves the web client and REST API immediately, but it will not accept Canvus desktop-client connections until a license is activated.

Activate with your MultiTaction activation key once the services are running:

& "C:\Program Files\MT Canvus Server\bin\mt-canvus-server.exe" --activate <ACTIVATION-KEY>
Restart-Service mt-canvus-server

--activate performs an online activation (the host must reach MultiTaction's licensing service). For an air-gapped host, generate an offline request:

& "C:\Program Files\MT Canvus Server\bin\mt-canvus-server.exe" --create-license-request <ACTIVATION-KEY>

Send the resulting request to MultiTaction and install the activated license they return, following their offline-activation instructions. The license is bound to the machine's Host ID, so run this on the final host.

Upgrading

Upgrade by uninstalling the current version and installing the new one. Do not upgrade in place.

Back up the server --- see Backup and restore.
Stop mt-canvus-server, then mt-canvus-postgres.
Uninstall the current version via Programs & Features, or silently with msiexec /x. This preserves %ProgramData%\MultiTaction\canvus\.
Reboot the server.
Install the new MSI.

%ProgramData%\MultiTaction\canvus\ (database, assets, configuration) survives the uninstall, so the new version finds the existing data. An existing .ini is not overwritten, so configuration properties passed on the install command line do not change a server that is already configured; edit the .ini directly to change settings.

See Updating a standalone deployment for the full procedure, including the additional step required when the bundled PostgreSQL major version changes.

Migrating from Canvus 3.4.x

The server binary and on-disk formats are compatible, so migration is a data copy rather than a special tool. The high-level shape is:

On the old server, stop Canvus and take a PostgreSQL dump of the Canvus database, plus a copy of the media-assets folder.
Do a fresh standalone install on the new Windows host (omit the admin properties; the admin comes from the backup).
Stop mt-canvus-server (leave mt-canvus-postgres running), restore the dump into the bundled PostgreSQL (which listens on localhost only), and copy the assets into %ProgramData%\MultiTaction\canvus\.
Restart-Service mt-canvus-server and verify.

Use the step-by-step runbook

For the exact commands — backing up the old server, uninstalling it, and restoring into 26.6.0 — follow the Migrate from 3.x runbook. The bundled PostgreSQL 18 restores backups from older PostgreSQL versions directly.

Uninstalling

# Via Programs & Features, or silently:
msiexec /x canvus-server_<version>_x64.msi /qn /l*v C:\canvus-uninstall.log

Uninstall removes both services, all binaries under %ProgramFiles%\MT Canvus Server, and the firewall rule. It preserves %ProgramData%\MultiTaction\canvus\ (database, assets, configuration, backups) so a later reinstall finds the data intact.

Do not delete the data folder

Deleting %ProgramData%\MultiTaction\canvus\ by hand destroys the database, assets, configuration and backups --- every canvas on the server, unrecoverable without a restored backup. Leave it in place unless you intend to erase the server's data permanently.

Troubleshooting

Install rolled back / mt-canvus-server not running: read %ProgramData%\MultiTaction\canvus\logs\installer.log and the verbose MSI log from /l*v. The most common cause is PostgreSQL failing to initialize; check the PostgreSQL log files under %ProgramData%\MultiTaction\canvus\postgres\ and the Windows Event Log (Application).
Server refuses to start after editing the INI: check for a backslash in a Windows path; INI paths must use forward slashes.
Clients cannot connect: confirm the inbound HTTPS port (443 by default, or your CANVUS_HTTPS_PORT) is open end to end and that system/external-url matches the certificate name and resolves to this host.
SSO rejected (saml_rejected): confirm the IdP sends an emailAddress Name ID, the Reply URL exactly matches https://<your-host>/users/login/saml/callback, and idp-cert-file is the IdP's current signing certificate.