Setting up a WebRTC proxy for Mattermost

At PowerDNS, we’ve become quite fond of Mattermost, an MIT-licensed, self-hosted alternative for Slack, for our internal communication.

As a beta feature, Mattermost allows one-on-one video calls using WebRTC. A WebRTC proxy is needed to allow the calling parties to establish communication. Janus is the recommended proxy software. Unfortunately, the documentation is sparse on how to configure Janus to achieve this.

This guide assumes a Janus 0.2.3 installation on Debian or Ubuntu, but should be applicable to other versions and operating systems. It only shows settings that should be modified, modify all others at you own discretion. The configuration files for Janus have many comments for each setting.

Configuring Janus

Janus support tons of transports and has many settings. For Mattermost, the secure WebSockets transport and the HTTPS admin need to be configured.

After installing Janus, edit /etc/janus/janus.cfg to enable the admin:

[general]
token_auth = True
admin_secret = V3ryS3cr3t
server_name = webrtc-proxy

And use valid certificates for DTLS (used to exchange key material inside the RTP session):

[certificates]
cert_pem = /etc/ssl/private/webrtc-proxy.example.com.pem
cert_key = /etc/ssl/private/webrtc-proxy.example.com.key

If you need IPv6 support, enable this as well:

[media]
ipv6 = yes

To create tokens, Mattermost needs to access the admin endpoint on the proxy. This endpoint can be reached over HTTP and HTTPS (from Mattermost). In this configuration the admin HTTP and the HTTP and HTTPS proxying are disabled. The configuration file for the HTTP transport is /etc/janus/janus.transport.http.cfg.

[general]
http = no
https = no

[admin]
admin_http = no
admin_base_path = /admin
admin_https = yes
admin_secure_port = 7889

[certificates]
cert_pem = /etc/ssl/private/webrtc-proxy.example.com.pem
cert_key = /etc/ssl/private/webrtc-proxy.example.com.key

The last bit of required configuration for Janus is the WebSockets transport. As the admin over WebSockets is not used by Mattermost, this is disabled. This configuration file is called /etc/janus/janus.transport.websockets.cfg.

[general]
ws = no
wss = yes
wss_port = 8989

[admin]
admin_ws = False
admin_wss = False

[certificates]
cert_pem = /etc/ssl/private/webrtc-proxy.example.com.pem
cert_key = /etc/ssl/private/webrtc-proxy.example.com.key

Now that Janus is configured, restart the service (systemctl restart janus.service) and move on to Mattermost.

Configuring Mattermost

Mattermost can be configured via the web interface (System Console > WebRTC (Beta)) or via the config.json file. See the WebRTC (Beta) documentation which settings in the web interface match the ones from the configuration file.

Some things to keep in mind:

• The GatewayAdminUrl’s port must match the the admin_secure_port set in /etc/janus/janus.transport.http.cfg
• The GatewayAdminUrl’s path must match the the admin_base_path set in /etc/janus/janus.transport.http.cfg
• The GatewayWebsocketUrl must use the wss:// scheme for WebRTC to work
• The GatewayWebsocketUrl’s port must match the wss_port from /etc/janus/janus.transport.websockets.cfg
• The GatewayAdminSecret must match the admin_secret from /etc/janus/janus.cfg

The WebrtcSettings should look like this after configuring:

  "WebrtcSettings": {
    "Enable": true,
    "GatewayAdminSecret": "V3ryS3cr3t",
    "GatewayAdminUrl": "https://webrtc-proxy.example.com:7889/admin",
    "GatewayWebsocketUrl": "wss://webrtc-proxy.example.com:8989",
    "StunURI": "",
    "TurnSharedKey": "",
    "TurnURI": "",
    "TurnUsername": ""
  }

Mattermost should pick up the configuration changes by itself. If not, restart it.

Now the users can enable WebRTC for themselves (Account Settings > Advanced > Preview pre-release features > Enable the ability to make and receive one-on-one WebRTC calls) and start calling each other.

What about STUN and TURN?

In the testing we have done with the video calls, no NAT-punching was needed. Your mileage may vary, of course.

Bonus: Installing Janus on Debian Stretch

There is no Janus package available on Debian Stretch. As I like to run one distribution in my infrastructure, I had to backport Janus from Buster to Stretch.

To install Janus on Debian Stretch, add the following to /etc/apt/sources.list.d/janus.list:

deb https://repo.plexis.eu/debian stretch-janus main

And add the public key to the keyring:

curl -L https://repo.plexis.eu/6A8573EDDC4A8842.asc | sudo apt-key add -

Now install Janus:

sudo apt-get update
sudo apt-get install janus janus-tools