Distribuisci Matrix Synapse con Docker Compose e PostgreSQL

Esegui Synapse come progetto Docker Compose con una directory di configurazione persistente e un database PostgreSQL. La configurazione seguente genera le chiavi di firma di Synapse homeserver.yaml, lo connette a PostgreSQL e mantiene il listener HTTP su localhost in modo da poter posizionare HTTPS e la federazione dietro un proxy inverso prima di esporre il server a Internet.

Synapse è il server domestico di Matrix: memorizza account, stanze, eventi e file multimediali per un server. Docker Compose esegue i container di Synapse e PostgreSQL da un singolo file YAML. Questa è una configurazione di partenza per una singola macchina, non un'implementazione pubblica completa di Matrix.

Prima di iniziare

Installa Docker Engine e il plugin Docker Compose, quindi verifica che docker compose versionfunzioni correttamente. Docker Desktop include Compose su Windows e macOS; gli utenti Linux possono installare il plugin Compose dal repository dei pacchetti di Docker. Consulta le istruzioni di installazione di Compose per Docker .

Scegli il nome permanente del server Matrix prima di generare la configurazione. Questo nome compare negli ID utente, ad esempio @alex:matrix.example.org, e la sua modifica successiva non è una normale modifica del nome host. In questo esempio, matrix.example.orgè sia il nome del server Matrix che il nome host pubblico. Per un server pubblico, punta il suo record DNS al tuo host e pianifica un proxy inverso HTTPS. Il listener HTTP generato da Synapse sulla porta 8008 è adatto per i test locali; la documentazione di installazione indica che per un utilizzo pratico è necessario HTTPS.

1. Crea un progetto e un segreto

Sull'host Docker, crea una directory di lavoro e le cartelle persistenti. La synapsecartella conterrà la configurazione generata e la chiave di firma; la cartella data/postgresconterrà i file del database.

mkdir -p ~/matrix-synapse/synapse ~/matrix-synapse/data/postgres
cd ~/matrix-synapse
umask 077
openssl rand -hex 32

Copia l'output del comando in un nuovo .envfile chiamato DB_PASSWORD=.... Mantieni questo file privato ed effettua un backup sicuro. Compose legge .envle sostituzioni nel file Compose; Synapse non espande automaticamente quelle variabili all'interno di homeserver.yaml. Dovrai inserire la stessa password in quella configurazione al passaggio 3.

Visualizzazione a scopo illustrativo nel terminale della directory di un progetto matrix-synapse contenente il file docker-compose.yml, un file di ambiente, una cartella di configurazione di Synapse e una cartella dati.
Una cartella di progetto separa la definizione di Compose, la configurazione di Synapse e i file del database persistente.

2. Definisci i due servizi

Crea docker-compose.ymlnella directory del progetto. Questo esempio utilizza l'immagine ufficiale di Synapse pubblicata da Element HQ e PostgreSQL 16. La porta di Synapse è associata all'interfaccia di loopback anziché a ogni interfaccia di rete. Il controllo di integrità consente a Compose di attendere PostgreSQL prima di avviare Synapse.

services:
  synapse:
    image: ghcr.io/element-hq/synapse:latest
    restart: unless-stopped
    environment:
      SYNAPSE_CONFIG_PATH: /data/homeserver.yaml
    volumes:
      - ./synapse:/data
    ports:
      - "127.0.0.1:8008:8008"
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_USER: synapse
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: synapse
      POSTGRES_INITDB_ARGS: --encoding=UTF-8 --lc-collate=C --lc-ctype=C
    volumes:
      - ./data/postgres:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U synapse -d synapse"]
      interval: 10s
      timeout: 5s
      retries: 5

Inserisci , utilizzando il valore casuale del passaggio 1. Non caricare questo file nel sistema di controllo versione. Se in seguito modifichi la versione principale di PostgreSQL, segui la procedura di aggiornamento di PostgreSQL anziché puntare semplicemente un'immagine più recente a una directory dati esistente DB_PASSWORD=your-generated-value..env

3. Genera la configurazione di Synapse e seleziona PostgreSQL

Genera la configurazione iniziale e la chiave di firma nella synapsedirectory montata. Usa lo stesso nome del server che hai scelto in precedenza. Imposta esplicitamente l'opzione per le statistiche; ecco come fare no.

