ITGOIT - Wiki

Matrix

Matrix with LiveKit Calls

1. Initial Synapse Setup

Create the directory and generate the initial Synapse configuration:

cd /home/myusername/docker
mkdir -p synapse && cd "$_"
docker run -it --rm \
  -v ./data:/data \
  -e SYNAPSE_SERVER_NAME=chat.DOMAIN.COM \
  -e SYNAPSE_REPORT_STATS=no \
  ghcr.io/element-hq/synapse:latest generate

Note: Replace chat.DOMAIN.COM with your actual domain. server_name cannot be changed later without resetting the database.

2. Configure homeserver.yaml

Open the configuration file:

nano /home/myusername/docker/synapse/data/homeserver.yaml

Update or add the following settings (keep your generated signing_key_path, macaroon_secret_key, form_secret, and registration_shared_secret intact):

## Server ##
server_name: "chat.DOMAIN.COM"
public_baseurl: "https://chat.DOMAIN.COM/"
serve_server_wellknown: true

# Recommended defaults for modern Synapse
default_room_version: "12"
enable_search: true
max_event_delay_duration: 24h

## Federation & Public Directory ##
#allow_public_rooms_over_federation: true

## Presence ##
# Set to false to reduce server load on small instances
#presence:
#  enabled: false

## Registration ##
enable_registration: true
registration_requires_token: true

## Media & Room Limits ##
limit_remote_rooms:
  enabled: true
  complexity: 1.0
  admins_can_join: true

forgotten_room_retention_period: 28d

media_retention:
  remote_media_lifetime: 30d

## User Directory ##
user_directory:
  enabled: true
  prefer_local_users: true
  exclude_remote_users: true

## Email (Optional - remove/comment out if not using SMTP) ##
email:
  smtp_host: mail.DOMAIN.COM
  smtp_port: 587
  smtp_user: "[email protected]"
  smtp_pass: "REPLACE_WITH_YOUR_EMAIL_PASSWORD"
  require_transport_security: true
  notif_from: "Your Friendly %(app)s homeserver <[email protected]>"
  app_name: "my_branded_matrix_server"
  enable_notifs: true
  notif_for_new_users: true
  notif_delay_before_mail: 10m
  invite_client_location: https://app.element.io

## MatrixRTC / LiveKit (Added for voice & video calls - see Section 4) ##
matrix_rtc:
  transports:
    - type: livekit
      url: wss://livekit.DOMAIN.COM
      livekit_service_url: https://livekit.DOMAIN.COM

experimental_features:
  msc4143_enabled: true

Validate your homeserver.yaml before starting Synapse:

docker compose run --rm --no-deps --entrypoint python synapse -m synapse.config -c /data/homeserver.yaml

3. Configure docker-compose.yml (Synapse + LiveKit)

Create or edit /home/myusername/docker/synapse/docker-compose.yml:

services:
  synapse:
    image: ghcr.io/element-hq/synapse:latest
    container_name: synapse
    restart: unless-stopped
    volumes:
      - ./data:/data
    ports:
      - "8150:8008"
    networks:
      - production

  lk-jwt-service:
    image: ghcr.io/element-hq/lk-jwt-service:latest
    container_name: lk-jwt-service
    restart: unless-stopped
    environment:
      LIVEKIT_JWT_BIND: :8081
      LIVEKIT_URL: wss://livekit.DOMAIN.COM
      LIVEKIT_FULL_ACCESS_HOMESERVERS: chat.DOMAIN.COM
      LIVEKIT_KEY: REPLACE_WITH_LIVEKIT_KEY
      LIVEKIT_SECRET: REPLACE_WITH_LIVEKIT_SECRET
    ports:
      - "8081:8081"
    networks:
      - production

  livekit:
    image: livekit/livekit-server:latest
    container_name: livekit
    command: --config /etc/livekit.yaml
    restart: unless-stopped
    volumes:
      - ./livekit/livekit.yaml:/etc/livekit.yaml:ro
    network_mode: "host"

networks:
  production:
    external: true

Note: If you do not use an external production Docker network, remove the networks: blocks above.

4. Set Up LiveKit & MatrixRTC (Voice & Video Calls)

Element Web, Element Desktop, Element X, and Cinny use MatrixRTC + LiveKit for 1-on-1 calls, group calls, voice rooms, and screen sharing.

4.1 Generate LiveKit API Keys

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

Copy the generated API Key and API Secret into both docker-compose.yml (under lk-jwt-service) and livekit/livekit.yaml below.

4.2 Create livekit.yaml

mkdir -p /home/myusername/docker/synapse/livekit
nano /home/myusername/docker/synapse/livekit/livekit.yaml
port: 7880
bind_addresses:
  - ""
rtc:
  tcp_port: 7881
  port_range_start: 50100
  port_range_end: 50200
  use_external_ip: true
  enable_loopback_candidate: false
keys:
  REPLACE_WITH_LIVEKIT_KEY: REPLACE_WITH_LIVEKIT_SECRET
room:
  auto_create: false

4.3 DNS, Router Port Forwarding & Firewall

  1. DNS: Create an A record for livekit.DOMAIN.COM pointing to your public IP.
    • Cloudflare users: Set livekit.DOMAIN.COM to DNS only (Grey Cloud).
  2. Router / Modem Port Forwarding: Forward these ports to your Docker host's LAN IP:
    • 7881 TCP
    • 50100–50200 UDP
  3. Host Firewall (if using UFW):
    ufw allow 7881/tcp
    ufw allow 50100:50200/udp
    

4.4 Reverse Proxy Setup (Traefik Example)

Route /sfu/get, /healthz, and /get_token to lk-jwt-service (:8081, higher priority), and everything else on livekit.DOMAIN.COM to livekit (:7880):

  routers:
    synapse:
      entryPoints:
        - https
      rule: "Host(`chat.DOMAIN.COM`)"
      service: synapse
      middlewares:
        - "securityHeadersPrivate"

    livekit-jwt:
      entryPoints:
        - https
      rule: "Host(`livekit.DOMAIN.COM`) && (PathPrefix(`/sfu/get`) || PathPrefix(`/healthz`) || PathPrefix(`/get_token`))"
      priority: 100
      service: livekit-jwt
      middlewares:
        - "securityHeadersPrivate"

    livekit-ws:
      entryPoints:
        - https
      rule: "Host(`livekit.DOMAIN.COM`)"
      priority: 50
      service: livekit-ws
      middlewares:
        - "securityHeadersPrivate"

  services:
    synapse:
      loadBalancer:
        servers:
          - url: http://SERVER_LAN_IP:8150

    livekit-jwt:
      loadBalancer:
        servers:
          - url: http://SERVER_LAN_IP:8081

    livekit-ws:
      loadBalancer:
        servers:
          - url: http://SERVER_LAN_IP:7880

4.5 Start & Verify

cd /home/myusername/docker/synapse
docker compose up -d

Check that https://livekit.DOMAIN.COM/healthz returns 200 OK, then test a call between two devices (ideally with one on mobile 4G/5G to verify port forwarding).

5. Create Your First Admin Account

docker exec -it synapse register_new_matrix_user -c /data/homeserver.yaml http://localhost:8008

Follow the prompts and answer yes when asked to make the user an admin.

Option B: Promote an Existing Account via SQLite

If you already registered an account via Element (using a registration token), promote it to admin in SQLite:

cd /home/myusername/docker/synapse/data
apt install sqlite3
sqlite3 homeserver.db
SELECT name, admin FROM users;
UPDATE users SET admin=1 WHERE name='@myusername:chat.DOMAIN.COM';
.quit

6. Matrix Clients