Synapse

https://matrix-org.github.io/synapse/
Admin
Synapse is a Matrix homeserver written in Python that enables real-time communication through a...
Tokens:303,274
Snippets:3,806
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install coturn using apt

Source: https://matrix-org.github.io/synapse/latest/setup/turn/coturn.html

Installs the coturn package and starts the systemd service. Use this method for Debian-based systems.

```bash
sudo apt install coturn
```

--------------------------------

### Starting Synapse Main Process with Poetry

Source: https://matrix-org.github.io/synapse/latest/workers.html

Use this command to start the main Synapse homeserver process when installed from source using Poetry.

```bash
poetry run synapse_homeserver --config-file [your homeserver.yaml]

```

--------------------------------

### Configure and install coturn from source

Source: https://matrix-org.github.io/synapse/latest/setup/turn/coturn.html

Steps to download, configure, build, and install coturn from its source code. Ensure libevent2 is installed if prompted.

```bash
./configure
```

```bash
make
sudo make install
```

--------------------------------

### Install openSUSE Prerequisites

Source: https://matrix-org.github.io/synapse/latest/setup/installation.html

Installs development patterns and packages for Synapse on openSUSE.

```bash
sudo zypper in -t pattern devel_basis
sudo zypper in python-pip python-setuptools sqlite3 python-virtualenv \
               python-devel libffi-devel libopenssl-devel libjpeg62-devel \
               libicu-devel
```

--------------------------------

### Install Synapse via PyPI

Source: https://matrix-org.github.io/synapse/latest/print.html

Set up a virtual environment and install Synapse from PyPI.

```bash
mkdir -p ~/synapse
virtualenv -p python3 ~/synapse/env
source ~/synapse/env/bin/activate
pip install --upgrade pip
pip install --upgrade setuptools
pip install matrix-synapse
```

--------------------------------

### Install Prerequisites on openSUSE

Source: https://matrix-org.github.io/synapse/latest/print.html

Installs the development pattern and required Python/library packages.

```bash
sudo zypper in -t pattern devel_basis
sudo zypper in python-pip python-setuptools sqlite3 python-virtualenv \
               python-devel libffi-devel libopenssl-devel libjpeg62-devel \
               libicu-devel
```

--------------------------------

### Start Synapse in virtualenv

Source: https://matrix-org.github.io/synapse/latest/print.html

Activate the environment and start the Synapse service.

```bash
cd ~/synapse
source env3/bin/activate
synctl start
```

--------------------------------

### Start Synapse Homeserver

Source: https://matrix-org.github.io/synapse/latest/setup/installation.html

Start the Synapse homeserver from its working directory after activating the virtual environment.

```bash
cd ~/synapse
source env/bin/activate
synctl start
```

--------------------------------

### Install Prerequisites on CentOS or Fedora

Source: https://matrix-org.github.io/synapse/latest/print.html

Installs development libraries and the Development Tools group.

```bash
sudo dnf install libtiff-devel libjpeg-devel libzip-devel freetype-devel \
                 libwebp-devel libxml2-devel libxslt-devel libpq-devel \
                 python3-virtualenv libffi-devel openssl-devel python3-devel \
                 libicu-devel
sudo dnf groupinstall "Development Tools"
```

--------------------------------

### User Registration Prompt Example

Source: https://matrix-org.github.io/synapse/latest/print.html

Example output showing the interactive prompts for creating a new user and setting administrative privileges.

```text
New user localpart: erikj
Password:
Confirm password:
Make admin [no]:
Success!
```

--------------------------------

### Install Synapse on Void Linux

Source: https://matrix-org.github.io/synapse/latest/setup/installation.html

Update repositories and install Synapse using xbps-install.

```bash
xbps-install -Su
xbps-install -S synapse
```

--------------------------------

### Install Individual Dependencies

Source: https://matrix-org.github.io/synapse/latest/print.html

Workaround for memory exhaustion during installation by installing specific packages individually.

```bash
pip install twisted
```

--------------------------------

### Install Prerequisites on Ubuntu or Debian

Source: https://matrix-org.github.io/synapse/latest/print.html

Installs essential build tools and development headers required for Synapse.

```bash
sudo apt install build-essential python3-dev libffi-dev \
                     python3-pip python3-setuptools sqlite3 \
                     libssl-dev virtualenv libjpeg-dev libxslt1-dev libicu-dev
```

--------------------------------

### Install Synapse on OpenBSD

Source: https://matrix-org.github.io/synapse/latest/setup/installation.html

Install Synapse using the pre-compiled binary package. Ensure the filesystem for /var/synapse is mounted with 'wxallowed'.

```bash
doas pkg_add synapse
```

--------------------------------

### Install Dependencies in User Space

Source: https://matrix-org.github.io/synapse/latest/upgrade.html

