Come installare Synapse Matrix Server con Docker Compose

Esempio illustrativo: Immaginate un piccolo gruppo di volontari che desidera un proprio server Matrix all'indirizzo chat.example.com. Questa è una configurazione ipotetica, non la descrizione di un server testato. Gli stessi passaggi possono essere adattati a un dominio reale, ma scegliete con attenzione il nome del server Matrix: Synapse lo utilizza negli ID utente e non può essere modificato in seguito.

Questa guida crea un servizio Synapse e un database PostgreSQL con Docker Compose. L'immagine Docker ufficiale di Synapse inizia con SQLite per impostazione predefinita, il che è comodo per una prova temporanea; la documentazione Docker di Synapse raccomanda PostgreSQL per gli ambienti di produzione. L'esempio, quindi, genera prima la configurazione di Synapse, modifica le impostazioni del database in PostgreSQL e poi avvia entrambi i container. L'immagine ufficiale è ghcr.io/element-hq/synapse. Le istruzioni e i dettagli dell'immagine sono stati verificati rispetto alla documentazione ufficiale corrente il 6 ottobre 2026; i tag dell'immagine e le versioni del software supportate possono cambiare, quindi si consiglia di consultare la documentazione collegata prima di una distribuzione a lungo termine.

Cosa ti serve prima dell'installazione

• Un server Linux o un altro host compatibile con Docker, con Docker Engine e il plugin Docker Compose installati. Verifica la disponibilità di Compose con docker compose version. Segui le istruzioni di installazione ufficiali di Docker per il tuo sistema operativo.
• Un dominio o sottodominio che punta al server. In questo esempio, chat.example.comè il nome del server Synapse, quindi gli ID utente locali avranno un aspetto simile a @alex:chat.example.com. Sostituiscilo con un dominio di tua proprietà prima di generare la configurazione.
• Un proxy inverso o un altro metodo di terminazione TLS per uso pubblico. Il listener HTTP predefinito di Synapse sulla porta 8008non è un endpoint HTTPS accessibile da Internet. Questo esempio di Compose associa tale porta all'interfaccia di loopback dell'host in modo che un proxy inverso sulla stessa macchina possa raggiungerla.

Il nome in SYNAPSE_SERVER_NAMEnon è necessariamente l'URL di ogni connessione client. Se si desiderano ID più brevi, ad esempio, @alex:example.comquando si servono client da chat.example.com, ciò richiede una configurazione specifica del dominio e del rilevamento. Decidere questo aspetto prima di creare gli account.

1. Creare una directory di lavoro e una password per il database.

Sul server, crea una directory per il progetto Compose e per i file persistenti di Synapse:

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

Crea un file locale .envche Docker Compose possa leggere. Genera una password lunga e casuale utilizzando un gestore di password o un generatore sicuro locale e inseriscila dopo POSTGRES_PASSWORD=. Per questo esempio, usa lettere e numeri per evitare problemi di virgolette in YAML in seguito. Non caricare questo file in un repository pubblico e limitane i permessi:

umask 077
nano .env

Il file dovrebbe contenere una sola riga, ad esempio POSTGRES_PASSWORD=replace-with-a-long-random-value. Il testo è un segnaposto, non una password da riutilizzare. Conserva la password per la configurazione del database Synapse al passaggio 3.

2. Definire i servizi Synapse e PostgreSQL

Creare compose.yamlnella directory del progetto:

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:

Sostituisci chat.example.comcon il nome del server finale che hai scelto. Il controllo di integrità di PostgreSQL consente a Compose di attendere che il database segnali di essere pronto prima di avviare Synapse. Il volume del database denominato e la ./datadirectory montata sull'host sopravvivono alla sostituzione del container; la sola rimozione dei container non li cancella. Evita di farlo docker compose down -va meno che tu non voglia eliminare intenzionalmente il volume del database.

L'esempio serve :latesta semplificare il primo pull. Per un server gestito, selezionare e registrare uno specifico tag di rilascio di Synapse o un digest dell'immagine, quindi aggiornarlo tramite un processo di aggiornamento pianificato dopo aver esaminato le note di rilascio. Non dare per scontato che il latesttag modificabile mantenga la stessa versione.

3. Genera la configurazione di Synapse e configurala per PostgreSQL

Esegui l'immagine ufficiale una volta nella sua modalità di generazione della configurazione. Poiché Compose viene montato ./datain /data, la configurazione generata e la chiave di firma rimangono sull'host:

docker compose run --rm synapse generate

Questo comando utilizza il nome del server e l'opzione per le statistiche anonime dall'ambiente Compose. Synapse crea anche una chiave di firma; conservala nella directory dei dati e includila nei backup protetti. Non rigenerarla né eliminarla durante un normale aggiornamento del container.

Apri data/homeserver.yamle sostituisci la database:sezione generata con le seguenti impostazioni. Utilizza la password esatta al .envposto del segnaposto:

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

Mantieni la rientranza YAML circostante e assicurati che ci sia una sola database:sezione attiva. L'hostname postgresè il nome del servizio Compose, che i container possono risolvere sulla loro rete predefinita condivisa. La configurazione utilizza il nome del motore PostgreSQL documentato da Synapse, psycopg2e i nomi degli argomenti del database, incluso dbname.

