Jak zainstalować Synapse Matrix Server z Docker Compose

Przykład ilustrujący: Wyobraź sobie małą grupę wolontariuszy, która chce mieć własny serwer domowy Matrix pod adresem chat.example.com. To hipotetyczna konfiguracja, a nie raport z przetestowanego serwera. Te same kroki można zaadaptować do rzeczywistej domeny, ale należy ostrożnie dobrać nazwę serwera Matrix: Synapse używa jej w identyfikatorach użytkowników i nie można jej później zmienić.

Ten przewodnik opisuje tworzenie usługi Synapse i bazy danych PostgreSQL za pomocą Docker Compose. Oficjalny obraz Dockera firmy Synapse domyślnie uruchamia się z bazą SQLite, co jest wygodne w przypadku jednorazowego testu; dokumentacja Dockera firmy Synapse zaleca PostgreSQL do zastosowań produkcyjnych. Dlatego przykład najpierw generuje konfigurację Synapse, zmienia ustawienia bazy danych na PostgreSQL, a następnie uruchamia oba kontenery. Oficjalny obraz to ghcr.io/element-hq/synapse. Instrukcje i szczegóły obrazu zostały sprawdzone pod kątem aktualnej oficjalnej dokumentacji z 6 października 2026 r.; tagi obrazów i obsługiwane wersje oprogramowania mogą ulec zmianie, dlatego przed wdrożeniem długoterminowym należy zapoznać się z powiązaną dokumentacją.

Czego potrzebujesz przed instalacją

• Serwer Linux lub inny host obsługujący Dockera z zainstalowanym Docker Engine i wtyczką Docker Compose. Sprawdź, czy Compose jest dostępny docker compose version. Postępuj zgodnie z oficjalnymi instrukcjami instalacji Dockera dla swojego systemu operacyjnego.
• Domena lub subdomena wskazująca na serwer. W tym przykładzie chat.example.comjest to nazwa serwera Synapse, więc identyfikatory użytkowników lokalnych będą wyglądać następująco @alex:chat.example.com: . Zastąp ją domeną, którą kontrolujesz, przed wygenerowaniem konfiguracji.
• Odwrotny serwer proxy lub inna metoda zakończenia protokołu TLS do użytku publicznego. Domyślny nasłuchiwacz HTTP w Synapse na porcie 8008nie jest punktem końcowym HTTPS skierowanym do Internetu. Ten przykład Compose wiąże ten port z interfejsem pętli zwrotnej hosta, aby odwrotny serwer proxy na tym samym komputerze mógł się z nim połączyć.

Nazwa w polu „In” SYNAPSE_SERVER_NAMEniekoniecznie musi być adresem URL każdego połączenia klienta. Jeśli chcesz używać krótszych identyfikatorów, na przykład @alex:example.compodczas obsługi klientów z adresu chat.example.com, wymaga to przemyślanej konfiguracji domeny i wykrywania. Zdecyduj o tym przed utworzeniem kont.

1. Utwórz katalog roboczy i hasło do bazy danych

Na serwerze utwórz katalog dla projektu Compose i stałych plików Synapse:

mkdir -p ~/matrix-synapse/data
cd ~/matrix-synapse

Utwórz plik lokalny .env, który będzie odczytywany przez Docker Compose. Wygeneruj długie, losowe hasło za pomocą menedżera haseł lub lokalnego, bezpiecznego generatora i umieść je po POSTGRES_PASSWORD=. W tym przykładzie użyj liter i cyfr, aby uniknąć późniejszych problemów z cytowaniem w YAML. Nie zatwierdzaj tego pliku w publicznym repozytorium i ogranicz jego uprawnienia:

umask 077
nano .env

Plik powinien zawierać jedną linię, na przykład POSTGRES_PASSWORD=replace-with-a-long-random-value. Tekst jest symbolem zastępczym, a nie hasłem do ponownego użycia. Zachowaj hasło dostępne do konfiguracji bazy danych Synapse w kroku 3.

2. Zdefiniuj usługi Synapse i PostgreSQL

Utwórz compose.yamlw katalogu projektu:

services:
  postgres:
    image: postgres:16
    restart: unless-stopped
    environment:
      POSTGRES_USER: synapse
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD in .env}
      POSTGRES_DB: synapse
      POSTGRES_INITDB_ARGS: "--encoding=UTF8 --locale=C"
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U synapse -d synapse"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 20s

  synapse:
    image: ghcr.io/element-hq/synapse:latest
    restart: unless-stopped
    depends_on:
      postgres:
        condition: service_healthy
    environment:
      SYNAPSE_SERVER_NAME: chat.example.com
      SYNAPSE_REPORT_STATS: "no"
    volumes:
      - ./data:/data
    ports:
      - "127.0.0.1:8008:8008"