Install new dependencies by running setup.py in develop mode for the current user.

```bash
python setup.py develop --user
```

--------------------------------

### Install project dependencies

Source: https://matrix-org.github.io/synapse/latest/print.html

Installs all project dependencies including extras and synchronizes the environment.

```bash
poetry install --all-extras --sync
```

--------------------------------

### Install Synapse on OpenSUSE

Source: https://matrix-org.github.io/synapse/latest/print.html

Install the matrix-synapse package from the official OpenSUSE repositories.

```bash
sudo zypper install matrix-synapse
```

--------------------------------

### Install Synapse on Alpine Linux

Source: https://matrix-org.github.io/synapse/latest/setup/installation.html

Install Synapse from the community repository using apk.

```bash
sudo apk add synapse
```

--------------------------------

### Install Synapse on OpenBSD

Source: https://matrix-org.github.io/synapse/latest/print.html

Install the pre-compiled Synapse binary using the OpenBSD package manager.

```bash
doas pkg_add synapse
```

--------------------------------

### Install Synapse Dependencies with Poetry

Source: https://matrix-org.github.io/synapse/latest/development/contributing_guide.html

Navigate to your cloned repository and install all runtime and developer dependencies for Synapse using Poetry. Ensure the 'poetry install' command completes successfully.

```bash
cd path/where/you/have/cloned/the/repository
poetry install --extras all
```

--------------------------------

### Install Synapse on Void Linux

Source: https://matrix-org.github.io/synapse/latest/print.html

Update the system repositories and install the Synapse package.

```bash
xbps-install -Su
xbps-install -S synapse
```

--------------------------------

### Install Poetry and Dependencies

Source: https://matrix-org.github.io/synapse/latest/print.html

Installs the required version of Poetry and project dependencies.

```bash
pip install --user pipx
pipx install poetry==1.5.1
```

```bash
cd path/where/you/have/cloned/the/repository
poetry install --extras all
```

--------------------------------

### Install Synapse on Fedora

Source: https://matrix-org.github.io/synapse/latest/print.html

Install the matrix-synapse package from the official Fedora repositories.

```bash
sudo dnf install matrix-synapse
```

--------------------------------

### Install Ubuntu/Debian Prerequisites

Source: https://matrix-org.github.io/synapse/latest/setup/installation.html

Installs essential build tools and Python development headers for Synapse on Ubuntu or Debian systems.

```bash
sudo apt install build-essential python3-dev libffi-dev \
                     python3-pip python3-setuptools sqlite3 \
                     libssl-dev virtualenv libjpeg-dev libxslt1-dev libicu-dev
```

--------------------------------

### Install Synapse on FreeBSD

Source: https://matrix-org.github.io/synapse/latest/setup/installation.html

Install Synapse using either the Ports collection or pre-compiled packages.

```bash
cd /usr/ports/net-im/py-matrix-synapse && make install clean
pkg install py38-matrix-synapse
```

--------------------------------

### Build and Install Synapse on OpenBSD

Source: https://matrix-org.github.io/synapse/latest/setup/installation.html

Navigates to the Synapse port directory and initiates the build and installation process on OpenBSD.

```bash
cd /usr/ports/net/synapse
make install
```

--------------------------------

### Install Synapse from Debian Repositories

Source: https://matrix-org.github.io/synapse/latest/print.html

Install the maintainer-provided package for Debian bookworm or sid.

```bash
sudo apt install matrix-synapse
```

--------------------------------

### Install Synapse on OpenSUSE

Source: https://matrix-org.github.io/synapse/latest/setup/installation.html

Use zypper to install the Synapse package from the OpenSUSE repositories.

```bash
sudo zypper install matrix-synapse
```

--------------------------------

### Example .well-known/matrix/server for specific routing

Source: https://matrix-org.github.io/synapse/latest/delegate.html

This example shows how to configure the .well-known file to route federation traffic to synapse.example.com on port 443.

```json
{
    "m.server": "synapse.example.com:443"
}
```

--------------------------------

### Example User Registration Prompt

Source: https://matrix-org.github.io/synapse/latest/setup/installation.html

This is an example of the interactive prompts you will encounter when running `register_new_matrix_user` to create a new user account.

```text
New user localpart: erikj
Password:
Confirm password:
Make admin [no]:
Success!
```

--------------------------------

### Install Prerequisites on ArchLinux

Source: https://matrix-org.github.io/synapse/latest/print.html

Installs base development tools and Python dependencies via pacman.

```bash
sudo pacman -S base-devel python python-pip \
               python-setuptools python-virtualenv sqlite3 icu
```

--------------------------------

### Install CentOS/Fedora Prerequisites

Source: https://matrix-org.github.io/synapse/latest/setup/installation.html