In questo piccolo esempio, la password del database compare sia nella configurazione di Synapse che nel .envfile protetto. Trattate entrambi i file come segreti, limitate l'accesso dall'host e utilizzate un approccio dedicato alla gestione dei segreti se il vostro ambiente di distribuzione lo richiede. Non incollate la password reale nei log, negli screenshot o nelle richieste di supporto.

4. Avvia Synapse con Docker Compose

Avvia lo stack in background:

docker compose up -d

Verifica lo stato del servizio e leggi i log di avvio:

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

Attendi che Synapse completi la configurazione iniziale del database. Un container in esecuzione significa solo che il suo processo è attivo; controlla i log per individuare errori di configurazione, del database o di autorizzazione prima di procedere. Per visualizzare i log man mano che arrivano, usa docker compose logs -f synapsee premi Ctrl+Cper interrompere il monitoraggio senza arrestare il container.

5. Verificare l'API locale e configurare l'accesso pubblico

Dall'host Docker, richiedere l'endpoint delle versioni dell'API client di Synapse:

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

Una risposta positiva è un file JSON che descrive le versioni supportate dell'API client di Matrix. Ciò conferma che il listener HTTP sta rispondendo localmente; non dimostra tuttavia che DNS, HTTPS o la federazione siano configurati correttamente.

Configura il reverse proxy dell'host per inoltrare le richieste per il dominio scelto http://127.0.0.1:8008e ottenere un certificato TLS valido. Mantieni il percorso di richiesta Matrix durante il proxy. Quindi controlla l'endpoint pubblico:

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

Sostituisci il nome host di esempio con quello reale. Se i client devono individuare l'homeserver da un dominio con ID utente separato, pubblica i record di rilevamento noti di Matrix appropriati per tale configurazione. La federazione richiede anche un routing pubblico e un DNS corretti; la 8008sola apertura della porta locale non garantisce una distribuzione pubblica completa. Consulta le linee guida di Synapse relative al reverse proxy e alla federazione prima di esporre il servizio.

6. Creare il primo account amministratore

Synapse disabilita la registrazione pubblica per impostazione predefinita. Per un server privato, mantieni questa impostazione predefinita e crea gli account dalla riga di comando. Aggiungi temporaneamente un registration_shared_secretvalore forte a data/homeserver.yaml, quindi riavvia Synapse in modo che applichi la modifica:

docker compose restart synapse

Esegui lo strumento di registrazione all'interno del container. Richiede un nome utente e una password; impostando questo, --adminviene creato il primo amministratore:

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

Dopo aver creato l'account, rimuoverlo registration_shared_secretdalla configurazione e riavviare Synapse. Lasciare il segreto configurato consente a chiunque lo ottenga di registrare account standard o di amministratore tramite l'interfaccia di registrazione. Accedere tramite un client Matrix che supporti home server personalizzati, utilizzando l'URL del server fornito dal proxy inverso.

Backup, aggiornamenti e correzioni comuni

• Esegui il backup dei dati corretti: interrompi o crea snapshot regolari dei dati di PostgreSQL ed esegui il backup ./data, inclusi configurazione, supporti e chiave di firma. Una compose.yamlsemplice copia non è sufficiente a ripristinare il server domestico. Archivia i backup in una posizione separata dal server e verifica periodicamente di poterli leggere.
• Synapse non può scrivere su /data: verificare la proprietà dell'host e i permessi su ./data. L'utente runtime dell'immagine ufficiale necessita dei permessi per leggere la configurazione e scrivere i dati. Regolare attentamente la proprietà dell'host anziché rendere la directory scrivibile da tutti.
• La connessione al database non riesce: verifica che la configurazione del database utilizzi host: postgres, che la password corrisponda a .enve che docker compose logs postgresmostri un database integro. La condizione di prontezza di Compose depends_onriduce le condizioni di gara all'avvio, ma non corregge le credenziali errate.
• L'API locale funziona, ma i client non riescono a connettersi: verifica il record DNS, il certificato TLS, il proxy inverso upstream e i record di rilevamento per la configurazione di dominio scelta. La mappatura della porta solo loopback è intenzionale per un proxy sullo stesso host; un proxy in un altro container richiede una rete Docker condivisa e una diversa configurazione di routing.
• Aggiornamento: prima esegui un backup, consulta le note di rilascio di Synapse, aggiorna il tag dell'immagine bloccata e ricrea il servizio con docker compose pullseguito da docker compose up -d. Mantieni la stessa directory dei dati, il volume del database, il nome del server e la chiave di firma.

Nell'esempio di configurazione per un gruppo di volontari, l'installazione è completa solo quando l'endpoint delle versioni locali risponde, l'endpoint HTTPS risponde tramite il proxy e l'amministratore può accedere utilizzando il dominio Matrix ID previsto. Questi controlli sono indicatori pratici di una prima implementazione funzionante; non sostituiscono la revisione dei requisiti di sicurezza, backup, federazione e operativi prima di coinvolgere una comunità più ampia.

Riferimenti ufficiali

• Istruzioni per l'installazione di Synapse e indicazioni sul nome del server.
• README dell'immagine Docker ufficiale di Synapse
• Riferimento alla configurazione di Synapse
• Guida del proxy inverso Synapse
• Installazione di Docker Engine
• Ordine di avvio e controlli di integrità di Docker Compose