volumes:
  postgres_data:

Zastąp chat.example.comwybraną nazwą serwera. Kontrola stanu PostgreSQL pozwala Compose poczekać na zgłoszenie gotowości bazy danych przed uruchomieniem Synapse. Podany wolumin bazy danych i ./datakatalog zamontowany na hoście przetrwają zamianę kontenerów; samo usunięcie kontenerów nie powoduje ich usunięcia. Unikaj tej opcji, docker compose down -vchyba że celowo chcesz usunąć wolumin bazy danych.

Przykład ma :latestna celu uproszczenie pierwszego pobrania. W przypadku serwera zarządzanego wybierz i zapisz konkretny tag wydania Synapse lub skrót obrazu, a następnie zaktualizuj go w ramach zaplanowanego procesu aktualizacji po zapoznaniu się z informacjami o wydaniu. Nie zakładaj, że latesttag zmienny zachowa tę samą wersję.

3. Wygeneruj konfigurację Synapse i skieruj ją do PostgreSQL

Uruchom oficjalny obraz raz w trybie generowania konfiguracji. Ponieważ Compose montuje się ./dataw /data, wygenerowany klucz konfiguracji i podpisu pozostaje na hoście:

docker compose run --rm synapse generate

To polecenie wykorzystuje nazwę serwera i anonimowe statystyki wybrane ze środowiska Compose. Synapse tworzy również klucz podpisu; należy go przechowywać w katalogu danych i uwzględniać w chronionych kopiach zapasowych. Nie należy go ponownie generować ani usuwać podczas standardowej aktualizacji kontenera.

Otwórz data/homeserver.yamli zastąp wygenerowaną database:sekcję następującymi ustawieniami. Użyj dokładnego hasła z .envsymbolu zastępczego:

database:
  name: psycopg2
  args:
    user: synapse
    password: 'replace-with-the-same-random-value'
    dbname: synapse
    host: postgres
    port: 5432
    cp_min: 5
    cp_max: 10

Zachowaj otaczające wcięcie YAML i upewnij się, że jest tylko jedna aktywna database:sekcja. Nazwa hosta postgresto nazwa usługi Compose, którą kontenery mogą rozwiązywać w swojej współdzielonej sieci domyślnej. Konfiguracja używa udokumentowanej nazwy silnika PostgreSQL firmy Synapse, psycopg2, oraz nazw argumentów bazy danych, w tym dbname.

W tym prostym przykładzie hasło do bazy danych pojawia się zarówno w konfiguracji Synapse, jak i w .envpliku chronionym. Traktuj oba pliki jako sekrety, ogranicz dostęp do hosta i zastosuj dedykowane podejście do zarządzania sekretami, jeśli środowisko wdrożeniowe tego wymaga. Nie wklejaj prawdziwego hasła do logów, zrzutów ekranu ani zgłoszeń do pomocy technicznej.

4. Uruchom Synapse za pomocą Docker Compose

Uruchom stos w tle:

docker compose up -d

Sprawdź stan usługi i przeczytaj logi uruchamiania:

docker compose ps
docker compose logs --tail=100 synapse

Poczekaj, aż Synapse zakończy konfigurację bazy danych po pierwszym uruchomieniu. Uruchomiony kontener oznacza jedynie, że jego proces jest aktywny; przed kontynuacją sprawdź logi pod kątem błędów konfiguracji, bazy danych lub uprawnień. Aby monitorować logi w miarę ich napływania, użyj docker compose logs -f synapsei naciśnij Ctrl+C, aby zatrzymać śledzenie ich bez zatrzymywania kontenera.

5. Zweryfikuj lokalne API i skonfiguruj dostęp publiczny

Z hosta Docker zażądaj punktu końcowego wersji interfejsu API klienta Synapse:

curl -fsS http://127.0.0.1:8008/_matrix/client/versions

Pomyślna odpowiedź to kod JSON opisujący obsługiwane wersje API klienta Matrix. Potwierdza to, że nasłuchiwacz HTTP odpowiada lokalnie; nie dowodzi to jednak, że DNS, HTTPS ani federacja są poprawnie skonfigurowane.

Skonfiguruj odwrotny serwer proxy hosta, aby przekierowywał żądania dla wybranej domeny http://127.0.0.1:8008i uzyskiwał prawidłowy certyfikat TLS. Zachowaj ścieżkę żądania Matrix podczas korzystania z serwera proxy. Następnie sprawdź publiczny punkt końcowy:

curl -fsS https://chat.example.com/_matrix/client/versions

