Matrix Synapse non funziona correttamente su CasaOS: guida alla correzione di Docker

Se Matrix Synapse su CasaOS mostra “il container non è in salute”, controlla prima i log del container e il file homeserver.yaml generato, invece di reinstallare senza verifiche. Synapse dispone di un'immagine Docker ufficiale, ma un homeserver di produzione richiede anche una configurazione e dati persistenti, un nome server appropriato, PostgreSQL e una pianificazione per HTTPS e la federazione.

SQLite è adatto per i test, ma la documentazione attuale di Synapse consiglia PostgreSQL per quasi tutte le installazioni reali. Un container può avviarsi ma risultare comunque non in salute se si verificano errori nella configurazione, nel database, nelle autorizzazioni o nella migrazione all'avvio.

Usa l'immagine ufficiale di Synapse

L'attuale guida all'installazione di Synapse indica ghcr.io/element-hq/synapse come immagine container ufficiale.

Genera la configurazione iniziale

Crea una directory persistente e genera la configurazione una volta prima dell'avvio normale:

mkdir -p /DATA/AppData/synapse
docker run --rm -it   -v /DATA/AppData/synapse:/data   -e SYNAPSE_SERVER_NAME=matrix.example.com   -e SYNAPSE_REPORT_STATS=no   ghcr.io/element-hq/synapse:latest generate

Sostituisci il dominio di esempio con il nome del server Matrix che intendi mantenere.

Verifica perché il container non è in salute

docker ps -a | grep synapse
docker inspect synapse --format '{{json .State.Health}}'
docker logs --tail 200 synapse

Cerca errori YAML, file mancanti, problemi di autorizzazioni, errori di connessione al database o migrazioni che non vengono mai completate.

Usa PostgreSQL per la produzione

L'attuale guida a PostgreSQL per Synapse illustra la configurazione supportata del database. Mantieni persistenti i dati di Postgres ed esegui il backup insieme allo stato di Synapse.

Do Not Change server_name Later Without Planning

I tuoi ID Matrix derivano dal nome del server, ad esempio @user:example.com. Scegli il dominio definitivo prima di invitare gli utenti.

Per un utilizzo pratico è necessario HTTPS

Normalmente Synapse è in ascolto internamente su HTTP (comunemente sulla porta 8008). Usa un proxy inverso con HTTPS per i client e la federazione, invece di esporre pubblicamente la porta grezza del container.

La federazione comporta ulteriori requisiti per DNS e proxy

Se vuoi comunicare con altri server Matrix, configura correttamente il nome pubblico del server, HTTPS e l’individuazione della federazione. Un test solo locale può essere molto più semplice.

Esegui il backup anche di altri elementi oltre al container

Conserva homeserver.yaml, le chiavi di firma, i file multimediali caricati e il database PostgreSQL. Scaricare di nuovo l’immagine non ripristina l’identità del server domestico.

La guida alla risoluzione dei problemi di Docker illustra il metodo generale per diagnosticare i container.

Controlla la proprietà dei file nella cartella dei dati persistenti

Se il log del container segnala un errore di autorizzazione durante la lettura di homeserver.yaml, delle chiavi di firma o dei file multimediali, correggi il proprietario della directory dei dati Synapse montata, assegnandola all’UID/GID previsto dall’immagine. Evita di rendere scrivibile da chiunque l’intero albero dei dati CasaOS.

Attendi le migrazioni del database prima di valutare lo stato di salute

Dopo un aggiornamento o la prima connessione a PostgreSQL, Synapse potrebbe aver bisogno di tempo per eseguire le migrazioni dello schema. Controlla i log invece di riavviare ripetutamente il container: le migrazioni interrotte possono rendere più difficile la diagnosi.

Verifica l’API locale prima del proxy inverso

Prima di aggiungere HTTPS, DNS o federazione, verifica che l’endpoint HTTP interno di Synapse risponda dall’host CasaOS. Se l’API locale non è in buono stato, un proxy inverso non può risolvere il problema.

Domande frequenti

Perché Synapse non è in buono stato?

Controlla i log e lo stato di salute per individuare errori di configurazione, autorizzazione, database o migrazione; la discussione originale non indicava una causa specifica verificata.

Posso usare SQLite?

Per i test, sì. La documentazione attuale di Synapse consiglia PostgreSQL per quasi tutte le installazioni di produzione.

Quale porta usa Synapse internamente?

Le configurazioni Docker più comuni espongono l’API client/server sulla porta 8008 dietro un proxy inverso.

Mi serve Element?

No. Synapse è il server domestico; Element è uno dei possibili client o frontend web.