Skip to main content

LiveKit Configuration (Voice & Video Calls)

Bellamy Book uses LiveKit for real-time voice and video calls. You can use LiveKit Cloud or run your own self-hosted LiveKit server.

Option 1: LiveKit Cloud (easiest)​

  1. Sign up: Go to livekit.io, create an account, and create a project.
  2. In the project dashboard, copy:
    • WebSocket URL (e.g. wss://your-project.livekit.cloud)
    • API Key
    • API Secret

Set in .env​

In your .env:

LiveKit__Url=wss://YOUR_PROJECT.livekit.cloud
LiveKit__ApiKey=your_api_key
LiveKit__ApiSecret=your_api_secret

Replace YOUR_PROJECT, your_api_key, and your_api_secret with the values from the LiveKit dashboard.

Frontend (if you build from source)​

When building the frontend, set the LiveKit URL so the app can connect:

VITE_LIVEKIT_URL=wss://YOUR_PROJECT.livekit.cloud

With pre-built images, the backend returns the LiveKit URL with the token; the frontend uses the URL from runtime config (your .env).

Option 2: Self-hosted LiveKit server​

If you run LiveKit on your own server:

  1. Install LiveKit server

    • Releases, or
    • Docker: docker run --rm -p 7880:7880 -p 7881:7881 livekit/livekit-server --config /etc/livekit.yaml

  2. Configure LiveKit
    Create a config file (e.g. livekit.yaml) with at least:

    • port — e.g. 7880 (clients connect to wss://your-host:7880 or put a reverse proxy in front).
    • rtc — WebRTC port range and TCP port; open these on the firewall.
    • keys — At least one key/secret pair. The API Key and API Secret in your Bellamy Book .env must match one of these.

  3. Set in .env
    Use your LiveKit server URL and the same key/secret as in the server config:

LiveKit__Url=wss://livekit.yourdomain.com
LiveKit__ApiKey=your_key
LiveKit__ApiSecret=your_secret
  1. TLS
    For production, serve LiveKit behind HTTPS (e.g. Traefik or nginx) so the WebSocket URL is wss://livekit.yourdomain.com.

Restart after changes​

docker compose restart api

CSP (Content Security Policy) — important​

The frontend's connect-src directive must allow both schemes for LiveKit:

  • wss://... for the signaling WebSocket
  • https://... for the /rtc/validate token-validation HTTP request

If only wss:// is allowed, video calls fail silently with the misleading error could not establish signal connection: Failed to fetch because the browser blocks the HTTPS validate call before the WebSocket can even start.

LiveKit Cloud users: the default CSP already includes https://*.livekit.cloud wss://*.livekit.cloud, so any LiveKit Cloud project works without further configuration.

Self-hosted LiveKit users: add your LiveKit host to CSP_EXTRA_CONNECT_SRC in .env (both schemes):

CSP_EXTRA_CONNECT_SRC="https://livekit.yourdomain.com wss://livekit.yourdomain.com"

Security​

  • Do not commit LiveKit__ApiKey or LiveKit__ApiSecret to git. Keep them in .env or a secrets manager.
  • Restrict firewall rules so only your app servers and clients can reach the LiveKit ports.

Next steps​