Configuration

MikroRoom works out of the box with zero configuration, but you can customize it for production deployments.

Configuration Files

MikroRoom uses two configuration approaches:

1. Frontend Config - static/mikroroom.config.json (runtime)
2. Server Config - .env file (environment variables)

Frontend Configuration

Edit static/mikroroom.config.json to configure the client:

{
  "apiUrl": "wss://api.yourdomain.com/ws",
  "iceServers": [
    { "urls": "stun:stun.cloudflare.com:3478" },
    {
      "urls": "turn:turn.yourdomain.com:3478",
      "username": "your-username",
      "credential": "your-password"
    }
  ]
}

Options

apiUrl (required)

WebSocket URL for the signaling server.

• Development: ws://localhost:3000/ws
• Production (HTTPS): wss://yourdomain.com/ws
• Separate API server: wss://api.yourdomain.com/ws

Tip

Use ws:// for HTTP and wss:// for HTTPS. Mismatched protocols will fail.

iceServers (optional)

Array of STUN/TURN servers for WebRTC connectivity.

Default (if omitted):

[{ "urls": "stun:stun.cloudflare.com:3478" }]

With TURN (recommended for production):

[
  { "urls": "stun:stun.cloudflare.com:3478" },
  {
    "urls": "turn:turn.yourdomain.com:3478",
    "username": "mikroroom",
    "credential": "your-secure-password"
  }
]

Server Configuration

Create a .env file in the project root:

# Server port
PORT=3000

# HTTPS (optional)
USE_HTTPS=false
SSL_CERT_PATH=/path/to/cert.pem
SSL_KEY_PATH=/path/to/key.pem

# TURN server (recommended for production)
TURN_SERVER_URL=turn:turn.yourdomain.com:3478
TURN_SERVER_USERNAME=mikroroom
TURN_SERVER_CREDENTIAL=your-password

# Room management
MAX_LATENT_ROOMS=10
LATENT_ROOM_MAX_AGE_HOURS=24

Server Options

PORT

Server port (default: 3000)

PORT=8080

USE_HTTPS

Enable HTTPS server (default: false)

USE_HTTPS=true
SSL_CERT_PATH=/etc/letsencrypt/live/yourdomain.com/fullchain.pem
SSL_KEY_PATH=/etc/letsencrypt/live/yourdomain.com/privkey.pem

Caution

When USE_HTTPS=true, both certificate paths are required.

TURN Server

Configure TURN for users behind strict NAT/firewalls:

TURN_SERVER_URL=turn:turn.example.com:3478
TURN_SERVER_USERNAME=username
TURN_SERVER_CREDENTIAL=password

Tip

TURN credentials must be set in BOTH server .env and frontend mikroroom.config.json.

Room Management

Control room lifecycle:

MAX_LATENT_ROOMS=20           # Max pre-created empty rooms
LATENT_ROOM_MAX_AGE_HOURS=48  # Hours before cleanup

HTTPS Setup

HTTPS is required for:

• Camera/microphone access in browsers
• Production deployments
• Secure WebSocket connections (WSS)

Option 1: Let’s Encrypt (Recommended)

# Install Certbot
sudo apt install certbot

# Get certificate
sudo certbot certonly --standalone -d yourdomain.com

# Configure MikroRoom
USE_HTTPS=true
SSL_CERT_PATH=/etc/letsencrypt/live/yourdomain.com/fullchain.pem
SSL_KEY_PATH=/etc/letsencrypt/live/yourdomain.com/privkey.pem

Option 2: Reverse Proxy (Easier)

Use Nginx or Caddy for SSL termination. Run MikroRoom on HTTP internally.

Nginx Example:

server {
    listen 443 ssl http2;
    server_name yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/yourdomain.com/privkey.pem;

    # WebSocket upgrade for /ws
    location /ws {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }

    # Proxy other requests
    location / {
        proxy_pass http://localhost:3000;
    }
}

Caddy Example (auto-HTTPS):

yourdomain.com {
    reverse_proxy localhost:3000
}

TURN Server Setup

TURN servers ensure connectivity for users behind strict firewalls (~20% of cases).

Self-Hosted with Coturn

Install and configure Coturn:

# Install (Ubuntu/Debian)
sudo apt install coturn

# Edit /etc/turnserver.conf
listening-port=3478
realm=yourdomain.com
server-name=turn.yourdomain.com
lt-cred-mech
user=mikroroom:your-secure-password
fingerprint

# Start Coturn
sudo systemctl enable coturn
sudo systemctl start coturn

# Allow firewall
sudo ufw allow 3478/tcp
sudo ufw allow 3478/udp
sudo ufw allow 49152:65535/udp

Update both configs:

Server (.env):

TURN_SERVER_URL=turn:turn.yourdomain.com:3478
TURN_SERVER_USERNAME=mikroroom
TURN_SERVER_CREDENTIAL=your-secure-password

Frontend (mikroroom.config.json):

{
  "iceServers": [
    { "urls": "stun:stun.cloudflare.com:3478" },
    {
      "urls": "turn:turn.yourdomain.com:3478",
      "username": "mikroroom",
      "credential": "your-secure-password"
    }
  ]
}

Managed TURN Services

Alternatively, use a managed service:

• Twilio - Get credentials
• Metered.ca - Free tier available
• Xirsys - WebRTC infrastructure

Environment Examples

Development

.env

PORT=3000

mikroroom.config.json

{
  "apiUrl": "ws://localhost:3000/ws"
}

Production

.env

PORT=3000
TURN_SERVER_URL=turn:turn.yourdomain.com:3478
TURN_SERVER_USERNAME=mikroroom
TURN_SERVER_CREDENTIAL=strong-password
MAX_LATENT_ROOMS=20

mikroroom.config.json

{
  "apiUrl": "wss://yourdomain.com/ws",
  "iceServers": [
    { "urls": "stun:stun.cloudflare.com:3478" },
    {
      "urls": "turn:turn.yourdomain.com:3478",
      "username": "mikroroom",
      "credential": "strong-password"
    }
  ]
}

Next Steps

• Deployment Guide - Deploy to production
• CLI Reference - All configuration options