docker compose run --rm --no-deps \
  -e SYNAPSE_SERVER_NAME=matrix.example.org \
  -e SYNAPSE_REPORT_STATS=no \
  synapse generate

La modalità del contenitore ufficiale generatecrea homeserver.yamlla chiave di firma richiesta. Apri synapse/homeserver.yamle sostituisci la sezione del database SQLite con quanto segue. Sostituisci PASTE_THE_SAME_DB_PASSWORD_HEREcon il valore esatto memorizzato in .env. Questo campo è un valore di configurazione Synapse letterale, non un'interpolazione di Compose.

database:
  name: psycopg2
  args:
    user: synapse
    password: PASTE_THE_SAME_DB_PASSWORD_HERE
    dbname: synapse
    host: db
    port: 5432
    cp_min: 5
    cp_max: 10
Visualizzazione esemplificativa dell'editor homeserver.yaml con PostgreSQL configurato tramite psycopg2, database synapse, host db, porta 5432 e pool di connessioni.
La sezione del database di Synapse punta al nome del servizio Compose, db, sulla porta interna di PostgreSQL.

Mantieni registration_shared_secretprivato il file generato. Synapse lo utilizza per lo strumento di registrazione utenti da riga di comando; chiunque lo ottenga può creare account, inclusi gli amministratori. Lascia la registrazione pubblica disabilitata a meno che tu non intenda offrirla deliberatamente e dopo aver esaminato i relativi controlli anti-abuso.

4. Avvia Synapse e controlla i log

Dalla directory contenente docker-compose.yml, convalida il file Compose e avvia i servizi:

docker compose config
docker compose up -d
docker compose ps
docker compose logs --tail=100 synapse db

Il primo comando verifica che Compose sia in grado di analizzare il file e risolverlo DB_PASSWORD. Il successivo avvia il database e l'homeserver in background. Controlla i log per eventuali errori di connessione al database o file di configurazione mancanti. Poiché questa configurazione monta le cartelle locali tramite bind mount, la configurazione del database e di Synapse persiste anche quando i container vengono ricreati.

Esempio di prompt del terminale con il comando docker compose up -d inserito per avviare lo stack Synapse.
Dopo aver generato e verificato la configurazione, avviare i servizi Synapse e PostgreSQL.

5. Verifica l'endpoint locale e crea un account

Eseguire la richiesta delle versioni del client Matrix dall'host Docker. Una risposta JSON indica che l'API client sta rispondendo; una risposta vuota, un rifiuto della connessione o un errore HTTP indicano che è necessario esaminare i log di Synapse e verificare che la porta 8008 sia in ascolto.

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

Una volta ricevuta la risposta, crea un utente iniziale in modo interattivo. Questo comando richiede un nome utente e una password; scegli "no" per l'amministratore a meno che tu non abbia specificamente bisogno di un account amministratore.

docker compose exec synapse register_new_matrix_user \
  -c /data/homeserver.yaml http://localhost:8008
Esempio di prompt del terminale con una richiesta curl all'endpoint delle versioni del client Matrix di Synapse su localhost porta 8008.
Una risposta positiva all'endpoint delle versioni conferma che Synapse sta rispondendo localmente; questo prompt di esempio mostra il controllo, non il risultato del test.

Rendilo accessibile in sicurezza

La mappatura delle porte solo su localhost è intenzionale: impedisce l'accesso pubblico diretto al listener HTTP non crittografato. Per i client remoti, configurare un reverse proxy con un certificato TLS valido e inoltrare i percorsi Matrix a Synapse. Il proxy deve passare le intestazioni X-Forwarded-Fore X-Forwarded-Proto; nella configurazione del listener generato, abilitare x_forwarded: trueper la porta 8008. Non impostare un listener Synapse containerizzato in modo che si leghi solo a 127.0.0.1, perché ciò impedisce a un container proxy di raggiungerlo. Se anche il reverse proxy è containerizzato, posizionarlo insieme a Synapse su una rete Docker condivisa e instradare il proxy al nome del servizio synapse:8008.

