Configuration

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, you must 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

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

Canvus 26.4.0 adds real-time WebRTC video streaming. 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.

WebRTC is enabled by default in 26.4.0. In the containerized deployment, the canvus-media service runs alongside canvus-combined and canvus-postgres (see podman-compose.yml).

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.
; DEFAULT: true (26.4.0+)
; enabled=true

; 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.
; 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. The container entrypoint writes the resolved values into the working mt-canvus-server.ini. Edit the compose file (or the working INI) to change them, then restart the canvus-combined container.

Tip

To disable WebRTC entirely — for air-gapped sites, or deployments that do not need real-time video — set CANVUS_WEBRTC_ENABLED=false in podman-compose.yml. The canvus-media service can then be removed from the compose file.

SFU behaviour (operator-facing summary)

Operators do not configure mediasoup directly — the SFU behaviour below is baked into canvus-media and described only to help diagnose live sessions:

• 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 dashboard reverse proxy

Semantic change in 26.4.0

The meaning of [reverse-proxy] dashboard-url changed in 26.4.0. The setting name is the same, but the port it should point to has moved.

• Before 26.4.0: dashboard-url=http://localhost:5806 — pointed directly at the legacy Node.js dashboard.
• 26.4.0 and later: dashboard-url=http://localhost:5805 — points at the web-proxy gateway, which in turn proxies to the dashboard on :5806 and to the new web-client on the same port.

Operators upgrading from an older release must update this value, or the dashboard and web-client UI will be unreachable. In the containerized deployment the entrypoint rewrites this value automatically at startup; the change only needs to be applied manually on bare-metal installs.

[reverse-proxy]
; URL where the Canvus web-proxy gateway is running. The Canvus server routes
; all non-API web traffic (dashboard, web-client, authentication flows) to
; this URL.
;
; 26.4.0 and later: MUST point at the web-proxy gateway (port 5805), NOT at
; the legacy dashboard (port 5806). The web-proxy then fronts both the
; dashboard admin UI and the web-client canvas UI.
;
; CONTAINER DEFAULT: http://localhost:5805
; dashboard-url=http://localhost:5805

The web-proxy also introduces a new WebSocket handshake requirement for clients. This is not a configuration knob — it is documented here so operators inspecting proxy logs recognise the traffic:

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

Dashboard session secret

The Node.js dashboard signs 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 dashboard 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 dashboard 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.