Installs development libraries and tools required for Synapse on CentOS or Fedora Linux.

```bash
sudo dnf install libtiff-devel libjpeg-devel libzip-devel freetype-devel \
                 libwebp-devel libxml2-devel libxslt-devel libpq-devel \
                 python3-virtualenv libffi-devel openssl-devel python3-devel \
                 libicu-devel
sudo dnf groupinstall "Development Tools"
```

--------------------------------

### Install Synapse on Fedora

Source: https://matrix-org.github.io/synapse/latest/setup/installation.html

Use dnf to install the Synapse package from the Fedora repositories.

```bash
sudo dnf install matrix-synapse
```

--------------------------------

### Install Synapse Dependencies

Source: https://matrix-org.github.io/synapse/latest/print.html

Use the provided script to install required dependencies within a virtual environment.

```bash
python synapse/python_dependencies.py | xargs -n 1 pip install
```

--------------------------------

### Example of calling user_may_send_3pid_invite

Source: https://matrix-org.github.io/synapse/latest/modules/spam_checker_callbacks.html

This example demonstrates how to call the `user_may_send_3pid_invite` callback with specific parameters for inviting a user via email.

```python
await user_may_send_3pid_invite(
    "@bob:example.com",  # The inviter's user ID
    "email",  # The medium of the 3PID to invite
    "alice@example.com",  # The address of the 3PID to invite
    "!some_room:example.com",  # The ID of the room to send the invite into
)
```

--------------------------------

### Set up Synapse Virtual Environment

Source: https://matrix-org.github.io/synapse/latest/setup/installation.html

Create a directory, set up a Python virtual environment, and install Synapse along with its dependencies from PyPI.

```bash
mkdir -p ~/synapse
virtualenv -p python3 ~/synapse/env
source ~/synapse/env/bin/activate
pip install --upgrade pip
pip install --upgrade setuptools
pip install matrix-synapse
```

--------------------------------

### Start Synapse Processes with Poetry

Source: https://matrix-org.github.io/synapse/latest/print.html

Commands to start the main Synapse process or worker processes when installed via Poetry.

```bash
poetry run synapse_homeserver --config-file [your homeserver.yaml]
```

```bash
poetry run synapse_worker --config-file [your homeserver.yaml] --config-file [your worker.yaml]
```

--------------------------------

### Start Synapse

Source: https://matrix-org.github.io/synapse/latest/print.html

Launch the Synapse homeserver using the synctl utility.

```bash
cd ~/synapse
source env/bin/activate
synctl start
```

--------------------------------

### Install System Dependencies

Source: https://matrix-org.github.io/synapse/latest/print.html

Commands to install necessary system-level packages for Synapse development on Debian or Ubuntu.

```bash
sudo apt install python3-venv
```

```bash
sudo apt install libpq-dev
```

```bash
sudo apt install libicu-dev
```

--------------------------------

### Configure and Run Synapse

Source: https://matrix-org.github.io/synapse/latest/print.html

Initializes the configuration files and starts the local Synapse homeserver.

```bash
cp docs/sample_config.yaml homeserver.yaml
cp docs/sample_log_config.yaml log_config.yaml
```

```bash
poetry run python -m synapse.app.homeserver -c homeserver.yaml
```

--------------------------------

### Install Synapse from Debian Repositories (bookworm/sid)

Source: https://matrix-org.github.io/synapse/latest/setup/installation.html

Installs the `matrix-synapse` package directly from the Debian repositories for `bookworm` and `sid` distributions.

```bash
sudo apt install matrix-synapse

```

--------------------------------

### Activate virtualenv and start Synapse

Source: https://matrix-org.github.io/synapse/latest/setup/installation.html

If Synapse was installed via pip, activate its virtual environment and start the Synapse service before running user registration commands.

```bash
cd ~/synapse
source env/bin/activate
synctl start # if not already running
```

--------------------------------

### Install Dependencies with Poetry

Source: https://matrix-org.github.io/synapse/latest/development/dependencies.html

Installs all project dependencies, including optional extras, and synchronizes the lock file with the current environment.

```bash
poetry install --all-extras --sync
```

--------------------------------

### GET Request for Event Reports

Source: https://matrix-org.github.io/synapse/latest/admin_api/event_reports.html

This is an example of a GET request to the event reports endpoint. It demonstrates how to fetch a list of reported events with optional pagination parameters.

```http
GET /_synapse/admin/v1/event_reports?from=0&limit=10
```

--------------------------------

### Install PostgreSQL Python Client

Source: https://matrix-org.github.io/synapse/latest/postgres.html

Install the necessary Python client library for PostgreSQL. This command assumes you are using a virtual environment.

```bash
~/synapse/env/bin/pip install "matrix-synapse[postgres]"
```

--------------------------------

### Starting Synapse Worker Process with Poetry

