Server configuration

See also: Client configuration file.

Containerised Canvus server is configured primarily through environment variables in podman-compose.yml. This is the recommended approach — no file editing inside containers required.

Advanced users can also use the mt-canvus-server.ini configuration file by placing it at /canvus-data/config/mt-canvus-server.ini.

Environment variables

Edit podman-compose.yml and set variables under the canvus service's environment: block.

After changing any variable, restart the containers:

sudo podman-compose down
sudo podman-compose up -d

Required variables

Variable	Description	Example
CANVUS_EXTERNAL_URL	Public URL clients use to reach the server	https://canvus.example.com
CANVUS_ADMIN_EMAIL	Email address for the initial admin account	admin@yourcompany.com
CANVUS_ADMIN_PASSWORD	Password for the initial admin account	YourSecurePassword123!
POSTGRES_PASSWORD	Database password (must match postgres service)	a-strong-database-password

Note

CANVUS_ADMIN_EMAIL and CANVUS_ADMIN_PASSWORD are only used on first startup to create the initial admin account. Changing them after first startup has no effect.

Optional variables

Variable	Description	Default
CANVUS_LICENSE_KEY	License activation key (auto-activates on startup)	empty
CANVUS_HTTPS_PORT	HTTPS port inside the container	443

Example podman-compose.yml environment block

services:
  canvus:
    environment:
      CANVUS_EXTERNAL_URL: https://canvus.example.com
      CANVUS_ADMIN_EMAIL: admin@yourcompany.com
      CANVUS_ADMIN_PASSWORD: YourSecurePassword123!
      POSTGRES_PASSWORD: a-strong-database-password
      # CANVUS_LICENSE_KEY: XXXX-XXXX-XXXX-XXXX
  postgres:
    environment:
      POSTGRES_PASSWORD: a-strong-database-password

About mt-canvus-server.ini

There are two versions of mt-canvus-server.ini on each Canvus server:

• An example version is provided for reference purposes only. It contains all configuration settings currently supported by the Canvus server. When you update the Canvus server, the existing example version is overwritten by a new example version.
• A working version of mt-canvus-server.ini is used to configure Canvus server operations. The working version is retained if you update Canvus server. After updating, you will need to manually add any new settings to the existing working version of mt-canvus-server.ini.

Note

When you configure the Canvus server, always edit the working version of the configuration file.

See server-config-file for default locations of the configuration file.

Specify external URL

For Canvus server to display correct links to shared canvases, it needs to know the URL under which it is reachable by your users. For example, https://canvus.example.com.

[system]
; URL on which Canvus will be reachable. If empty, will be set to use a
; detected hostname and system/port with scheme set to HTTPS if ssl/enabled is
; true (otherwise HTTP).
; DEFAULT: empty
; external-url=

Specify database

You must provide the server with details about the database that you set up during server-install.

[sql]
; Settings for PostgreSQL data storage

; PSQL server port to use
; DEFAULT: 5432
; port=5432

; Name of the database to use
; DEFAULT: empty
; databasename=

; Set the username for DB login.
; DEFAULT: empty
; username=

; Set the password for DB login.
; DEFAULT: empty
; password=

Note

Canvus server must be restarted for these changes to take effect.

Define accepted connections

Canvus server uses a single port to listen for connections. It accepts Canvus clients using proprietary TCP/SSL protocol and web browsers accessing the web UI using HTTP(S). The arriving traffic is multiplexed based on protocol.

Canvus can optionally redirect HTTP traffic from port 80 to the port it listens SSL/HTTPS connections for.

If you enable encrypted SSL connections, you may also want to server-configuration-certificates.

; The address where the server will listen for the connections
; DEFAULT: 0.0.0.0 (all available networks)
; address=0.0.0.0

; Port where the server will listen for the connections
; DEFAULT: 80 for TCP protocol
; DEFAULT: 443 for SSL protocol (if system/ssl-enabled is true)
; port=443

; Enable encrypted HTTPS or TLS connections to the server. If disabled, only
; unencrypted HTTP or TCP connections are supported.
; DEFAULT: true
; ssl-enabled=true

; If enabled, the server listens to HTTP connections on port 80 and redirects
; them to the SSL port. This is only used if system/ssl-enabled is true and
; system/port is different from 80.
; DEFAULT: true
; http-redirect-enabled=true

Tip

Due to security, we recommend only using encrypted SSL connections.

