Synapse Documentation

Synapse is a Matrix homeserver implementation. To manage a production instance, you can perform the following tasks:

• Installation & Configuration: Set up your instance and configure settings, including Single Sign-On (SSO).
• Upgrades: Follow procedures to upgrade between Synapse versions.
• Administration: Use the Admin API, install pluggable modules, or access the manhole.
• Logging: Read log lines, configure standard logging, or set up structured logging.
• Scaling: Scale the server by adding worker processes.
• Monitoring: Set up metrics to monitor instance performance.

Server Notices use standard Matrix communication mechanisms and work with any Matrix client.

User Behavior:

• Invitations: When a user is first sent a notice, they receive an invitation to a room (the name is configurable via room_name). Users cannot reject this invitation; attempts to do so will result in an error.
• Viewing Notices: Once accepted, notices appear in the room history, sent by the configured 'server notices user'.
• Permissions: Users are prevented from sending messages in the notices room via power levels.
• Leaving: Users can leave the room if they wish. If they have left, subsequent notices will trigger the creation of a new room.

Synapse implements faster joins (also known as partial joins) to allow servers to request a lightweight response to the federation /send_join endpoint. This optimizes the joining process by providing a subset of the room state instead of the full state.

A room is marked as partially joined in the database via the partial_state_rooms table, and specific events are marked as "partially stated" in the partial_state_events table.

Key characteristics of a partially joined room:

• Synapse uses a "best-effort approximation" of the room state.
• Authorization check 5 (rules based on state before the event) is performed against the resolution of the partial state and the event's auth events.
• Authorization check 6 (soft-failures based on current room state) is disabled.
• Events with partial state are not considered outliers.

Synapse uses streams as append-only logs of facts to notify different parts of the application (or different workers) about database changes. Streams allow components to respond to events like new messages, account data changes, or device updates.

Common stream examples include:

• Events stream: Reports new events (PDUs) created by Synapse or accepted from other homeservers.
• Account data stream: Reports changes to user account data.
• To-device stream: Reports when a device has a new to-device message.

For a full list of available streams, refer to the synapse.replication.tcp.streams module.

Synapse is an open source Matrix homeserver implementation. It is primarily distributed via the Element Server Suite (ESS), which provides a full Matrix stack tailored to specific use cases.

ESS editions include:

• ESS Community: Free distribution for small-to-mid-scale, non-commercial community use.
• ESS Pro: Commercial distribution for professional use.
• ESS TI-M: A version of ESS Pro focused on German National Digital Health Agency (Gematik) requirements for TI-Messenger Pro and ePA.

Synapse supports splitting its datastore across multiple physical databases. The schema is organized into logical databases:

• state: Stores Matrix room state (e.g., state_groups, their relationships, and contents).
• main: Stores all other data.
• common: Contains schema files for tables that must exist on all physical databases.

Synapse provides several built-in methods for authenticating users. You can use these out-of-the-box or extend the system using custom pluggable authentication modules.

Built-in authentication methods:

• Username and password: Standard credential-based login.
• Email address and password: Authentication using an email address as the identifier.
• Single Sign-On (SSO): Support for the following protocols:
  • SAML
  • OpenID Connect (OIDC)
  • CAS
• JSON Web Tokens (JWT): Token-based authentication.
• Administrator's shared secret: A method for administrative access.

Extensibility: Synapse can be extended to support custom authentication schemes via optional "password auth provider" modules.

Synapse is primarily written in Python. To contribute to the project:

1. Setup: Follow the development environment setup guide.
2. Workflow: Use the provided linters and testing suites to validate code.
3. Issues: Search the GitHub issue tracker for bugs or features, specifically looking for the good first issue label if you are new.
4. Advanced Topics: Familiarize yourself with database schema migrations, federation, and the internal build process.
5. Git Hygiene: Follow the project's guidelines for maintaining a clean git history.

Delta files define the steps to upgrade the database. SQL deltas are used for simple schema changes.

Requirements:

• Naming: Files must be named *.sql, *.sql.postgres, or *.sql.sqlite.
• Ordering: Files are applied in alphanumeric order. Use a prefix like 01, 02, etc. (e.g., 01add_bar_to_foo.sql).
• Location: Place files in synapse/storage/schema/<database>/delta/<version>/.
• Limitation: The SQL parser is simple. It does not support complex statements requiring a semicolon in the middle (like CREATE TRIGGER). Use Python delta files for such cases.

To generate a new homeserver.yaml and the necessary signing keys, use the generate command via docker-compose. You must provide the SYNAPSE_SERVER_NAME and SYNAPSE_REPORT_STATS environment variables.

After generation, you should customize the resulting configuration file before starting the server.

docker-compose run --rm -e SYNAPSE_SERVER_NAME=my.matrix.host -e SYNAPSE_REPORT_STATS=yes synapse generate