Source: https://matrix-org.github.io/synapse/latest/workers.html

Use this command to start a Synapse worker process when installed from source using Poetry, specifying both the main homeserver and worker configuration files.

```bash
poetry run synapse_worker --config-file [your homeserver.yaml] --config-file [your worker.yaml]

```

--------------------------------

### Run the homeserver

Source: https://matrix-org.github.io/synapse/latest/print.html

Starts the homeserver using the specified configuration file.

```bash
$ python synapse/app/homeserver.py --config-path homeserver.config
```

--------------------------------

### Uninstall Stale Webclient Module

Source: https://matrix-org.github.io/synapse/latest/print.html

Removes the legacy syweb python module if it was installed during a previous v0.5.0 setup.

```bash
$ pip uninstall syweb
```

--------------------------------

### Install Synapse on Debian/Ubuntu via Official Repository

Source: https://matrix-org.github.io/synapse/latest/print.html

Use these commands to add the official Matrix.org repository and install the latest Synapse release.

```bash
sudo apt install -y lsb-release wget apt-transport-https
sudo wget -O /usr/share/keyrings/matrix-org-archive-keyring.gpg https://packages.matrix.org/debian/matrix-org-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/matrix-org-archive-keyring.gpg] https://packages.matrix.org/debian/ $(lsb_release -cs) main" |
    sudo tee /etc/apt/sources.list.d/matrix-org.list
sudo apt update
sudo apt install matrix-synapse-py3
```

```bash
sudo wget -O /usr/share/keyrings/matrix-org-archive-keyring.gpg https://packages.matrix.org/debian/matrix-org-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/matrix-org-archive-keyring.gpg] https://packages.matrix.org/debian/ $(lsb_release -cs) main prerelease" |
    sudo tee /etc/apt/sources.list.d/matrix-org.list
sudo apt update
sudo apt install matrix-synapse-py3
```

--------------------------------

### Example JSON body to start a background update job

Source: https://matrix-org.github.io/synapse/latest/usage/administration/admin_api/background_updates.html

Provides the JSON payload for scheduling a specific background update job.

```json
{
    "job_name": "populate_stats_process_rooms"
}
```

--------------------------------

### Example JSON Response for Room Messages

Source: https://matrix-org.github.io/synapse/latest/print.html

A sample JSON response structure containing a chunk of room events, start and end tokens for pagination.

```json
{
  "chunk": [
    {
      "content": {
        "body": "This is an example text message",
        "format": "org.matrix.custom.html",
        "formatted_body": "<b>This is an example text message</b>",
        "msgtype": "m.text"
      },
      "event_id": "$143273582443PhrSn:example.org",
      "origin_server_ts": 1432735824653,
      "room_id": "!636q39766251:example.com",
      "sender": "@example:example.org",
      "type": "m.room.message",
      "unsigned": {
        "age": 1234
      }
    },
    {
      "content": {
        "name": "The room name"
      },
      "event_id": "$143273582443PhrSn:example.org",
      "origin_server_ts": 1432735824653,
      "room_id": "!636q39766251:example.com",
      "sender": "@example:example.org",
      "state_key": "",
      "type": "m.room.name",
      "unsigned": {
        "age": 1234
      }
    },
    {
      "content": {
        "body": "Gangnam Style",
        "info": {
          "duration": 2140786,
          "h": 320,
          "mimetype": "video/mp4",
          "size": 1563685,
          "thumbnail_info": {
            "h": 300,
            "mimetype": "image/jpeg",
            "size": 46144,
            "w": 300
          },
          "thumbnail_url": "mxc://example.org/FHyPlCeYUSFFxlgbQYZmoEoe",
          "w": 480
        },
        "msgtype": "m.video",
        "url": "mxc://example.org/a526eYUSFFxlgbQYZmo442"
      },
      "event_id": "$143273582443PhrSn:example.org",
      "origin_server_ts": 1432735824653,
      "room_id": "!636q39766251:example.com",
      "sender": "@example:example.org",
      "type": "m.room.message",
      "unsigned": {
        "age": 1234
      }
    }
  ],
  "end": "t47409-4357353_219380_26003_2265",
  "start": "t47429-4392820_219380_26003_2265"
}
```

--------------------------------

### Recreate Poetry Virtual Environment

Source: https://matrix-org.github.io/synapse/latest/development/dependencies.html

Removes all existing virtual environments for the project and then recreates them with all extras installed. Ensure you deactivate any active virtual environment before starting.

```bash
# Stop the current virtualenv if active
$ deactivate

# Remove all of the files from the current environment.
# Don't worry, even though it says "all", this will only
# remove the Poetry virtualenvs for the current project.
$ poetry env remove --all

# Reactivate Poetry shell to create the virtualenv again
$ poetry shell
# Install everything again
$ poetry install --extras all
```

