Als Matrix Synapse op CasaOS 'container is unhealthy' weergeeft, begin dan met de containerlogs en het gegenereerde homeserver.yaml in plaats van zonder nadenken opnieuw te installeren. Synapse heeft een officiële Docker-image, maar voor een homeserver in productie zijn ook persistente configuratie en gegevens, een goede servernaam, PostgreSQL en planning voor HTTPS en federatie nodig.
SQLite is geschikt voor tests, maar de actuele Synapse-documentatie beveelt PostgreSQL aan voor vrijwel alle echte installaties. Een container kan opstarten en toch ongezond blijven als de configuratie, database, machtigingen of opstartmigratie problemen opleveren.
Gebruik de officiële Synapse-image
De actuele installatiehandleiding voor Synapse vermeldt ghcr.io/element-hq/synapse als officiële container-image.
De initiële configuratie genereren
Maak een persistente map en genereer de configuratie eenmalig voordat je de normale opstartprocedure uitvoert:
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 generateVervang het voorbeelddomein door de Matrix-servernaam die je wilt behouden.
Controleer waarom de container niet gezond is
docker ps -a | grep synapse
docker inspect synapse --format '{{json .State.Health}}'
docker logs --tail 200 synapseControleer op YAML-fouten, ontbrekende bestanden, machtigingsproblemen, databaseverbindingsfouten of migraties die nooit worden afgerond.
Gebruik PostgreSQL voor productie
De actuele PostgreSQL-handleiding voor Synapse beschrijft de ondersteunde databaseconfiguratie. Zorg dat de Postgres-gegevens persistent zijn en maak er samen met de Synapse-status back-ups van.
Wijzig server_name later niet zonder dit goed te plannen
Je Matrix-ID's zijn afgeleid van de servernaam, zoals @user:example.com. Kies het domein voor de lange termijn voordat je gebruikers uitnodigt.
HTTPS is vereist voor praktisch gebruik
Synapse luistert intern doorgaans via HTTP (meestal op poort 8008). Gebruik een reverseproxy met HTTPS voor clients en federatie, in plaats van de ruwe containerpoort openbaar toegankelijk te maken.
Federatie vereist extra DNS- en proxyconfiguratie
Als je wilt communiceren met andere Matrix-servers, configureer dan de openbare servernaam, HTTPS en federatieontdekking correct. Een test die alleen lokaal werkt, kan veel eenvoudiger zijn.
Maak een back-up van meer dan alleen de container
Bewaar homeserver.yaml, ondertekeningssleutels, geüploade media en de PostgreSQL-database. De image opnieuw ophalen herstelt de identiteit van een homeserver niet.
De Docker-handleiding voor probleemoplossing beschrijft de algemene aanpak voor het opsporen van problemen met containers.
Controleer de bestandseigenaar van de permanente gegevensmap
Als het containerlog de melding 'permission denied' geeft bij het lezen van homeserver.yaml, ondertekeningssleutels of media, pas dan de eigenaar van de gekoppelde Synapse-gegevensmap aan voor de UID/GID die de image verwacht. Maak niet de volledige CasaOS-gegevensstructuur beschrijfbaar voor iedereen.
Wacht tot de databasemigraties zijn voltooid voordat je de gezondheidsstatus beoordeelt
Na een upgrade of de eerste PostgreSQL-verbinding heeft Synapse mogelijk tijd nodig om schemamigraties uit te voeren. Houd de logs in de gaten in plaats van de container steeds opnieuw te starten, want onderbroken migraties kunnen de diagnose bemoeilijken.
Test de lokale API voordat je de reverseproxy instelt
Controleer of het interne Synapse HTTP-eindpunt bereikbaar is vanaf de CasaOS-host voordat je HTTPS, DNS of federatie toevoegt. Als de lokale API niet gezond is, kan een reverseproxy dit niet oplossen.
Veelgestelde vragen
Waarom is Synapse ongezond?
Controleer de logs en de gezondheidsstatus op configuratie-, rechten-, database- of migratiefouten; de brondiscussie vermeldde geen enkele geverifieerde oorzaak.
Kan ik SQLite gebruiken?
Om te testen wel. De huidige Synapse-documentatie raadt PostgreSQL aan voor vrijwel alle productie-installaties.
Welke poort gebruikt Synapse intern?
Veelgebruikte Docker-configuraties stellen de client-/server-API beschikbaar op poort 8008 achter een reverseproxy.
Heb ik Element nodig?
Nee. Synapse is de homeserver; Element is een mogelijke client/webfrontend.
