RTCD Setup and Configuration#

Note

plans-img The rtcd service is available only on Enterprise plans

This guide provides detailed instructions for setting up, configuring, and validating a Mattermost Calls deployment using the dedicated RTCD service.

Prerequisites#

Before deploying RTCD, ensure you have:

  • A Mattermost Enterprise license

  • A server or VM with sufficient CPU and network capacity (see the Performance section for sizing guidance)

Network Requirements#

The following network connectivity is required:

Service

Ports

Protocols

Source

Target

Calls plugin API

80,443

TCP (incoming)

Mattermost clients

Mattermost server

RTC media

8443

UDP (incoming)

Mattermost clients

Mattermost or RTCD

RTC media

8443

TCP (incoming)

Mattermost clients

Mattermost or RTCD

RTCD API

8045

TCP (incoming)

Mattermost server

RTCD service

STUN

3478

UDP (outgoing)

Mattermost or RTCD

STUN servers

Installation and Deployment#

There are multiple ways to deploy RTCD, depending on your environment. We recommend the following order based on production readiness and operational control:

Docker Deployment#

Docker deployment is suitable for development, testing, or containerized production environments:

  1. Run the RTCD container with basic configuration:

    docker run -d --name rtcd \
  -e "RTCD_LOGGER_ENABLEFILE=false" \
  -e "RTCD_API_SECURITY_ALLOWSELFREGISTRATION=true" \
  -p 8443:8443/udp \
  -p 8443:8443/tcp \
  -p 8045:8045/tcp \
  mattermost/rtcd:latest

  2. For debugging purposes, you can enable more detailed logging:

    docker run -d --name rtcd \
  -e "RTCD_LOGGER_ENABLEFILE=false" \
  -e "RTCD_LOGGER_CONSOLELEVEL=DEBUG" \
  -e "RTCD_API_SECURITY_ALLOWSELFREGISTRATION=true" \
  -p 8443:8443/udp \
  -p 8443:8443/tcp \
  -p 8045:8045/tcp \
  mattermost/rtcd:latest

    To view the logs:

    docker logs -f rtcd

You can also use a mounted configuration file instead of environment variables:

docker run -d --name rtcd \
  -p 8045:8045 \
  -p 8443:8443/udp \
  -p 8443:8443/tcp \
  -v /path/to/config.toml:/rtcd/config/config.toml \
  mattermost/rtcd:latest

For a complete sample configuration file, see the RTCD config.sample.toml in the official repository.

Kubernetes Deployment#

For Kubernetes deployments, use the official Helm chart:

  1. Add the Mattermost Helm repository:

    helm repo add mattermost https://helm.mattermost.com
helm repo update

  2. Install the RTCD chart:

    helm install mattermost-rtcd mattermost/mattermost-rtcd \
  --set ingress.enabled=true \
  --set ingress.host=rtcd.example.com \
  --set service.annotations."service\\.beta\\.kubernetes\\.io/aws-load-balancer-backend-protocol"=udp \
  --set rtcd.ice.hostOverride=rtcd.example.com

    Refer to the RTCD Helm chart documentation for additional configuration options.

Configuration#

RTCD Configuration File#

The RTCD service uses a TOML configuration file. Here’s a comprehensive example with commonly used settings:

[api]
# The address and port to which the HTTP API server will listen
http.listen_address = ":8045"
# Security settings for authentication
security.allow_self_registration = false
security.enable_admin = true
security.admin_secret_key = "YOUR_API_KEY"
# Configure allowed origins for CORS
security.allowed_origins = ["https://mattermost.example.com"]

[rtc]
# The UDP address and port for media traffic
ice_address_udp = ""
ice_port_udp = 8443
# The TCP address and port for fallback connections 
ice_address_tcp = ""
ice_port_tcp = 8443
# Public hostname or IP that clients will use to connect
ice_host_override = "rtcd.example.com"

[logger]
# Logging configuration
enable_console = true
console_json = false
console_level = "INFO"
enable_file = true
file_json = true
file_level = "DEBUG"
file_location = "rtcd.log"

[metrics]
# Prometheus metrics configuration
enable_prom = true
prom_port = 9090

Key Configuration Options:

  • api.http.listen_address: The address and port where the RTCD HTTP API service listens

  • rtc.ice_address_udp: The UDP address for media traffic (empty means listen on all interfaces)

  • rtc.ice_port_udp: The UDP port for media traffic

  • rtc.ice_address_tcp: The TCP address for fallback media traffic

  • rtc.ice_port_tcp: The TCP port for fallback media traffic

  • rtc.ice_host_override: The public hostname or IP address clients will use to connect to RTCD

  • api.security.allowed_origins: List of allowed origins for CORS

  • api.security.admin_secret_key: API key for Mattermost servers to authenticate with RTCD

