Worker Configuration

This page documents every configuration option available for user-owned CallMeter workers. All configuration is done through environment variables passed to the Docker container.

Required Environment Variables

These variables must be set for the worker to start and connect to CallMeter.

# Minimal configuration
environment:
  WORKER_TOKEN: "${WORKER_TOKEN}"
  CLOUD_URL: "wg.callmeter.io:443"

Optional Environment Variables

General Settings

environment:
  WORKER_TOKEN: "${WORKER_TOKEN}"
  CLOUD_URL: "wg.callmeter.io:443"
  WORKER_NAME: "lab-worker-nyc"
  LOG_LEVEL: "info"
  LOG_FORMAT: "json"
  HEALTH_PORT: "3030"

SIP Network Configuration

These settings control how the worker handles SIP signaling within your network. In most deployments, the defaults work correctly. You only need to set these if the worker is behind NAT, has multiple network interfaces, or needs to bind to specific addresses.

RTP Media Port Configuration

Each active SIP endpoint uses one or more RTP ports (one for audio, one for video if enabled, plus RTCP ports). Ensure the port range is large enough for your capacity:

• Audio-only calls: ~2 ports per endpoint (RTP + RTCP)
• Audio + video calls: ~4 ports per endpoint (audio RTP/RTCP + video RTP/RTCP)

For a worker with 100 endpoint capacity running audio-only tests, you need at least 200 ports in the range. The default range (10000-65535) provides over 55,000 ports, which is sufficient for any capacity configuration.

NAT Traversal Configuration

When the worker operates behind NAT (common in corporate networks), you may need to configure how it advertises its network address.

Common NAT scenario: The worker has a private IP (10.0.1.50) but your SIP server needs to send RTP to the worker's NAT-mapped address (203.0.113.10):

environment:
  SIP_IP: "10.0.1.50"         # Local bind address
  SDP_IP: "203.0.113.10"      # Advertised in SDP to SIP server
  EXTERNAL_IP: "203.0.113.10" # Advertised in SIP headers

If your SIP infrastructure and the worker are on the same network (the most common deployment), you do not need NAT configuration at all.

Logging Configuration

Workers produce structured logs that can be consumed by log aggregation systems.

Log Levels

Log Formats

# Production logging
environment:
  LOG_LEVEL: "info"
  LOG_FORMAT: "json"

# Debugging
environment:
  LOG_LEVEL: "debug"
  LOG_FORMAT: "pretty"

Log Output

All logs are written to stdout and stderr, following Docker logging conventions. Use Docker's logging drivers to route logs to your preferred destination:

# Docker Compose with logging driver
services:
  callmeter-worker:
    image: registry.callmeter.io/worker:latest
    logging:
      driver: "json-file"
      options:
        max-size: "50m"
        max-file: "5"

Health Check Configuration

The worker runs an HTTP health endpoint for monitoring and orchestration integration.

Health Endpoint

GET http://localhost:{HEALTH_PORT}/health

Response:

{
  "status": "healthy",
  "connected": true,
  "uptime": 3600
}

Docker Health Check Integration

Add a health check to your Docker Compose configuration:

services:
  callmeter-worker:
    image: registry.callmeter.io/worker:latest
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3030/health"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 15s

This allows Docker to automatically detect and optionally restart unhealthy workers.

Token Management

Token Format

Worker tokens follow a fixed format:

• Prefix: cmw_ (4 characters)
• Random hex string: 64 characters
• Total length: 68 characters

Example: cmw_a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4e5f67890

Token Security

The token authenticates the worker to the CallMeter platform. It is hashed server-side and never stored in plaintext. Security best practices:

• Store in a secrets manager --- HashiCorp Vault, AWS Secrets Manager, GCP Secret Manager, Azure Key Vault
• Use environment files with restricted permissions --- chmod 600 .env
• Never commit to version control --- Add .env to .gitignore
• Rotate periodically --- Regenerate tokens as part of your security rotation schedule
• One token per worker --- Never share tokens between workers; a token can only authenticate one simultaneous connection

Regenerating a Token

If a token is compromised or lost:

1. Open your project in CallMeter
2. Navigate to Workers
3. Click on the worker
4. Click Regenerate Token
5. Copy the new token immediately (it will not be shown again)
6. Update the WORKER_TOKEN environment variable on the Docker host
7. Restart the worker container

Token-Related Errors

Performance Tuning

Resource Allocation

The worker's capacity should match the resources allocated to the Docker container. General guidelines:

These are approximate values for audio-only calls. Video calls require approximately 3-5x the CPU and 5-10x the bandwidth per endpoint.

Docker Resource Limits

Set explicit resource limits to prevent the worker from consuming all host resources:

deploy:
  resources:
    limits:
      cpus: "4.0"
      memory: 4G
    reservations:
      cpus: "2.0"
      memory: 2G

Network Mode

For optimal network performance, especially at high endpoint counts, consider using Docker host networking:

services:
  callmeter-worker:
    image: registry.callmeter.io/worker:latest
    network_mode: host
    environment:
      WORKER_TOKEN: "${WORKER_TOKEN}"
      CLOUD_URL: "wg.callmeter.io:443"
      SIP_IP: "10.0.1.50"

Host networking eliminates Docker's NAT overhead and provides direct access to the host's network stack. This is recommended for workers handling more than 100 concurrent endpoints.

Complete Configuration Example

A production-ready docker-compose.yml with all common options:

version: "3.8"

services:
  callmeter-worker:
    image: registry.callmeter.io/worker:latest
    container_name: callmeter-worker
    restart: unless-stopped
    environment:
      # Required
      WORKER_TOKEN: "${WORKER_TOKEN}"
      CLOUD_URL: "wg.callmeter.io:443"
      # Identity
      WORKER_NAME: "production-dc-fra-01"
      # Logging
      LOG_LEVEL: "info"
      LOG_FORMAT: "json"
      # Health
      HEALTH_PORT: "3030"
      # SIP/Media (only if needed for your network)
      # SIP_IP: "10.0.1.50"
      # MEDIA_IP: "10.0.1.50"
      # SDP_IP: "10.0.1.50"
      # RTP_PORT_MIN: "10000"
      # RTP_PORT_MAX: "20000"
    ports:
      - "3030:3030"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3030/health"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 15s
    deploy:
      resources:
        limits:
          cpus: "4.0"
          memory: 4G
        reservations:
          cpus: "2.0"
          memory: 2G
    logging:
      driver: "json-file"
      options:
        max-size: "50m"
        max-file: "5"

Next Steps

• Networking --- Deep dive into firewall rules, NAT, and bandwidth requirements
• Capacity and Scaling --- Size workers correctly and scale horizontally
• Troubleshooting --- Resolve configuration and connection issues