Als Matrix Synapse in CasaOS ‘container is unhealthy’ weergeeft, begin dan met de containerlogboeken en het gegenereerde homeserver.yaml in plaats van blind opnieuw te installeren. Synapse heeft een officiële Docker-image, maar een productiehomeserver heeft ook persistente configuratie en gegevens, een juiste servernaam, PostgreSQL en een plan voor HTTPS en federatie nodig.
SQLite is acceptabel voor tests, maar de huidige Synapse-documentatie raadt PostgreSQL aan voor vrijwel alle echte installaties. Een container kan starten en toch ongezond blijven wanneer de configuratie, database, rechten of migratie bij het opstarten mislukt.
Gebruik de officiële Synapse-image
De actuele Synapse-installatiehandleiding documenteert ghcr.io/element-hq/synapse als officiële container-image.
Genereer de eerste configuratie
Maak een persistente map aan en genereer de configuratie één keer 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 blijven gebruiken.
Controleer waarom de container ongezond is
docker ps -a | grep synapse
docker inspect synapse --format '{{json .State.Health}}'
docker logs --tail 200 synapseLet op YAML-fouten, ontbrekende bestanden, fouten met rechten, databaseverbindingsfouten of migraties die niet worden voltooid.
Gebruik PostgreSQL voor productie
De actuele Synapse PostgreSQL-handleiding legt de ondersteunde databaseconfiguratie uit. Zorg dat de PostgreSQL-gegevens persistent zijn en maak samen met de Synapse-status back-ups.
Wijzig server_name later niet zonder planning
Je Matrix-ID’s zijn afgeleid van de servernaam, zoals @user:example.com. Kies het definitieve domein voordat je gebruikers uitnodigt.
HTTPS is vereist voor praktisch gebruik
Synapse luistert intern normaal gesproken via HTTP (meestal op poort 8008). Gebruik een reverseproxy met HTTPS voor clients en federatie in plaats van de onbewerkte containerpoort openbaar beschikbaar te maken.
Federatie vereist extra DNS- en proxyconfiguratie
Als je met andere Matrix-servers wilt communiceren, configureer dan de openbare servernaam, HTTPS en federatiedetectie correct. Een lokale test kan veel eenvoudiger zijn.
Maak van meer dan alleen de container een back-up
Bewaar homeserver.yaml, ondertekeningssleutels, geüploade media en de PostgreSQL-database. De image opnieuw ophalen herstelt de identiteit van een homeserver niet.
De Docker-probleemoplossingshandleiding biedt een algemeen model voor het opsporen van containerproblemen.
Controleer de eigenaar van de persistente gegevensmap
Als het containerlogboek bij het lezen van homeserver.yaml, ondertekeningssleutels of media de foutmelding ‘permission denied’ bevat, wijzig dan de eigenaar van de gekoppelde Synapse-gegevensmap naar de UID/GID die door de image wordt verwacht. Maak niet de volledige CasaOS-gegevensstructuur voor iedereen schrijfbaar.
Wacht op databasemigraties voordat je de gezondheidsstatus beoordeelt
Na een upgrade of de eerste PostgreSQL-verbinding kan Synapse tijd nodig hebben om schemamigraties uit te voeren. Houd de logboeken in de gaten in plaats van de container steeds opnieuw te starten, omdat onderbroken migraties de diagnose moeilijker kunnen maken.
Test de lokale API vóór de reverseproxy
Controleer vanaf de CasaOS-host of het interne Synapse-HTTP-eindpunt reageert voordat je HTTPS, DNS of federatie toevoegt. Als de lokale API ongezond is, kan een reverseproxy dit niet herstellen.
Veelgestelde vragen
Waarom is Synapse ongezond?
Controleer de logboeken en gezondheidsinformatie op configuratie-, rechten-, database- of migratiefouten; de oorspronkelijke thread bevatte geen één geverifieerde oorzaak.
Kan ik SQLite gebruiken?
Voor tests wel. De huidige Synapse-documentatie raadt PostgreSQL aan voor vrijwel alle productie-installaties.
Welke poort gebruikt Synapse intern?
Veel 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 of webfrontend.
