Home
» Come fare
»
Distribuisci Matrix Synapse con Docker Compose e PostgreSQL
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.
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.
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.
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.
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.
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.
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.
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.
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.