docs/main/administration-guide/configure/calls-offloader-setup.mdx
This guide provides detailed instructions for setting up, configuring, and validating the Mattermost calls-offloader service used for call recording and transcription features.
The calls-offloader service is a dedicated microservice that handles resource-intensive tasks for Mattermost Calls, including:
By offloading these tasks to a dedicated service, the main Mattermost server and RTCD service can focus on core functionality while maintaining optimal performance.
Before deploying calls-offloader, ensure you have:
For detailed system requirements and performance recommendations, refer to the calls-offloader performance documentation.
Call recordings can consume significant storage space. Based on average recording sizes with screen sharing on (including one audio track), storage usage by quality chosen is approximately:
Note: Audio-only recordings consume approximately 1MB per minute per participant.
Looking for an automated setup? Check out these community-maintained Calls Installation Scripts for quick provisioning of the Calls Offloader service on Ubuntu/Debian systems.
</Tip>Download the latest release from the calls-offloader GitHub repository
Create the necessary directories:
sudo mkdir -p /opt/calls-offloader/data/db
sudo useradd --system --home /opt/calls-offloader calls-offloader
sudo chown -R calls-offloader:calls-offloader /opt/calls-offloader
Create a configuration file (/opt/calls-offloader/config.toml):
[api]
http.listen_address = ":4545"
http.tls.enable = false
http.tls.cert_file = ""
http.tls.cert_key = ""
security.allow_self_registration = true
security.enable_admin = false
security.admin_secret_key = ""
security.session_cache.expiration_minutes = 1440
[store]
data_source = "/opt/calls-offloader/data/db"
[jobs]
api_type = "docker"
max_concurrent_jobs = 100
failed_jobs_retention_time = "30d"
image_registry = "mattermost"
[logger]
enable_console = true
console_json = false
console_level = "INFO"
enable_file = true
file_json = true
file_level = "DEBUG"
file_location = "/opt/calls-offloader/calls-offloader.log"
enable_color = true
Create a systemd service file (/etc/systemd/system/calls-offloader.service):
[Unit]
Description=Mattermost Calls Offloader Service
After=network.target docker.service
Requires=docker.service
[Service]
Type=simple
User=calls-offloader
WorkingDirectory=/opt/calls-offloader
ExecStart=/opt/calls-offloader/calls-offloader --config /opt/calls-offloader/config.toml
Restart=always
RestartSec=10
LimitNOFILE=65536
[Install]
WantedBy=multi-user.target
Enable and start the service:
sudo systemctl daemon-reload
sudo systemctl enable calls-offloader
sudo systemctl start calls-offloader
Check the service status:
sudo systemctl status calls-offloader
Verify the service is responding:
curl http://localhost:4545/version
# Example output:
# {"buildDate":"2025-03-10 19:13","buildVersion":"v0.9.2","buildHash":"a4bd418","goVersion":"go1.23.6"}
The API section controls how the service accepts requests:
:4545)Controls persistent data storage:
Controls job processing behavior:
docker or kubernetes)mattermost)Controls logging output:
When the Mattermost deployment is running in a private network, additional configuration may be necessary for the jobs spawned by the calls-offloader service to reach the Mattermost server.
In such cases, you can override the site URL used by recorder jobs or transcriber jobs to connect to Mattermost by setting the following environment variables on the Mattermost server:
When these Site URL overrides are used, the ServiceSettings.AllowCorsFrom setting on your Mattermost server may need to be adjusted accordingly to ensure CORS does not block requests.
This override configuration lets the recorder and transcriber jobs connect to mattermost server using HTTP instead of HTTPS, which should only be used in a private network.
</Note>Example configuration:
Create or edit the Mattermost environment file (/opt/mattermost/config/mattermost.environment):
MM_CALLS_RECORDER_SITE_URL="http://internal-mattermost-server:8065"
MM_CALLS_TRANSCRIBER_SITE_URL="http://internal-mattermost-server:8065"
Then ensure your Mattermost systemd service references this environment file:
[Unit]
Description=Mattermost
After=network.target
[Service]
Type=notify
EnvironmentFile=/opt/mattermost/config/mattermost.environment
ExecStart=/opt/mattermost/bin/mattermost
TimeoutStartSec=3600
KillMode=mixed
Restart=always
RestartSec=10
WorkingDirectory=/opt/mattermost
User=mattermost
Group=mattermost
[Install]
WantedBy=multi-user.target
This is particularly useful when:
After deploying calls-offloader, validate the installation:
Check service status:
# For systemd
sudo systemctl status calls-offloader
Test API connectivity:
From the calls-offloader server (localhost test):
curl http://localhost:4545/version
# Should return version information
# Example: {"buildDate":"2025-03-10 19:13","buildVersion":"v0.9.2","buildHash":"a4bd418","goVersion":"go1.23.6"}
From the Mattermost server:
curl http://YOUR_CALLS_OFFLOADER_SERVER:4545/version
# Should return the same version information
# This confirms network connectivity from Mattermost to calls-offloader
If the localhost test works but the Mattermost server test fails, check:
Verify Docker service (if using docker api_type):
# Check that system user running calls-offloader can access Docker
sudo -u calls-offloader docker ps
Once calls-offloader is properly set up and validated, configure Mattermost to use it:
Go to System Console > Plugins > Calls
In the Job Service section:
http://calls-offloader-server:4545)Enable recording and transcription features as needed:
Save the configuration
Restart the Calls plugin to re-establish state:
Test by starting a call and starting a recording
"failed to create recording job: max concurrent jobs reached"
This error occurs when the calls-offloader service has reached its configured job limit, and it will usually result in a failure message on the Mattermost Calls plugin side (such as a timeout).
Solutions:
max_concurrent_jobs in the configurationJobs not processing
Check the following:
sudo systemctl status calls-offloadercalls-offloader)Docker permission issues
If using Docker API and seeing permission errors:
# Add calls-offloader user to docker group
sudo usermod -a -G docker calls-offloader
sudo systemctl restart calls-offloader
Monitor calls-offloader job containers:
# View running job containers
docker ps --format "{{.ID}} {{.Image}}" | grep "calls"
# Follow logs for debugging
docker ps --format "{{.ID}} {{.Image}}" | grep "calls" | awk '{print $1}' | xargs -I {} docker logs -f {}
# View completed job containers
docker ps -a --filter "status=exited"
Monitor service health:
# Check service version and health
curl http://localhost:4545/version
Check service logs:
# View recent logs
sudo journalctl -u calls-offloader -f
# View log file (if file logging enabled)
tail -f /opt/calls-offloader/calls-offloader.log
Monitor calls-offloader performance and resource usage to ensure optimal operation. See Calls Metrics and Monitoring for details on setting up metrics and observability.
calls-offloaderThis guide covers deploying calls-offloader in an environment without internet access. The process uses scripts from the calls-install-scripts repository and follows a two-phase workflow: preparing a transfer bundle on an internet-connected machine, then deploying it on the isolated target machine.
Because calls-offloader relies on Docker images for the recorder and transcriber jobs, an air-gapped deployment requires that those images be pre-pulled and packaged alongside the calls-offloader binary before being transferred to the target environment.
The install scripts handle this in two stages:
setup-airgap-offloader.sh pulls the required Docker images and downloads the calls-offloader binary, then packages everything into a transfer bundle and generates a ready-to-run deployment script.deploy-airgap-offloader.sh script, which loads the Docker images into a local registry and installs the service.On the internet-connected machine, run setup-airgap-offloader.sh specifying the versions of each component to package:
./setup-airgap-offloader.sh \
--offloader v0.9.5 \
--recorder v0.9.0 \
--transcriber v0.3.0 \
--arch amd64
| Flag | Description | Default |
|---|---|---|
--offloader VERSION | calls-offloader binary version (e.g. v0.9.5) | required |
--recorder VERSION | calls-recorder Docker image version | required |
--transcriber VERSION | calls-transcriber Docker image version | required |
--arch amd64|arm64 | Target CPU architecture | amd64 |
The script will:
calls-recorder and calls-transcriber Docker images from Docker Hubcalls-offloader binary from GitHub releases.tar archivesdeploy-airgap-offloader.sh deployment script configured for the selected versionsCopy the generated bundle to the target machine using whatever transfer mechanism is available in your environment (USB drive, secure file transfer, etc.):
scp calls-offloader-airgap-bundle.tar.gz user@airgap-host:/tmp/
On the air-gapped machine, extract the bundle:
tar -xzf calls-offloader-airgap-bundle.tar.gz
cd calls-offloader-airgap-bundle/
Run the generated deployment script with root or sudo privileges:
sudo ./deploy-airgap-offloader.sh
This script will:
calls-offloader binary to /usr/local/bin/mattermost system user and add it to the docker groupOnce complete, verify the service is up:
curl http://localhost:4545/version
Configure the Mattermost Calls plugin to use the offloader service via System Console > Plugins > Calls > Job service URL, setting it to http://<offloader-host>:4545.
[!NOTE] The first time Mattermost connects to the offloader it will self-register and store its authentication key in the database, provided
API_SECURITY_ALLOWSELFREGISTRATION=trueis set (the default in the deployment script).
In air-gapped environments the recorder and transcriber containers typically need to reach the Mattermost server via an internal URL. Set the following environment variables on the Mattermost server to override the site URL used by spawned jobs:
MM_CALLS_RECORDER_SITE_URL=http://internal-mattermost-server:8065
MM_CALLS_TRANSCRIBER_SITE_URL=http://internal-mattermost-server:8065
You may also need to add the internal URL to ServiceSettings.AllowCorsFrom in the Mattermost server configuration.
[!NOTE] In particularly restrictive environments (e.g., VMs with strict network isolation), set
DOCKER_NETWORK=hostin thecalls-offloaderservice environment so that job containers can reach the Mattermost server via its local address.
If your air-gapped environment already has an internal Docker registry, you can point install-offloader.sh at it directly instead of using the local registry set up by the deployment script:
sudo ./install-offloader.sh \
--binary ./calls-offloader-linux-amd64 \
--image-registry registry.internal.example.com/mattermost \
--arch amd64
The --image-registry flag sets the registry prefix used when the offloader pulls recorder and transcriber images for each job.