Note

Canvus server must be restarted for these changes to take effect.

Setup certificates for encrypted connections

If you want to encrypt connections between Canvus clients and the server, or between browsers and the Canvus dashboard, you need a digital certificate and specify its location on the Canvus server.

Note

All files in the [[certificates]]{.title-ref} block should be X.509 certificates in .pem format.

[certificates]
; SSL certificate settings, shared between Canvus Connect server and the
; web UI. If all fields in this sections are left empty but SSL is enabled, a
; new self-signed certificate is created automatically.

; Certificate file name (.pem). This is the digital certificate issued by
; your Certificate Authority (CA). Make sure the certificate common name
; matches the domain name in system/external-url.
; DEFAULT: empty
; certificate-file=

; Certificate private key file name (.pem).
; DEFAULT: empty
; certificate-key-file=

; Certificate chain file name (.pem). This is the intermediate certificate
; issued by your CA.
; DEFAULT: empty
; certificate-chain-file=

Tip

If you leave these values empty but set system/ssl-enabled to true, Canvus will automatically generate self-signed certificates for you during startup and use them automatically.

The automatically generated certificates are placed in the following locations:

• Windows: %PROGRAMDATA%\MultiTaction\canvus\server\certificates
• Ubuntu: /etc/MultiTaction/canvus/server/certificates

Note

Canvus server must be restarted for these changes to take effect.