--------------------------------

### Example OIDC Provider Configuration

Source: https://matrix-org.github.io/synapse/latest/print.html

A complete configuration example for an OIDC provider, including endpoints, client credentials, and user mapping templates.

```yaml

__
oidc_providers:
  # Generic example
  #
  - idp_id: my_idp
    idp_name: "My OpenID provider"
    idp_icon: "mxc://example.com/mediaid"
    discover: false
    issuer: "https://accounts.example.com/"
    client_id: "provided-by-your-issuer"
    client_secret: "provided-by-your-issuer"
    client_auth_method: client_secret_post
    scopes: ["openid", "profile"]
    authorization_endpoint: "https://accounts.example.com/oauth2/auth"
    token_endpoint: "https://accounts.example.com/oauth2/token"
    userinfo_endpoint: "https://accounts.example.com/userinfo"
    jwks_uri: "https://accounts.example.com/.well-known/jwks.json"
    skip_verification: true
    enable_registration: true
    user_mapping_provider:
      config:
        subject_claim: "id"
        localpart_template: "{{ user.login }}"
        display_name_template: "{{ user.name }}"
        email_template: "{{ user.email }}"
    attribute_requirements:
      - attribute: userGroup
        value: "synapseUsers"

```

--------------------------------

### Run Homeserver with Configuration

Source: https://matrix-org.github.io/synapse/latest/upgrade.html

Start the homeserver using the specified configuration file after it has been generated or edited.

```bash
$ python synapse/app/homeserver.py --config-path homeserver.config
```

--------------------------------

### Shibboleth OIDC Relying Party Configuration

Source: https://matrix-org.github.io/synapse/latest/openid.html

Example configuration for Shibboleth as an OpenID Connect provider. Ensure `client_id` and `client_secret` are securely generated and that the `redirect_uris` match your Synapse installation.

```json
{
    "client_id": "SOME-CLIENT-ID",
    "client_secret": "SOME-SUPER-SECRET-SECRET",
    "response_types": ["code"],
    "grant_types": ["authorization_code"],
    "scope": "openid profile email",
    "redirect_uris": ["https://[synapse public baseurl]/_synapse/client/oidc/callback"]
}

```

--------------------------------

### Federation Destination Retry Info Response

Source: https://matrix-org.github.io/synapse/latest/usage/administration/admin_api/federation.html

This is an example of the JSON response body returned by the GET /_synapse/admin/v1/federation/destinations endpoint. It details the federation status, retry timings, and failure timestamps for remote servers.

```json
{
   "destinations":[
      {
         "destination": "matrix.org",
         "retry_last_ts": 1557332397936,
         "retry_interval": 3000000,
         "failure_ts": 1557329397936,
         "last_successful_stream_ordering": null
      }
   ],
   "total": 1
}
```

--------------------------------

### Address Docker Port Binding Error

Source: https://matrix-org.github.io/synapse/latest/development/contributing_guide.html

An example error message indicating that port 5432 is already in use, likely by a locally running PostgreSQL instance. This suggests stopping the existing instance before starting a new one via Docker.

```bash
docker: Error response from daemon: driver failed programming external connectivity on endpoint nice_ride (b57bbe2e251b70015518d00c9981e8cb8346b5c785250341a6c53e3c899875f1): Error starting userland proxy: listen tcp4 0.0.0.0:5432: bind: address already in use.
```

--------------------------------

### Start Synapse Demo Servers

Source: https://matrix-org.github.io/synapse/latest/development/demo.html

Starts the Synapse demo servers, generating configuration if needed. An optional --no-rate-limit flag can be used to disable rate limiting.

```bash
./demo/stop.sh; ./demo/clean.sh && ./demo/start.sh
```

--------------------------------

### Copy Sample Configuration Files

Source: https://matrix-org.github.io/synapse/latest/development/contributing_guide.html

Before starting a local Synapse instance, copy the sample configuration files to your working directory. You will need to edit `homeserver.yaml` to configure your instance.

```bash
cp docs/sample_config.yaml homeserver.yaml
cp docs/sample_log_config.yaml log_config.yaml
```

--------------------------------

### Install OpenID Connect dependencies

Source: https://matrix-org.github.io/synapse/latest/print.html

Command to install the necessary OIDC dependencies when using a virtualenv installation.

```bash
/path/to/env/bin/pip install matrix-synapse[oidc]
```

--------------------------------

### Install Twisted Dependency

Source: https://matrix-org.github.io/synapse/latest/setup/installation.html

Use this command to individually install the Twisted dependency if pip runs into memory issues during Synapse installation.

```bash
pip install twisted

```

--------------------------------

### View Synapse Configuration Help

Source: https://matrix-org.github.io/synapse/latest/usage/configuration/config_documentation.html

