Deploying a Private Matrix Synapse Messaging Network with End-to-End Encryption and Turn Servers

Points clés

• Disable federation for a private network. Set federation_domain_whitelist to empty and block inbound federation traffic.
• Enforce end-to-end encryption. Configure the server to reject unencrypted rooms and require device verification.
• Deploy a TURN server. coturn relays voice and video when direct peer connections fail.
• Store media locally. Use the local media store with a retention policy rather than an external S3 backend for small deployments.
• Set up a reverse proxy. Nginx or Caddy terminates TLS and routes Matrix and TURN traffic.
• Configure well-known endpoints. .well-known/matrix/server and /client tell clients where to connect.
• Back up the database. PostgreSQL holds all messages and keys; automate dumps and test restores.
• Monitor federation attempts. Even with federation disabled, log and alert on any inbound federation traffic.

Architecture

Clients connect through a reverse proxy to Synapse, which stores messages and keys in PostgreSQL. Media lives on local disk. TURN handles NAT traversal for calls. With federation disabled, the network is a closed island with full control over membership and data.

Production configuration

server_name: chat.example.com
listeners:
  - port: 8008
    tls: false
    bind_addresses: ['127.0.0.1']
    type: http
    resources:
      - names: [client, federation]
database:
  name: psycopg2
  args:
    user: synapse
    password: change-me
    database: synapse
    host: 127.0.0.1
federation_domain_whitelist: []
encryption_enabled_by_default_for_room_type: all
media_store_path: /var/lib/matrix-synapse/media
max_upload_size: 100M

listening-port=3478
fingerprint
lt-cred-mech
use-auth-secret
static-auth-secret=change-me
realm=chat.example.com
total-quota=100
cert=/etc/letsencrypt/live/chat.example.com/fullchain.pem
pkey=/etc/letsencrypt/live/chat.example.com/privkey.pem

server {
  listen 443 ssl http2;
  server_name chat.example.com;
  location /_matrix/ {
    proxy_pass http://127.0.0.1:8008;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $remote_addr;
  }
  location /.well-known/matrix/ {
    alias /var/www/matrix-well-known/;
  }
}

Edge cases from production

• E2EE key backup must be enabled by users; server-side recovery is not possible by design.
• Media retention policies delete files but leave database references; run the media cleanup job regularly.
• TURN credentials expire; clients must fetch fresh credentials from Synapse before each call.
• Federation disabled means no external users; plan membership provisioning via SSO or manual invites.

Questions fréquentes