However, if you are later renewing existing certificate files on disk (e.g. Let's Encrypt), you can run mt-canvus-server --reload-certs to notify the server to reload the certificates and avoid having to restart it.

Define authentication methods

Canvus server supports multiple authentication methods for users. You can also configure which authentication methods can be used to sign up.

Tip

You can configure authentication methods also from the web UI.

[authentication]
; Enables authentication using email and password
; DEFAULT: true
; password-enabled=true

; Enables creation new local accounts
; Applies only if password authentication enabled
; DEFAULT: true
; password-sign-up-enabled=true

; Enables authentication using SAML
; DEFAULT: false
; saml-enabled=false

; Enables creating new accounts using SAML authentication
; Applies only if SAML authentication is enabled
; DEFAULT: true
; saml-sign-up-enabled=true

; Enables QR code authentication
; DEFAULT: true
; qr-code-enabled=true

; Comma separated list of domains allowed for creating new accounts (both SAML and local)
; Wildcards are allowed in the domain names
; Example: sign-up-allow-list=multitaction.com,gmail.com,*.gov
; DEFAULT: *
; sign-up-allow-list=*

; When enabled, any user signing up and creating an account will have to be approved
; by an administrator before they can sign in
; DEFAULT: false
; require-admin-approval=false

Password policy

Local-account passwords, including the initial admin password set via CANVUS_ADMIN_PASSWORD, are checked against a configurable complexity policy. By default, only a minimum length is enforced --- a mix of letters, numbers, and symbols is not required unless you configure it:

[password-security]
; The minimum number of characters passwords must have.
; Set to 0 or empty for no limit.
; DEFAULT: 8
; min-length=8

; The minimum number of lowercase characters a password must have.
; DEFAULT: 0
; min-lowercase=0

; The minimum number of uppercase characters a password must have.
; DEFAULT: 0
; min-uppercase=0

; The minimum number of numeric characters a password must have.
; DEFAULT: 0
; min-numeric=0

; The minimum number of symbol characters, for example !@#$%^&*, a
; password must have.
; DEFAULT: 0
; min-symbol=0

If you want the initial admin password (or any local password) to be required to contain letters, numbers, and symbols, set min-lowercase, min-uppercase, min-numeric, and min-symbol to at least 1 before first startup.

Configure SAML authentication

Canvus server can be configured to act as a SAML 2.0 Service Provider (SP). This allows Canvus to consume assertations from a SAML Identity Provider (IdP) to authenticate users.

You must first configure SAML 2.0 support in Canvus and then register Canvus server in your SAML IdP.

Tip

You can configure SAML from the web UI.

[saml]
; Override for the SAML Assertion Consumer Service URL.
; When empty, the ACS URL is derived from external-url + /users/login/saml/callback.
; Set this when using a load balancer or reverse proxy where the ACS URL differs
; from external-url. When set, this value is used in the IdP metadata, SAML
; responses, and the web-proxy configuration. The key is read-only over the REST API.
; DEFAULT: empty
; acs-url=

; SP Entity ID
; DEFAULT: canvus
; sp-entity-id=canvus

; IDP target URL
; DEFAULT: empty
; idp-target-url=

; IDP Entity ID
; DEFAULT: empty
; idp-entity-id=

; IDP X509 certificate SHA256 fingerprint
; IDP certificate is supposed to be included in SAML response
; Example: 2C:16:23:31:0B:39:B7:0F:EE:54:4F:ED:A3:92:20:FD:BA:24:24:33:8F:A1:80:CE:9E:C5:97:83:2A:D5:B0:DE
; DEFAULT: empty
; Ignored when idp-cert-file= is set.
; idp-cert-fingerprint=

; Path to the IdP certificate file in PEM format.
; Use this instead of idp-cert-fingerprint when the IdP signs SAML responses but
; omits <KeyInfo> from the signature (spec-permitted but incompatible with
; fingerprint-based validation), or when you want a stable, file-based trust anchor.
; When set, the server uses the cert at this path directly as the SAML trust anchor
; and idp-cert-fingerprint is ignored. The path is interpreted inside the container
; for containerised deployments — mount the file into the container and reference
; the container-internal path. See the SAML IdP Certificate File guide for setup.
; DEFAULT: empty (uses idp-cert-fingerprint for verification)
; idp-cert-file=

; NameID format
; Should be one of the values listed in http://docs.oasis-open.org/security/saml/v2.0/saml-core-2.0-os.pdf §8.3
; DEFAULT: urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
; name-id-format=urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

Codice folders

Canvus allows content to be stored in special folders associated with Codice markers. These folders are called Codice folders.

This feature is always enabled on the Canvus server. No configuration steps are required to enable it. Some behavior of the feature can be controlled by modifying settings in the following settings.

Enforce Codice folder passwords

Codice folders can be protected by a password that must be entered before the contents of the folder can be accessed by a user. The password can be made mandatory by adjusting the following setting:

[system]

; Set to true if all newly-created Codice folders must be protected by a
; password.
; DEFAULT: false
; enforce-codice-folder-password=false
; (The legacy key name "enforce-personal-folder-password" is accepted as a deprecated alias.)

Note

This setting has no effect on any Codice folders on the server that were created before the setting was enabled.

Enforce Codice folder registration

A Codice folder can be either anonymous or registered. Anonymous Codice folders are only linked with a specific Codice card. Registered Codice folder has additionally the user's name and email address associated with it.

To disallow anonymous Codice folders, the registration can be made mandatory by adjusting the following setting:

[system]

; Set to true if all newly-created Codice folders must be registered with a
; valid name and email address. If false, Codice folders can be anonymous
; and just attached to a Codice marker.
; DEFAULT: false
; enforce-codice-folder-registration=false
; (The legacy key name "enforce-personal-folder-registration" is accepted as a deprecated alias.)

Note

This setting has no effect on any Codice folders on the server that were created before the setting was enabled.

Info

• client-personal-folder-cards in the client installation manual.
• codice-cards in the user manual.

Configure WebRTC video streaming

Coming soon

WebRTC video streaming is not yet feature-complete and is disabled by default in 26.4.0. The canvus-media service ships commented out of the default podman-compose.yml, and [webrtc] enabled defaults to false. The rest of this section describes the design so operators can recognize the setting and enable it once the feature ships; do not enable it in production yet.

When enabled, the Canvus server does not route media itself — it acts as a signaling relay between desktop clients and a separate canvus-media service (a mediasoup Selective Forwarding Unit). Media (RTP/UDP) flows directly between clients and canvus-media; only signaling messages traverse the server.

The server identifies itself to the canvus-media SFU as server-relay; this is hardcoded and not configurable.

[webrtc]
; Enable WebRTC video streaming. When enabled, the server relays WebRTC
; signaling messages between desktop clients and the canvus-media service.
; Requires a running canvus-media service.
;
; COMING SOON: WebRTC video streaming is not yet feature-complete. Leave this
; off until the feature ships.
; DEFAULT: false
enabled=false

; URL of the canvus-media WebSocket signaling endpoint. The server connects
; to this URL to relay signaling between clients and the SFU.
; In the standard compose deployment this resolves to the canvus-media
; container via the internal Podman/Docker network.
; CONTAINER DEFAULT: ws://canvus-media:4443/ws?peerId=server-relay
; media-service-url=ws://canvus-media:4443/ws?peerId=server-relay

Note

In the containerized deployment, these values are driven by the environment variables CANVUS_WEBRTC_ENABLED and CANVUS_WEBRTC_MEDIA_URL set in podman-compose.yml. Both the CANVUS_WEBRTC_* env vars and the canvus-media service itself are commented out of the shipped compose file today. To try WebRTC ahead of general availability, uncomment the canvus-media service block and the two CANVUS_WEBRTC_* env vars, then set CANVUS_WEBRTC_ENABLED=true and restart the canvus-combined container.

SFU behavior (operator-facing summary)

Operators will not configure mediasoup directly — the SFU behavior below is baked into canvus-media and described only so the design is documented ahead of release:

• When a client publishes a stream, canvus-media broadcasts a producer-available event to every other peer in the same canvas room. When the stream ends it broadcasts producer-closed.
• Clients joining a canvas that already has active streams receive a snapshot of current producers in the join-room reply, so they do not need to wait for new producer events.
• A client that reconnects with the same peerId performs an idempotent rejoin — old producers are cleaned up server-side before the new session is registered, so transient network drops do not leave stale streams.

The signaling WebSocket between the Canvus server and canvus-media uses the reserved peer ID server-relay. Client peer IDs are allocated per-session by the desktop client and are not operator-configurable.

Configure the reverse proxy / web-client serving

No Node.js web-proxy in 26.4.0

Earlier releases fronted the dashboard with a separate Node.js web-proxy process reachable at dashboard-url. In the combined container and the Windows MSI install, that process is gone. An in-process Go gateway (mt-network-frontend, built into the C++ server binary) now serves the web-client SPA and answers /auth and /api/dashboard directly — there is nothing listening on a separate port to point dashboard-url at, and leaving dashboard-url unset does not break the UI.

[reverse-proxy]
; URL where an external web-proxy gateway is running. When set, the server
; forwards all non-API web traffic here. Left unset for the combined
; container: the in-process Go gateway (mt-network-frontend) serves the
; SPA + auth directly (see web-client-path below), so no separate web-proxy
; process runs.
; dashboard-url=

; Path to a directory holding pre-built web-client static files. When set,
; the in-process Go gateway serves these directly via FileServer + SPA
; fallback to index.html, and answers /auth and /api/dashboard in-process,
; bypassing dashboard-url entirely.
; CONTAINER DEFAULT: /opt/canvus/web-client/dist
web-client-path=/opt/canvus/web-client/dist

The gateway also introduces a WebSocket handshake requirement for clients. This is not a configuration knob — it is documented here so operators inspecting logs recognize the traffic:

• After opening a WebSocket through the gateway, the client must send a {"action":"join","canvasId":"...","token":"..."} message before any further traffic is accepted.
• The gateway rejects WebSockets that do not complete this handshake. If you see 400 Bad Request or immediate close frames on the WebSocket logs, a client or reverse-proxy in front of Canvus is likely stripping the handshake payload.

Web-client session secret

The in-process Go gateway signs browser session cookies with a secret value. On first start in 26.4.0, the container entrypoint:

1. Checks whether SESSION_SECRET is set in the container environment.
2. If not, reads /canvus-data/config/.session-secret if it exists (persisted across restarts via the /canvus-data/config bind mount).
3. Otherwise, generates a new 64-character hex secret with openssl rand -hex 32, writes it to /canvus-data/config/.session-secret with mode 600 owned by canvus:canvus, and uses that value.

Treat .session-secret as a secret

/canvus-data/config/.session-secret signs every browser session cookie. Anyone with the file contents can forge valid sessions. You must:

• Include it in your server backups (so sessions survive a restore).
• Keep it out of version control, chat transcripts, and screenshots.
• Protect the /canvus-data/config directory with standard filesystem permissions.

Rotating the session secret

To invalidate all existing web-client sessions (for example, after a suspected leak or a departing admin):

1. sudo rm /canvus-data/config/.session-secret
2. sudo podman-compose -f deploy/podman-compose.yml restart canvus
3. The entrypoint will generate a fresh secret on startup. All users will be forced to sign in again.

Advanced configuration settings

The Canvus server configuration file contains additional settings not documented in this manual. These settings are used to configure advanced Canvus server operations. You do not need to change these settings from their default values unless instructed to do so by MultiTaction support staff.