Run this command to access the help reference for Synapse configuration options.

```bash
python -m synapse.config --help
```

--------------------------------

### Install New Python Dependencies

Source: https://matrix-org.github.io/synapse/latest/upgrade.html

Install new Python dependencies required for the Synapse upgrade. This command uses xargs to pipe the list of dependencies to pip install.

```bash
python synapse/python_dependencies.py | xargs -n 1 pip install
```

--------------------------------

### Install PyICU for Improved User Search

Source: https://matrix-org.github.io/synapse/latest/upgrade.html

To enable improved user search with Unicode characters, install PyICU and its development headers. Then, install matrix-synapse with the user-search extra.

```bash
pip install matrix-synapse[user-search]
```

--------------------------------

### Initialize Django Project

Source: https://matrix-org.github.io/synapse/latest/print.html

Create a new Django project in the current directory.

```bash
django-admin startproject cas_test .
```

--------------------------------

### Install Synapse on Debian/Ubuntu (Latest Release)

Source: https://matrix-org.github.io/synapse/latest/setup/installation.html

Installs the latest stable release of Synapse using official Matrix.org Debian packages. Ensure you have `lsb-release`, `wget`, and `apt-transport-https` installed.

```bash
sudo apt install -y lsb-release wget apt-transport-https

```

```bash
sudo wget -O /usr/share/keyrings/matrix-org-archive-keyring.gpg https://packages.matrix.org/debian/matrix-org-archive-keyring.gpg

```

```bash
echo "deb [signed-by=/usr/share/keyrings/matrix-org-archive-keyring.gpg] https://packages.matrix.org/debian/ $(lsb_release -cs) main" |
    sudo tee /etc/apt/sources.list.d/matrix-org.list

```

```bash
sudo apt update

```

```bash
sudo apt install matrix-synapse-py3

```

--------------------------------

### Example output format

Source: https://matrix-org.github.io/synapse/latest/print.html

Sample output showing room counts and names.

```text
   9459  !FPUfgzXYWTKgIrwKxW:matrix.org              | This Week in Matrix
   9459  !FPUfgzXYWTKgIrwKxW:matrix.org              | This Week in Matrix (TWIM)
  17799  !iDIOImbmXxwNngznsa:matrix.org              | Linux in Russian
  18739  !GnEEPYXUhoaHbkFBNX:matrix.org              | Riot Android
  23373  !QtykxKocfZaZOUrTwp:matrix.org              | Matrix HQ
  39504  !gTQfWzbYncrtNrvEkB:matrix.org              | ru.[matrix]
  43601  !iNmaIQExDMeqdITdHH:matrix.org              | Riot
  43601  !iNmaIQExDMeqdITdHH:matrix.org              | Riot Web/Desktop
```

--------------------------------

### Sample homeserver.yaml configuration

Source: https://matrix-org.github.io/synapse/latest/print.html

A reference template for the homeserver.yaml file. Do not use this as a production configuration; generate a fresh one using Synapse installation instructions.

```yaml
# This file is maintained as an up-to-date snapshot of the default
# homeserver.yaml configuration generated by Synapse. You can find a
# complete accounting of possible configuration options at
# https://matrix-org.github.io/synapse/latest/usage/configuration/config_documentation.html
#
# It is *not* intended to be copied and used as the basis for a real
# homeserver.yaml. Instead, if you are starting from scratch, please generate
# a fresh config using Synapse by following the instructions in
# https://matrix-org.github.io/synapse/latest/setup/installation.html.
#
################################################################################

# Configuration file for Synapse.
#
# This is a YAML file: see [1] for a quick introduction. Note in particular
# that *indentation is important*: all the elements of a list or dictionary
# should have the same indentation.
#
# [1] https://docs.ansible.com/ansible/latest/reference_appendices/YAMLSyntax.html
#
# For more information on how to configure Synapse, including a complete accounting of
# each option, go to docs/usage/configuration/config_documentation.md or
# https://matrix-org.github.io/synapse/latest/usage/configuration/config_documentation.html
server_name: "SERVERNAME"
pid_file: DATADIR/homeserver.pid
listeners:
  - port: 8008
    tls: false
    type: http
    x_forwarded: true
    bind_addresses: ['::1', '127.0.0.1']
    resources:
      - names: [client, federation]
        compress: false
database:
  name: sqlite3
  args:
    database: DATADIR/homeserver.db
log_config: "CONFDIR/SERVERNAME.log.config"
media_store_path: DATADIR/media_store
signing_key_path: "CONFDIR/SERVERNAME.signing.key"
trusted_key_servers:
  - server_name: "matrix.org"
```

--------------------------------

### Install OIDC Dependencies for Synapse

Source: https://matrix-org.github.io/synapse/latest/openid.html

