Matrix Synapse — zdecentralizowany komunikator: instalacja serwera

Opublikowano: 10 kwietnia 2026 · Kategoria: VPS

Matrix to zdecentralizowany protokół komunikacji — każdy może postawić własny serwer i rozmawiać z użytkownikami innych serwerów Matrix na całym świecie, bez uzależnienia od jednej firmy. Synapse to oficjalny serwer Matrix napisany w Pythonie. W przeciwieństwie do Mattermost nie wymaga, żeby wszyscy uczestnicy rozmowy byli na tym samym serwerze — wystarczy że ich serwery obsługują federację. Ten artykuł pokazuje instalację Synapse, konfigurację TLS, rejestrację użytkowników przez Element i dodanie bridge'a dla Telegrama.

Instalacja Synapse przez Docker Compose

Docker to najwygodniejsza metoda instalacji Synapse — unika problemów z zależnościami Pythona i ułatwia aktualizacje. Przed startem potrzebujesz domeny z rekordem A wskazującym na VPS oraz otwartych portów 443 (HTTPS) i 8448 (federacja Matrix).

# Utwórz katalog i generuj konfigurację
mkdir -p /opt/synapse && cd /opt/synapse

# Generuj homeserver.yaml
docker run -it --rm \
  -v /opt/synapse:/data \
  -e SYNAPSE_SERVER_NAME=matrix.example.com \
  -e SYNAPSE_REPORT_STATS=no \
  matrixdotorg/synapse:latest generate

# docker-compose.yml
version: '3.8'
services:
  synapse:
    image: matrixdotorg/synapse:latest
    restart: unless-stopped
    volumes:
      - /opt/synapse:/data
    ports:
      - "8008:8008"   # HTTP (Nginx proxuje na HTTPS)
    environment:
      - SYNAPSE_CONFIG_PATH=/data/homeserver.yaml
    depends_on:
      - postgres

  postgres:
    image: postgres:15
    restart: unless-stopped
    environment:
      POSTGRES_USER: synapse
      POSTGRES_PASSWORD: synapse_password
      POSTGRES_DB: synapse
      POSTGRES_INITDB_ARGS: "--encoding=UTF-8 --lc-collate=C --lc-ctype=C"
    volumes:
      - /opt/synapse/postgres:/var/lib/postgresql/data

docker compose up -d

Konfiguracja homeserver.yaml

Plik homeserver.yaml kontroluje wszystkie aspekty serwera. Kluczowe sekcje do skonfigurowania po wygenerowaniu domyślnej konfiguracji:

# homeserver.yaml - kluczowe sekcje

# Identyfikator serwera (NIE ZMIENIAC PO PIERWSZYM URUCHOMIENIU)
server_name: "example.com"  # krótka domena, nie matrix.example.com

# Podlaczenie do PostgreSQL zamiast SQLite
database:
  name: psycopg2
  args:
    user: synapse
    password: synapse_password
    database: synapse
    host: postgres
    port: 5432
    cp_min: 5
    cp_max: 10

# Rejestracja uzytkownikow (wylacz publicznie)
enable_registration: false
registration_requires_token: true

# SMTP dla emaili weryfikacyjnych
email:
  smtp_host: smtp.example.com
  smtp_port: 587
  smtp_user: [email protected]
  smtp_pass: smtp_password
  require_transport_security: true
  notif_from: "%(app)s <[email protected]>"
  app_name: Matrix

# Federacja - limit dla duzych publicznych pokojow
federation_domain_whitelist: []  # puste = wszystkie serwery
# Aby ogra niczyc federacje:
# federation_domain_whitelist:
#   - matrix.org
#   - company.com

Nginx + Let's Encrypt i Well-Known

Matrix wymaga specjalnej konfiguracji Nginx: proxy na port 8008 dla API klienta oraz plik .well-known/matrix/server umożliwiający delegację serwera (server_name ≠ domena Synapse):

server {
  listen 443 ssl;
  server_name matrix.example.com;

  ssl_certificate /etc/letsencrypt/live/matrix.example.com/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/matrix.example.com/privkey.pem;

  # Klient API
  location /_matrix {
    proxy_pass http://127.0.0.1:8008;
    proxy_set_header X-Forwarded-For $remote_addr;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header Host $host;
    client_max_body_size 50M;
  }
}

# Well-known na krotka domene (example.com)
server {
  listen 443 ssl;
  server_name example.com;

  location /.well-known/matrix/server {
    return 200 '{"m.server": "matrix.example.com:443"}';
    add_header Content-Type application/json;
  }

  location /.well-known/matrix/client {
    return 200 '{"m.homeserver":{"base_url":"https://matrix.example.com"}}';
    add_header Content-Type application/json;
    add_header Access-Control-Allow-Origin *;
  }
}

Rejestracja użytkowników i klient Element

Po wyłączeniu publicznej rejestracji (enable_registration: false) tworzysz konta przez CLI Synapse lub tokenami rejestracyjnymi. Element to oficjalny klient webowy i desktopowy dla Matrix:

# Tworzenie uzytkownika przez CLI (wewnątrz kontenera)
docker exec -it synapse register_new_matrix_user \
  -c /data/homeserver.yaml \
  -u admin -p strong_password \
  --admin http://localhost:8008

# Generowanie tokenu rejestracyjnego (Matrix 1.2+)
docker exec -it synapse python -m synapse.app.admin_cmd \
  -c /data/homeserver.yaml generate_registration_token

# Sprawdz status serwera
curl https://matrix.example.com/_matrix/client/versions

# Element Web - uruchom przez Docker
docker run -d \
  --name element \
  -p 8080:80 \
  -v /opt/element/config.json:/app/config.json \
  vectorim/element-web:latest

# config.json dla Element (podstawowy)
# {
#   "default_server_config": {
#     "m.homeserver": {
#       "base_url": "https://matrix.example.com"
#     }
#   }
# }

Bridge Telegram — mautrix-telegram

Bridges pozwalają używać Matrix jako warstwy integrującej wiele komunikatorów. Poniżej instalacja most do Telegrama. Mosty działają jako Application Services zarejestrowane w Synapse:

# docker-compose.yml - dodaj serwis bridge
  mautrix-telegram:
    image: dock.mau.dev/mautrix/telegram:latest
    volumes:
      - /opt/mautrix-telegram:/data
    depends_on:
      - synapse
      - postgres

# Generuj konfigurację
docker run --rm -v /opt/mautrix-telegram:/data \
  dock.mau.dev/mautrix/telegram:latest

# Edytuj /opt/mautrix-telegram/config.yaml
# homeserver.address: https://matrix.example.com
# homeserver.domain: example.com
# appservice.address: http://mautrix-telegram:29317
# telegram.api_id: (z my.telegram.org)
# telegram.api_hash: (z my.telegram.org)

# Generuj registration.yaml dla Synapse
docker run --rm -v /opt/mautrix-telegram:/data \
  dock.mau.dev/mautrix/telegram:latest -g

# Dodaj registration.yaml do homeserver.yaml
# app_service_config_files:
#   - /data/mautrix-telegram-registration.yaml

# Zrestartuj Synapse i uruchom bridge
docker compose restart synapse
docker compose up -d mautrix-telegram

Najczęstsze pytania