If Matrix Synapse on CasaOS shows “container is unhealthy,” start with the container logs and generated homeserver.yaml rather than reinstalling blindly. Synapse has an official Docker image, but a production homeserver also needs persistent configuration/data, a proper server name, PostgreSQL, and HTTPS/federation planning.
SQLite is acceptable for testing, but current Synapse documentation recommends PostgreSQL for almost all real installations. A container can start yet remain unhealthy when its config, database, permissions, or startup migration fails.
Use the Official Synapse Image
The current Synapse installation guide documents ghcr.io/element-hq/synapse as an official container image.
Generate the Initial Configuration
Create a persistent directory and generate configuration once before normal startup:
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 generateReplace the example domain with the Matrix server name you intend to keep.
Check Why the Container Is Unhealthy
docker ps -a | grep synapse
docker inspect synapse --format '{{json .State.Health}}'
docker logs --tail 200 synapseLook for YAML errors, missing files, permission failures, database connection errors, or migrations that never complete.
Use PostgreSQL for Production
The current Synapse PostgreSQL guide explains the supported database setup. Keep Postgres data persistent and back it up together with Synapse state.
Do Not Change server_name Later Without Planning
Your Matrix IDs are derived from the server name, such as @user:example.com. Pick the long-term domain before inviting users.
HTTPS Is Required for Practical Use
Synapse normally listens internally on HTTP (commonly port 8008). Use a reverse proxy with HTTPS for clients and federation rather than exposing the raw container port publicly.
Federation Adds More DNS and Proxy Requirements
If you want to communicate with other Matrix servers, configure the public server name, HTTPS, and federation discovery correctly. A local-only test can be much simpler.
Back Up More Than the Container
Preserve homeserver.yaml, signing keys, uploaded media, and the PostgreSQL database. Re-pulling the image does not restore a homeserver identity.
The Docker troubleshooting guide provides the general container-debugging model.
Check File Ownership on the Persistent Data Folder
If the container log reports permission denied while reading homeserver.yaml, signing keys, or media, fix the ownership of the mapped Synapse data directory for the UID/GID expected by the image. Avoid making the entire CasaOS data tree world-writable.
Wait for Database Migrations Before Judging Health
After an upgrade or first PostgreSQL connection, Synapse may need time to run schema migrations. Watch the logs instead of repeatedly restarting the container, because interrupted migrations can make diagnosis harder.
Test the Local API Before the Reverse Proxy
Confirm the internal Synapse HTTP endpoint responds from the CasaOS host before adding HTTPS, DNS, or federation. If the local API is unhealthy, a reverse proxy cannot repair it.
FAQ
Why is Synapse unhealthy?
Check logs and health output for configuration, permission, database, or migration errors; the source thread did not provide a verified single cause.
Can I use SQLite?
For testing, yes. Current Synapse docs recommend PostgreSQL for almost all production installations.
What port does Synapse use internally?
Common Docker setups expose the client/server API on port 8008 behind a reverse proxy.
Do I need Element?
No. Synapse is the homeserver; Element is one possible client/web frontend.
