Skip to content

Matrix/Synapse — Runbook

User Management

Create a user

ssh -i ~/.ssh/homelab_claude [email protected] \
  "pct exec 121 -- docker exec synapse register_new_matrix_user -u <username> -p <password> -a -c /data/homeserver.yaml https://matrix.eva-00.network"

-a flag makes the user an admin. Remove it for regular users.

Logs

Log Contents Location Loki query Format
Synapse Federation events, room state, user registration, auth, errors Docker (LXC 121) stdout {job="matrix", container="synapse"} Plain text

Notes: - SSH fallback: ssh [email protected] "pct exec 121 -- docker logs synapse"

Troubleshooting

Synapse fails to start (permission error on data volume)

Fix volume permissions: 

ssh -i ~/.ssh/homelab_claude [email protected] \
  "pct exec 121 -- chown -R 991:991 /opt/matrix/data/"
Then restart the container.

Federation not working

  • Verify https://matrix.eva-00.network/.well-known/matrix/server returns the correct server name
  • Check Synapse logs for federation errors