La federazione è separata dall'avvio locale. Gli altri server Matrix devono individuare e raggiungere il tuo server, in genere sulla porta 8448 o tramite individuazione HTTPS delegata. DNS, routing del reverse proxy e tutti i record necessari devono corrispondere al nome del server scelto. Segui la documentazione e le istruzioni di installazione del reverse proxy.well-known di Synapse prima di annunciare un homeserver pubblico. Anche le chiamate vocali e video richiedono un server TURN per una connettività multimediale affidabile.

Se Synapse non riesce a connettersi a PostgreSQL, verificare che hostsia db(il nome del servizio Compose), che entrambe le password corrispondano esattamente e che il contenitore del database sia integro. Se l'endpoint non è raggiungibile, controllare docker compose psi log di Synapse e se un altro servizio sta già utilizzando la porta host 8008. Eseguire il backup sia della directory dei dati di PostgreSQL che della configurazione di Synapse e della chiave di firma; la chiave di firma è essenziale per l'identità del server.

Per i dettagli sulla configurazione di PostgreSQL, consultare la guida PostgreSQL di Synapse . Per le opzioni del container e la creazione degli utenti, consultare la documentazione ufficiale di Synapse per Docker .

Lascia un commento

Distribuisci Matrix Synapse con Docker Compose e PostgreSQL

Distribuisci Matrix Synapse con Docker Compose e PostgreSQL

Configura un server domestico Synapse persistente con Docker Compose, PostgreSQL, una configurazione privata ed effettua i controlli necessari prima di esporlo tramite HTTPS.

Personalizza il tema e l'immagine coordinata di Element Web

Imposta un nome personalizzato, colori e elementi di accesso per la tua implementazione di Element Web, tenendo presente quali parti rimangono a marchio Element.

Aumenta il limite di file di Systemd in Synapse senza dover fare supposizioni.

Aumenta il limite di file di Systemd in Synapse senza dover fare supposizioni.

Diagnostica se Synapse ha raggiunto il limite di file aperti per processo, imposta un comando systemd specifico per il servizio o il worker corretto e verifica il limite effettivo.

Element mostra "Decrittazione non riuscita"? Ripristina la chiave della stanza mancante

Element mostra "Decrittazione non riuscita"? Ripristina la chiave della stanza mancante

Scopri se l'errore è limitato a un singolo browser o a un singolo evento, quindi utilizza la chiave di ripristino di Element o un dispositivo attendibile senza rischiare di perdere la cronologia crittografata rimanente.

Elimina i vecchi messaggi e file multimediali di Synapse senza perdere dati.

Utilizza le API di Synapse per la cancellazione della cronologia e dei supporti di memorizzazione o le impostazioni di conservazione per rimuovere in modo sicuro i dati obsoleti, quindi verifica il completamento dell'operazione e il recupero dello spazio su disco.

Crea un bot di tipo Matrix Echo in Python con Simple-Matrix-Bot-Lib

Crea un bot di tipo Matrix Echo in Python con Simple-Matrix-Bot-Lib

Installa la libreria corrente, collega un account Matrix dedicato ed esegui un piccolo bot !echo con una gestione più sicura delle credenziali e un test chiaro.

Collega Matrix a WhatsApp, Telegram e Discord con bridge separati.

Collega Matrix a WhatsApp, Telegram e Discord con bridge separati.

Configura tre bridge Mautrix con registrazioni, accessi e test separati, ed evita sorprese legate alla rete Docker, alle policy degli account e alla sincronizzazione.

Recupera spazio su disco in Synapse Media senza compromettere i file condivisi.

Scopri cosa occupa spazio di archiviazione in Synapse, imposta la conservazione sicura dei file multimediali e svuota la cache remota senza eliminare i file direttamente dal disco.

Disattivare gli utenti Matrix inattivi senza eliminare la cronologia delle stanze

Disattivare gli utenti Matrix inattivi senza eliminare la cronologia delle stanze

Esamina l'attività del dispositivo, disattiva gli account Synapse inattivi confermati tramite l'API di amministrazione e scopri cosa rimuove effettivamente il flag di cancellazione opzionale.

Ridurre la pressione sulla memoria di PostgreSQL in Matrix Synapse

Scopri se l'utilizzo della memoria PostgreSQL deriva da query, buffer condivisi, connessioni o operazioni di manutenzione, quindi apporta modifiche mirate e compatibili con Synapse.