Zastąp przykładową nazwę hosta swoją prawdziwą nazwą. Jeśli klienci muszą wykryć serwer domowy z oddzielnej domeny identyfikatora użytkownika, opublikuj odpowiednie rekordy wykrywania znanych rekordów Matrix dla tego projektu. Federacja wymaga również prawidłowego routingu publicznego i DNS; 8008samo otwarcie portu lokalnego nie zapewnia pełnego wdrożenia publicznego. Przed udostępnieniem usługi zapoznaj się z wytycznymi Synapse dotyczącymi odwrotnego proxy i federacji.

6. Utwórz pierwsze konto administratora

Synapse domyślnie wyłącza rejestrację publiczną. W przypadku serwera prywatnego należy zachować to ustawienie domyślne i utworzyć konta z poziomu wiersza poleceń. Tymczasowo dodaj registration_shared_secretwartość strong do data/homeserver.yaml, a następnie uruchom ponownie Synapse, aby odczytał zmianę:

docker compose restart synapse

Uruchom narzędzie rejestracyjne w kontenerze. Pojawi się monit o podanie nazwy użytkownika i hasła; ustawienie --admintworzy pierwszego administratora:

docker compose exec synapse register_new_matrix_user \
  http://localhost:8008 \
  -c /data/homeserver.yaml \
  --admin

Po utworzeniu konta usuń je registration_shared_secretz konfiguracji i ponownie uruchom Synapse. Pozostawienie skonfigurowanego hasła pozwala każdemu, kto je uzyska, na rejestrację kont standardowych lub administratora za pośrednictwem interfejsu rejestracji. Zaloguj się za pomocą klienta Matrix obsługującego niestandardowe serwery domowe, używając adresu URL serwera dostarczonego przez odwrotny serwer proxy.

Kopie zapasowe, aktualizacje i typowe poprawki

• Utwórz kopię zapasową właściwych danych: zatrzymaj lub regularnie twórz migawki danych PostgreSQL i twórz kopie zapasowe ./data, w tym konfigurację, nośniki i klucz podpisu. Sama kopia compose.yamlnie przywróci serwera domowego. Przechowuj kopie zapasowe w innym miejscu niż serwer i okresowo sprawdzaj, czy możesz je odczytać.
• Synapse nie może zapisać do /data: sprawdź własność hosta i uprawnienia do niego ./data. Użytkownik środowiska uruchomieniowego oficjalnego obrazu potrzebuje uprawnień do odczytu konfiguracji i zapisu danych. Dostosuj własność hosta ostrożnie, zamiast ustawiać katalog jako dostępny do zapisu dla wszystkich.
• Połączenie z bazą danych nie powiodło się: sprawdź, czy konfiguracja bazy danych używa host: postgres, czy hasło jest zgodne .envi czy docker compose logs postgresbaza danych jest prawidłowa. Stan gotowości Compose depends_onzmniejsza liczbę wyścigów startowych, ale nie naprawia nieprawidłowych danych uwierzytelniających.
• Lokalny interfejs API działa, ale klienci nie mogą się połączyć: sprawdź rekord DNS, certyfikat TLS, serwer proxy odwrotnego (reverse-proxy upstream) i rekordy wykrywania dla wybranej konfiguracji domeny. Mapowanie portów tylko w pętli zwrotnej jest celowe dla serwera proxy tego samego hosta; serwer proxy w innym kontenerze wymaga współdzielonej sieci Docker i innego projektu routingu.
• Aktualizacja: najpierw wykonaj kopię zapasową, zapoznaj się z informacjami o wydaniu Synapse, zaktualizuj przypięty znacznik obrazu i utwórz usługę docker compose pullponownie za pomocą docker compose up -d. Zachowaj ten sam katalog danych, wolumin bazy danych, nazwę serwera i klucz podpisu.

W przykładowej konfiguracji dla grupy wolontariuszy instalacja kończy się dopiero po udzieleniu odpowiedzi przez lokalny punkt końcowy, udzieleniu odpowiedzi przez punkt końcowy HTTPS za pośrednictwem serwera proxy i możliwości zalogowania się administratora przy użyciu docelowej domeny Matrix ID. Te kontrole są praktycznymi wskaźnikami udanego wdrożenia; nie zastępują one jednak weryfikacji zabezpieczeń, kopii zapasowych, federacji i wymagań operacyjnych przed zaproszeniem szerszej społeczności.

Oficjalne referencje

• Instrukcje instalacji Synapse i wskazówki dotyczące nazwy serwera
• Oficjalny obraz Synapse Docker README
• Odniesienie do konfiguracji Synapse
• Odwrotne prowadzenie proxy synaptyczne
• Instalacja Docker Engine
• Kolejność uruchamiania i kontrole stanu Docker Compose