Install the necessary dependencies for OpenID Connect integration if Synapse was installed in a virtual environment. This ensures the 'authlib' library and related packages are available.

```bash
/path/to/env/bin/pip install matrix-synapse[oidc]
```

--------------------------------

### Install Django and django-mama-cas

Source: https://matrix-org.github.io/synapse/latest/print.html

Install the required packages for the CAS server implementation.

```bash
python -m pip install "django<3" "django-mama-cas==2.4.0"
```

--------------------------------

### Enable a Synapse Configuration Setting

Source: https://matrix-org.github.io/synapse/latest/usage/configuration/config_documentation.html

Example showing how to enable a configuration setting by uncommenting it in the YAML file.

```yaml
pid_file: DATADIR/homeserver.pid
```

--------------------------------

### Start Synapse with Python 3 Virtual Environment

Source: https://matrix-org.github.io/synapse/latest/upgrade.html

After activating the Python 3 virtual environment, use these commands to navigate to your Synapse directory and start the server. Ensure the virtual environment is active before running synctl.

```bash
cd ~/synapse
source env3/bin/activate
synctl start
```

--------------------------------

### Install coturn via apt

Source: https://matrix-org.github.io/synapse/latest/print.html

Installs the coturn package on Debian-based systems.

```bash
sudo apt install coturn
```

--------------------------------

### Install Synapse on Debian/Ubuntu (Prerelease Channel)

Source: https://matrix-org.github.io/synapse/latest/setup/installation.html

Installs a release candidate version of Synapse by enabling the prerelease channel in APT sources. Requires `lsb-release`, `wget`, and `apt-transport-https`.

```bash
sudo wget -O /usr/share/keyrings/matrix-org-archive-keyring.gpg https://packages.matrix.org/debian/matrix-org-archive-keyring.gpg

```

```bash
echo "deb [signed-by=/usr/share/keyrings/matrix-org-archive-keyring.gpg] https://packages.matrix.org/debian/ $(lsb_release -cs) main prerelease" | sudo tee /etc/apt/sources.list.d/matrix-org.list

```

```bash
sudo apt update

```

```bash
sudo apt install matrix-synapse-py3

```

--------------------------------

### Example Replication Protocol Session

Source: https://matrix-org.github.io/synapse/latest/print.html

A sample sequence of commands showing connection establishment, position updates, and data replication.

```text
> SERVER localhost:8823
> PING 1490197665618
< NAME synapse.app.appservice
< PING 1490197665618
< REPLICATE
> POSITION events master 1 1
> POSITION backfill master 1 1
> POSITION caches master 1 1
> RDATA caches master 2 ["get_user_by_id",["@01register-user:localhost:8823"],1490197670513]
> RDATA events master 14 ["$149019767112vOHxz:localhost:8823",
    "!AFDCvgApUmpdfVjIXm:localhost:8823","m.room.guest_access","",null]
< PING 1490197675618
> ERROR server stopping
```

--------------------------------

### Sample homeserver.yaml Configuration

Source: https://matrix-org.github.io/synapse/latest/usage/configuration/homeserver_sample_config.html

This is a sample homeserver configuration file for Synapse. It outlines various settings for server name, database, logging, media storage, and trusted key servers. Note that this file is for reference and should not be directly copied; generate a fresh configuration using Synapse.

```yaml
# This file is maintained as an up-to-date snapshot of the default
# homeserver.yaml configuration generated by Synapse. You can find a
# complete accounting of possible configuration options at
# https://matrix-org.github.io/synapse/latest/usage/configuration/config_documentation.html
#
# It is *not* intended to be copied and used as the basis for a real
# homeserver.yaml. Instead, if you are starting from scratch, please generate
# a fresh config using Synapse by following the instructions in
# https://matrix-org.github.io/synapse/latest/setup/installation.html.
#
################################################################################

# Configuration file for Synapse.
#
# This is a YAML file: see [1] for a quick introduction. Note in particular
# that *indentation is important*: all the elements of a list or dictionary
# should have the same indentation.
#
# [1] https://docs.ansible.com/ansible/latest/reference_appendices/YAMLSyntax.html
#
# For more information on how to configure Synapse, including a complete accounting of
# each option, go to docs/usage/configuration/config_documentation.md or
# https://matrix-org.github.io/synapse/latest/usage/configuration/config_documentation.html
server_name: "SERVERNAME"
pid_file: DATADIR/homeserver.pid
listeners:
  - port: 8008
    tls: false
    type: http
    x_forwarded: true
    bind_addresses: ['::1', '127.0.0.1']
    resources:
      - names: [client, federation]
        compress: false
database:
  name: sqlite3
  args:
    database: DATADIR/homeserver.db
log_config: "CONFDIR/SERVERNAME.log.config"
media_store_path: DATADIR/media_store
signing_key_path: "CONFDIR/SERVERNAME.signing.key"
trusted_key_servers:
  - server_name: "matrix.org"

```

