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.COMwith your actual domain.server_namecannot 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
productionDocker network, remove thenetworks: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
- DNS: Create an
Arecord forlivekit.DOMAIN.COMpointing to your public IP.- Cloudflare users: Set
livekit.DOMAIN.COMto DNS only (Grey Cloud).
- Cloudflare users: Set
- Router / Modem Port Forwarding: Forward these ports to your Docker host's LAN IP:
7881TCP50100–50200UDP
- 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
Option A: Via CLI (Recommended when registration_requires_token: true)
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
- Web: app.element.io or app.cinny.in
- Windows / macOS / Linux: Element Desktop / Cinny Desktop
- iOS: Element X (App Store) or Element Classic
- Android: Element X (Google Play / F-Droid) or Element Classic