Skip to content

livekit

Jump to bottom
docisit edited this page Jul 27, 2026 · 2 revisions

🌐 LiveKit Setup

WebRTC infrastructure for guest video/audio — the backbone of real-time communication in ITG Media App.

What is LiveKit?

LiveKit is the open-source WebRTC platform that powers all real-time video and audio in ITG Media App. It handles:

  • Guest-to-host WebRTC connections (video + audio in the browser)
  • WHIP ingress (OBS pushing a dedicated video feed)
  • Egress (recording and RTMP output)
  • Room management (joining, leaving, muting, kicking participants)
  • TURN/STUN (NAT traversal for guests behind firewalls)

Without LiveKit, ITG Media App is essentially a static website — all live video/audio features depend on it.

📋 LiveKit Options

Option Best For Cost
LiveKit Cloud Easiest setup, no server management Free tier → paid plans
Self-Hosted (Docker) Full control, on your own infrastructure Your server cost only

☁️ Option A: LiveKit Cloud (Recommended for Beginners)

The simplest way — LiveKit runs their infrastructure, you just use it.

1. Sign Up

Go to cloud.livekit.io and create an account.

2. Create a Project

  1. Click "Create Project"
  2. Choose a region closest to your users
  3. Copy your API Key and API Secret (save them — you won't see the secret again!)

3. Configure ITG Media App

Add the keys to your .env:

LIVEKIT_API_KEY=APIxxxxxxxxxxxxx
LIVEKIT_API_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
LIVEKIT_URL=wss://your-project.livekit.cloud
LIVEKIT_API_URL=https://your-project.livekit.cloud

That's it! LiveKit Cloud handles TURN, SSL, and scaling automatically.

💡 LiveKit Cloud TURN is included for free — guests behind strict firewalls/NATs will connect without issues.

🐳 Option B: Self-Hosted LiveKit (Docker)

Run LiveKit on your own server alongside ITG Media App.

1. Install Docker

# Ubuntu/Debian
sudo apt update
sudo apt install docker.io docker-compose-v2 -y
sudo systemctl enable docker
sudo systemctl start docker

2. Create LiveKit Directory

mkdir -p /opt/livekit
cd /opt/livekit

3. Create LiveKit Config

Create livekit.yaml:

port: 7880
rtc:
  tcp_port: 7881
  udp_port: 7882
  port_range_start: 50000
  port_range_end: 60000
  use_external_ip: true
  # For TURN, LiveKit Cloud includes free TURN.
  # If self-hosting TURN, add it here.
keys:
  # Generate with: livekit-server generate-keys
  APIxxxxxxxxxxxxx: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

4. Create Docker Compose File

Create docker-compose.yml:

version: '3.8'
services:
  livekit:
    image: livekit/livekit-server:latest
    command: --config /etc/livekit.yaml --node-ip=<YOUR_SERVER_PUBLIC_IP>
    network_mode: host
    volumes:
      - ./livekit.yaml:/etc/livekit.yaml
    restart: unless-stopped

  livekit-egress:
    image: livekit/egress:latest
    network_mode: host
    environment:
      - EGRESS_CONFIG_FILE=/etc/egress.yaml
    volumes:
      - ./egress.yaml:/etc/egress.yaml
    restart: unless-stopped

  livekit-ingress:
    image: livekit/ingress:latest
    network_mode: host
    environment:
      - INGRESS_CONFIG_FILE=/etc/ingress.yaml
    volumes:
      - ./ingress.yaml:/etc/ingress.yaml
    restart: unless-stopped

5. Generate API Keys

docker run --rm livekit/livekit-server generate-keys

Copy the output into your livekit.yaml keys: section.

6. Start LiveKit

cd /opt/livekit
docker compose up -d

7. Configure ITG Media App

Update your .env:

LIVEKIT_API_KEY=APIxxxxxxxxxxxxx
LIVEKIT_API_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
LIVEKIT_URL=wss://vdo.yourdomain.com
LIVEKIT_API_URL=https://vdo.yourdomain.com

🔐 Firewall & Port Configuration

For self-hosted LiveKit, open these ports on your server firewall:

Port Protocol Purpose
443 TCP Secure WebSocket (wss://) for clients
7880 TCP LiveKit API server
7881 TCP WebRTC TCP fallback
7882 UDP WebRTC ICE connectivity
50000-60000 UDP WebRTC media port range

UFW Example (Ubuntu)

sudo ufw allow 443/tcp
sudo ufw allow 7880/tcp
sudo ufw allow 7881/tcp
sudo ufw allow 7882/udp
sudo ufw allow 50000:60000/udp
sudo ufw enable

🔗 Nginx Reverse Proxy for LiveKit

Route LiveKit traffic through Nginx on a subdomain (e.g., vdo.yourdomain.com):

# /etc/nginx/sites-available/vdo.yourdomain.com
server {
    listen 443 ssl http2;
    server_name vdo.yourdomain.com;

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

    # WebSocket upgrade for LiveKit clients
    location / {
        proxy_pass http://127.0.0.1:7880;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 86400;
    }
}
# Enable site and get SSL certificate
sudo ln -s /etc/nginx/sites-available/vdo.yourdomain.com /etc/nginx/sites-enabled/
sudo certbot --nginx -d vdo.yourdomain.com
sudo nginx -t && sudo systemctl reload nginx

🔧 TURN Server Setup

TURN is required for guests behind strict firewalls or symmetric NATs. LiveKit Cloud includes free TURN. For self-hosted, you can use coturn.

Install coturn

sudo apt install coturn -y

Configure coturn

Edit /etc/turnserver.conf:

listening-port=3478
tls-listening-port=5349
listening-ip=0.0.0.0
relay-ip=<YOUR_SERVER_PUBLIC_IP>
external-ip=<YOUR_SERVER_PUBLIC_IP>
min-port=49152
max-port=65535
fingerprint
lt-cred-mech
realm=vdo.yourdomain.com
user=mediasite:<YOUR_TURN_PASSWORD>
cert=/etc/letsencrypt/live/vdo.yourdomain.com/fullchain.pem
pkey=/etc/letsencrypt/live/vdo.yourdomain.com/privkey.pem
no-cli
log-file=/var/log/turnserver.log

Start coturn

sudo systemctl enable coturn
sudo systemctl start coturn

Add TURN to livekit.yaml

turn:
  enabled: true
  domain: vdo.yourdomain.com
  cert_file: /etc/letsencrypt/live/vdo.yourdomain.com/fullchain.pem
  key_file: /etc/letsencrypt/live/vdo.yourdomain.com/privkey.pem
  tls_port: 5349
  udp_port: 3478
  external_ip: <YOUR_SERVER_PUBLIC_IP>

✅ Verifying LiveKit

1. Health Check

curl -s https://vdo.yourdomain.com/ | jq .
# Expected: {"status":"OK","message":"LiveKit Server"}

2. Test WebRTC Connection

Open the LiveKit WebRTC Tester and enter:

  • WebSocket URL: wss://vdo.yourdomain.com
  • API Key and Secret from your config

You should see a successful connection and be able to publish video.

3. Test from ITG Media App Dashboard

  1. Log into your ITG Media App dashboard
  2. Navigate to the Studio page
  3. Verify you can create a room and join it

🧪 Troubleshooting

Problem Solution
WebSocket connection fails Check Nginx config — ensure Upgrade and Connection headers are set
Guests can't connect (ICE failed) Check TURN server is running and configured in livekit.yaml
Firewall blocking Verify ports 443, 7880-7882, 50000-60000 UDP are open
LiveKit server won't start Check logs: docker logs livekit
SSL certificate error Verify cert paths in Nginx and livekit.yaml
TURN not working Test with: turnutils_uclient -v -t -W <TURN_PASSWORD> -u mediasite vdo.yourdomain.com

⏭️ Next Steps

← Back to Wiki Home

Clone this wiki locally