--------------------------------

### GET /_synapse/admin/v1/users/<user_id>/pushers

Source: https://matrix-org.github.io/synapse/latest/print.html

Gets information about all pushers for a specific user_id.

```APIDOC
## GET /_synapse/admin/v1/users/<user_id>/pushers

### Description
Gets information about all pushers for a specific user_id.

### Method
GET

### Endpoint
/_synapse/admin/v1/users/<user_id>/pushers

### Parameters
#### Path Parameters
- **user_id** (string) - Required - Fully qualified user ID.

### Response
#### Success Response (200)
- **pushers** (array) - List of pusher objects.
- **total** (integer) - Total count of pushers.
```

--------------------------------

### GET /_synapse/admin/v2/users/<user_id>/devices

Source: https://matrix-org.github.io/synapse/latest/print.html

Gets information about all devices for a specific user_id.

```APIDOC
## GET /_synapse/admin/v2/users/<user_id>/devices

### Description
Gets information about all devices for a specific user_id.

### Method
GET

### Endpoint
/_synapse/admin/v2/users/<user_id>/devices

### Parameters
#### Path Parameters
- **user_id** (string) - Required - The fully qualified user ID.

### Response
#### Success Response (200)
- **devices** (array) - List of device objects.
- **total** (integer) - Total number of user's devices.
```

--------------------------------

### Configure and Build Synapse on OpenBSD

Source: https://matrix-org.github.io/synapse/latest/print.html

Commands to prepare the filesystem, configure build directories, and install Synapse from ports.

```bash
doas mkdir /usr/local/pobj_wxallowed
```

```bash
doas chown _pbuild:_pbuild /usr/local/pobj_wxallowed
```

```bash
echo WRKOBJDIR_lang/python/3.7=/usr/local/pobj_wxallowed  \nWRKOBJDIR_lang/python/2.7=/usr/local/pobj_wxallowed >> /etc/mk.conf
```

```bash
cd /usr/ports/net/synapse
make install
```

--------------------------------

### Generate Synapse Configuration

Source: https://matrix-org.github.io/synapse/latest/print.html

Create the initial configuration file for the homeserver.

```bash
cd ~/synapse
python -m synapse.app.homeserver \
    --server-name my.domain.name \
    --config-path homeserver.yaml \
    --generate-config \
    --report-stats=[yes|no]
```

--------------------------------

### Build coturn from source

Source: https://matrix-org.github.io/synapse/latest/print.html

Commands to configure and build coturn after downloading the source code.

```bash
./configure
```

```bash
make
sudo make install
```

--------------------------------

### Build Synapse Package

Source: https://matrix-org.github.io/synapse/latest/print.html

Install build tools and execute the build process.

```bash
poetry run pip install build && poetry run python -m build
```

--------------------------------

### Display database size output

Source: https://matrix-org.github.io/synapse/latest/print.html

Example output showing the database size.

```text
pg_size_pretty 
----------------
 6420 MB
(1 row)
```

--------------------------------

### Example Module Configuration in YAML

Source: https://matrix-org.github.io/synapse/latest/code_style.html

This example shows how to configure modules in Synapse's YAML configuration. It demonstrates adding a module with specific configuration options, including nested dictionaries and boolean flags.

```yaml
modules:
  - module: my_super_module.MySuperClass
    config:
      do_thing: true
  - module: my_other_super_module.SomeClass
    config: {}
```

--------------------------------

### Start All Workers with Synctl

Source: https://matrix-org.github.io/synapse/latest/print.html

Command to start all worker configurations located in a specific directory.

```bash
synctl -a $CONFIG/workers start
```

--------------------------------

### Install Prerequisites on macOS

Source: https://matrix-org.github.io/synapse/latest/print.html

Commands for setting up Xcode tools, Homebrew dependencies, and OpenSSL environment variables.

```bash
xcode-select --install
```

```bash
brew install jpeg libpq
```

```bash
brew install openssl@1.1
export LDFLAGS="-L/usr/local/opt/openssl/lib"
export CPPFLAGS="-I/usr/local/opt/openssl/include"
```

--------------------------------

### GET /_synapse/admin/v1/users/<user_id>/accountdata

Source: https://matrix-org.github.io/synapse/latest/print.html

Gets information about account data for a specific user.

```APIDOC
## GET /_synapse/admin/v1/users/<user_id>/accountdata

### Description
Gets information about account data for a specific user.

### Method
GET

### Endpoint
/_synapse/admin/v1/users/<user_id>/accountdata

### Parameters
#### Path Parameters
- **user_id** (string) - Required - The fully qualified user ID.
```
Tokens:
Raw