Required Mattermost Server Configuration#

When using RTCD, you must configure the Mattermost server’s CORS settings to allow proper communication between the server and the RTCD service.

CORS Configuration#

The AllowCorsFrom setting must include your SiteURL and, if using calls-offloader in a private network, the Mattermost server’s private IP address:

Using mmctl:

# Basic RTCD configuration - include your SiteURL
mmctl config set ServiceSettings.AllowCorsFrom "https://your-domain.com"

# If using calls-offloader in a private network, also include Mattermost's private IP with port 8065
mmctl config set ServiceSettings.AllowCorsFrom "https://your-domain.com http://192.168.1.100:8065"

Using System Console:

  1. Go to System Console > Environment > Web Server

  2. Set Allow cross-origin requests from to include:

    • Your SiteURL (e.g., https://your-domain.com)

    • If using calls-offloader in a private network: Also include Mattermost’s private IP with port 8065 (e.g., http://192.168.1.100:8065)

Using config.json:

{
  "ServiceSettings": {
    "AllowCorsFrom": "https://your-domain.com http://192.168.1.100:8065"
  }
}

Important

This CORS configuration is specifically required for RTCD deployments and is not needed for integrated mode deployments. Multiple origins should be separated by spaces.

STUN/TURN Configuration#

For clients behind strict firewalls, you may need to configure STUN/TURN servers. In the RTCD configuration file, reference your STUN/TURN servers as follows:

[rtc]
# STUN/TURN server configuration
ice_servers = [
  { urls = ["stun:stun.example.com:3478"] },
  { urls = ["turn:turn.example.com:3478"], username = "turnuser", credential = "turnpassword" }
]

We recommend using coturn for your TURN server implementation.

System Tuning#

For high-volume deployments, tune your Linux system:

  1. Add the following to /etc/sysctl.conf:

    # Increase UDP buffer sizes
net.core.rmem_max = 16777216
net.core.wmem_max = 16777216
net.core.optmem_max = 16777216

  2. Apply the settings:

    sudo sysctl -p

Validation and Testing#

After deploying RTCD, validate the installation:

  1. Check service status and version:

    curl http://YOUR_RTCD_SERVER:8045/version
# Should return a JSON object with service information
# Example: {"build_hash":"abc123","build_date":"2023-01-15T12:00:00Z","build_version":"0.11.0","goVersion":"go1.20.4"}

  2. Test UDP connectivity:

    On the RTCD server:

    nc -l -u -p 8443

    On a client machine:

    nc -v -u YOUR_RTCD_SERVER 8443

    Type a message and hit Enter on either side. If messages are received on both ends, UDP connectivity is working.

    Note: This test must be run with the RTCD service stopped, as it binds to the same port.

    sudo systemctl stop rtcd

  3. Test TCP connectivity (if enabled):

    Similar to the UDP test, but remove the -u flag from both commands.

  4. Monitor metrics:

    Refer to Calls Metrics and Monitoring for setting up Calls metrics and monitoring.

Horizontal Scaling#

To scale RTCD horizontally:

  1. Deploy multiple RTCD instances:

    Deploy multiple RTCD servers, each with their own unique IP address.

  2. Configure DNS-based load balancing:

    Set up a DNS record that points to multiple RTCD IP addresses:

    rtcd.example.com.    IN A    10.0.0.1
rtcd.example.com.    IN A    10.0.0.2
rtcd.example.com.    IN A    10.0.0.3

  3. Configure health checks:

    Set up health checks to automatically remove unhealthy RTCD instances from DNS.

  4. Configure Mattermost:

    In the Mattermost System Console, set the RTCD Service URL to your DNS name (e.g., rtcd.example.com).

The Mattermost Calls plugin will distribute calls among the available RTCD hosts. Remember that a single call will always be hosted on one RTCD instance; sessions belonging to the same call are not spread across different instances.

Integration with Mattermost#

Once RTCD is properly set up and validated, configure Mattermost to use it:

  1. Go to System Console > Plugins > Calls

  2. Enable the Enable RTCD Service option

  3. Set the RTCD Service URL to your RTCD service address (either a single server or DNS load-balanced hostname)

  4. If configured, enter the RTCD API Key that matches the one in your RTCD configuration

  5. Save the configuration

  6. Test by creating a new call in any Mattermost channel

  7. Verify that the call is being routed through RTCD by checking the RTCD logs and metrics

Other Calls Documentation#

For detailed Mattermost Calls configuration options, see the Calls Plugin Configuration Settings documentation.