### Start Synapse

Source: https://github.com/element-hq/synapse/blob/develop/docs/setup/installation.md

Command to start the homeserver using synctl.

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

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

### Install OpenSUSE Prerequisites

Source: https://github.com/element-hq/synapse/blob/develop/docs/setup/installation.md

Install development patterns and required Python packages 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
```

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

### Configuration Documentation Example

Source: https://github.com/element-hq/synapse/blob/develop/docs/code_style.md

Example of the required YAML format for documenting configuration options in the Synapse manual.

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

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

### Example Implementation

Source: https://github.com/element-hq/synapse/blob/develop/docs/modules/presence_router_callbacks.md

An example module demonstrating how to implement both `get_users_for_states` and `get_interested_users` callbacks to route presence updates.

```APIDOC
## Example Module Implementation

### Description
This example shows a module that implements both presence router callbacks to ensure a specific user (`@alice:example.com`) receives presence updates from other specified users (`@bob:example.com` and `@charlie:somewhere.org`).

### Method
This section describes the methods used within the example class.

#### `__init__`
Initializes the module and registers the presence router callbacks.

#### `get_users_for_states`
Implements the `get_users_for_states` callback to forward presence updates for `@bob:example.com` and `@charlie:somewhere.org` to `@alice:example.com`.

#### `get_interested_users`
Implements the `get_interested_users` callback to specify that `@alice:example.com` is interested in the presence of `@bob:example.com` and `@charlie:somewhere.org`.

### Endpoint
N/A (This is a module implementation, not a direct API endpoint)

### Parameters
N/A

### Request Example
```python
from typing import Iterable

from synapse.module_api import ModuleApi


class CustomPresenceRouter:
    def __init__(self, config: dict, api: ModuleApi):
        self.api = api

        self.api.register_presence_router_callbacks(
            get_users_for_states=self.get_users_for_states,
            get_interested_users=self.get_interested_users,
        )

    async def get_users_for_states(
        self, 
        state_updates: Iterable["synapse.api.UserPresenceState"],
    ) -> dict[str, set["synapse.api.UserPresenceState"]]:
        res = {}
        for update in state_updates:
            if (
                update.user_id == "@bob:example.com"
                or update.user_id == "@charlie:somewhere.org"
            ):
                res.setdefault("@alice:example.com", set()).add(update)

        return res

    async def get_interested_users(
        self,
        user_id: str,
    ) -> set[str] | "synapse.module_api.PRESENCE_ALL_USERS":
        if user_id == "@alice:example.com":
            return {"@bob:example.com", "@charlie:somewhere.org"}

        return set()
```

### Response
N/A (This is a module implementation, not a direct API endpoint)
```

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

### Example User Registration Prompt

Source: https://github.com/element-hq/synapse/blob/develop/docs/setup/installation.md

This is an example of the interactive prompts when registering a new user via the command line.

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

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

### Install poetry using pipx

Source: https://github.com/element-hq/synapse/blob/develop/docs/development/contributing_guide.md

Recommended method for installing the poetry dependency manager.

```shell
pip install --user pipx
pipx install poetry
```

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

### Install project dependencies

Source: https://github.com/element-hq/synapse/blob/develop/docs/development/contributing_guide.md

Install all runtime and developer dependencies using poetry within the repository directory.

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

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

### Install Postgres Client Library with Pip

Source: https://github.com/element-hq/synapse/blob/develop/docs/postgres.md

Install the necessary Python PostgreSQL client library when setting up Synapse in a virtual environment. Ensure you have the PostgreSQL development files installed on your system.

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

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

### Install Synapse via pip

Source: https://github.com/element-hq/synapse/blob/develop/docs/setup/installation.md

Commands to set up a virtual environment and install the matrix-synapse package.

```sh
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 RHEL Prerequisites

Source: https://github.com/element-hq/synapse/blob/develop/docs/setup/installation.md

Install Python 3.12 and common development tools on RHEL systems.

```bash
dnf install python3.12 python3.12-devel
```

```bash
dnf install libpq5 libpq5-devel lz4 pkgconf
dnf group install "Development Tools"
```

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

### Install macOS Prerequisites

Source: https://github.com/element-hq/synapse/blob/develop/docs/setup/installation.md

Commands to install Xcode tools, dependencies, and OpenSSL configuration for macOS.

```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"
```

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

### Synapse TURN Configuration Example

Source: https://github.com/element-hq/synapse/blob/develop/docs/turn-howto.md

Example configuration for Synapse homeserver to enable TURN relaying. Ensure the shared secret is kept secure.

```yaml
turn_uris: [ "turn:turn.matrix.org?transport=udp", "turn:turn.matrix.org?transport=tcp" ]
turn_shared_secret: "n0t4ctuAllymatr1Xd0TorgSshar3d5ecret4obvIousreAsons"
turn_user_lifetime: 86400000
turn_allow_guests: true
```

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

### Install Synapse on Fedora

Source: https://github.com/element-hq/synapse/blob/develop/docs/setup/installation.md

Command to install the Synapse package from the official Fedora repositories.

```sh
sudo dnf install matrix-synapse
```

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

### Example call to user_may_send_3pid_invite

Source: https://github.com/element-hq/synapse/blob/develop/docs/modules/spam_checker_callbacks.md

Example usage of the 3PID invite callback for an email invitation.

```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
)
```

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

### Start Synapse with Activated Virtual Environment

Source: https://github.com/element-hq/synapse/blob/develop/docs/upgrade.md

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

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

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

### Custom Presence Router Module Example

Source: https://github.com/element-hq/synapse/blob/develop/docs/modules/presence_router_callbacks.md

An example module demonstrating the implementation of both `get_users_for_states` and `get_interested_users` to route specific presence updates.

```python
from typing import Iterable

from synapse.module_api import ModuleApi


class CustomPresenceRouter:
    def __init__(self, config: dict, api: ModuleApi):
        self.api = api

        self.api.register_presence_router_callbacks(
            get_users_for_states=self.get_users_for_states,
            get_interested_users=self.get_interested_users,
        )

    async def get_users_for_states(
        self,
        state_updates: Iterable["synapse.api.UserPresenceState"],
    ) -> dict[str, set["synapse.api.UserPresenceState"]]:
        res = {}
        for update in state_updates:
            if (
                update.user_id == "@bob:example.com"
                or update.user_id == "@charlie:somewhere.org"
            ):
                res.setdefault("@alice:example.com", set()).add(update)

        return res

    async def get_interested_users(
        self,
        user_id: str,
    ) -> set[str] | "synapse.module_api.PRESENCE_ALL_USERS":
        if user_id == "@alice:example.com":
            return {"@bob:example.com", "@charlie:somewhere.org"}

        return set()

```

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

### Example pg_hba.conf Line Order

Source: https://github.com/element-hq/synapse/blob/develop/docs/postgres.md

This line in `pg_hba.conf` should typically appear after custom authentication rules.

```sql
host    all         all             ::1/128     ident
```

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

### Install Synapse via Matrix.org Debian/Ubuntu Repository

Source: https://github.com/element-hq/synapse/blob/develop/docs/setup/installation.md

Commands to add the official Matrix.org repository and install the latest stable Synapse release.

```sh
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
```

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

### Configure SSO Settings

Source: https://github.com/element-hq/synapse/blob/develop/docs/usage/configuration/config_documentation.md

Example configuration for SSO client whitelisting and profile information updates.

```yaml
sso:
  client_whitelist:
  - https://riot.im/develop
  - https://my.custom.client/
  update_profile_information: true
```

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

### Manage Synapse Service with Systemd

Source: https://github.com/element-hq/synapse/blob/develop/contrib/systemd/README.md

Commands to start, check status, and enable the Synapse service.

```bash
sudo systemctl start matrix-synapse
```

```bash
sudo systemctl status matrix-synapse
```

```bash
sudo systemctl enable matrix-synapse
```

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

### Example Disk Space Calculation for Re-indexing

Source: https://github.com/element-hq/synapse/blob/develop/docs/upgrade.md

An example output from the disk space estimation query, showing 288 MB for 'events_order_room'. This indicates a need for approximately 1152MB of free disk space.

```text
synapse=# select pg_size_pretty(pg_relation_size('events_order_room'));
 pg_size_pretty
----------------
 288 MB
(1 row)
```

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

### Start All Synapse Workers with Synctl

Source: https://github.com/element-hq/synapse/blob/develop/docs/synctl_workers.md

Use this command to start all Synapse worker configurations found in the specified directory. The `-a` option indicates operation on all worker configurations.

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

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

### Run PostgreSQL via Docker

Source: https://github.com/element-hq/synapse/blob/develop/docs/development/contributing_guide.md

Starts a PostgreSQL container for testing purposes.

```shell
docker run --rm -e POSTGRES_PASSWORD=mysecretpassword -e POSTGRES_USER=postgres -e POSTGRES_DB=postgres -p 5432:5432 postgres:14
```

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

### Install Prerequisites on Debian/Ubuntu/Raspbian

Source: https://github.com/element-hq/synapse/blob/develop/docs/setup/installation.md

System packages required for building Synapse dependencies on Debian-based systems.

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

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

### Remove and Recreate Poetry Virtual Environment

Source: https://github.com/element-hq/synapse/blob/develop/docs/development/dependencies.md

Commands to completely remove the current virtual environment and then recreate it by installing all dependencies. This is useful for starting fresh.

```shell
deactivate
```

```shell
poetry env remove --all
```

```shell
poetry shell
```

```shell
poetry install --extras all
```

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

### Inspect Poetry Virtual Environment

Source: https://github.com/element-hq/synapse/blob/develop/docs/development/dependencies.md

Commands to get information about the current or all Poetry managed virtual environments, and to list installed packages within the active environment.

```shell
poetry env info
```

```shell
poetry env list --full-path
```

```shell
poetry run pip list
```

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

### Example JSON Response for Room Messages API

Source: https://github.com/element-hq/synapse/blob/develop/docs/admin_api/rooms.md

This JSON structure represents a typical response from the Room Messages API, including a chunk of events, and start and end tokens for pagination. The 'chunk' contains event details like content, sender, and type.

```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"
}
```

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

### Configure OpenBSD Build Environment

Source: https://github.com/element-hq/synapse/blob/develop/docs/setup/installation.md

Setup wxallowed filesystem directories and build configuration for Synapse on OpenBSD.

```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
```

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

### Copy Sample Configuration Files

Source: https://github.com/element-hq/synapse/blob/develop/docs/development/contributing_guide.md

Before running Synapse, copy the sample configuration files to your project directory. Ensure you edit `homeserver.yaml` to set `server_name`, adjust paths, and configure database and registration settings as needed.

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

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

### Install Specific Dependency

Source: https://github.com/element-hq/synapse/blob/develop/docs/setup/installation.md

If pip encounters memory issues during installation, you can install failing dependencies individually.

```sh
pip install twisted
```

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

### Install OIDC dependencies for Synapse

Source: https://github.com/element-hq/synapse/blob/develop/docs/openid.md

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

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

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

### Install Django and django-mama-cas

Source: https://github.com/element-hq/synapse/blob/develop/docs/development/cas.md

Install the required packages for the CAS server implementation.

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

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

### Run Synapse Homeserver

Source: https://github.com/element-hq/synapse/blob/develop/docs/upgrade.md

Starts the Synapse homeserver using a specified configuration file. Ensure the configuration file is correctly set up before running.

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

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

### Initialize Django Project

Source: https://github.com/element-hq/synapse/blob/develop/docs/development/cas.md

Create a new Django project in the current directory.

```sh
django-admin startproject cas_test .
```

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

### ExamplePresenceRouter Class Implementation

Source: https://github.com/element-hq/synapse/blob/develop/docs/presence_router_module.md

An example implementation of Synapse's PresenceRouter, supporting routing all presence to specific users or subsets of presence to room members. Requires a configuration object and Synapse's ModuleApi.

```python
class ExamplePresenceRouter:
    """An example implementation of synapse.presence_router.PresenceRouter.
    Supports routing all presence to a configured set of users, or a subset
    of presence from certain users to members of certain rooms.

    Args:
        config: A configuration object.
        module_api: An instance of Synapse's ModuleApi.
    """
    def __init__(self, config: PresenceRouterConfig, module_api: ModuleApi):
        self._config = config
        self._module_api = module_api
```

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

### Create Python Virtual Environment

Source: https://github.com/element-hq/synapse/blob/develop/docs/setup/installation.md

Set up a Python 3.12 virtual environment and install Synapse via pip.

```bash
mkdir -p ~/synapse
# To use Python 3.11, simply use the command "python3.11" instead.
python3.12 -m venv ~/synapse/env
source ~/synapse/env/bin/activate
pip install --upgrade pip
pip install --upgrade setuptools
pip install matrix-synapse
```

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

### Run Synapse Local Instance

Source: https://github.com/element-hq/synapse/blob/develop/docs/development/contributing_guide.md

Start a local Synapse instance using the poetry environment and the configured `homeserver.yaml` file. This command launches the Synapse homeserver application.

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

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

### Install Python 3.11 on RHEL

Source: https://github.com/element-hq/synapse/blob/develop/docs/setup/installation.md

Commands to install newer Python versions on RHEL-based distributions.

```bash
# Python 3.11
dnf install python3.11 python3.11-devel
```

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

### Install Synapse Prerelease via Matrix.org Repository

Source: https://github.com/element-hq/synapse/blob/develop/docs/setup/installation.md

Commands to enable the prerelease channel in the Matrix.org repository for testing release candidates.

```sh
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
```

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

### Serve Synapse Documentation Locally

Source: https://github.com/element-hq/synapse/blob/develop/docs/README.md

Serve the Synapse documentation on a local webserver with hot-reload functionality using mdbook. The URL will be logged.

```sh
mdbook serve
```

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

### Install Synapse Dependencies

Source: https://github.com/element-hq/synapse/blob/develop/docs/upgrade.md

Commands to update or install required Python dependencies for specific Synapse versions.

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

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

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

### Install Redis dependencies for Synapse

Source: https://github.com/element-hq/synapse/blob/develop/docs/workers.md

Install the necessary Python dependencies to enable Redis support for Synapse workers.

```sh
pip install "matrix-synapse[redis]"
```

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

### Start Django Development Server

Source: https://github.com/element-hq/synapse/blob/develop/docs/development/cas.md

Launch the test server to host CAS endpoints on port 8000.

```sh
python manage.py runserver
```

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

### Configure Manhole Listener for Native Installations

Source: https://github.com/element-hq/synapse/blob/develop/docs/manhole.md

Bind the manhole listener to local loopback addresses for non-Docker installations.

```yaml
listeners:
  - port: 9000
    bind_addresses: ['::1', '127.0.0.1']
    type: manhole
```

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

### Build Synapse Documentation

Source: https://github.com/element-hq/synapse/blob/develop/docs/README.md

Build the Synapse documentation locally using mdbook. The rendered contents will be available in the 'book/' directory.

```sh
mdbook build
```

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

### Largest Rooms Response Example

Source: https://github.com/element-hq/synapse/blob/develop/docs/admin_api/statistics.md

Example JSON response body for the largest rooms by database size endpoint.

```json
{
  "rooms": [
    {
      "room_id": "!OGEhHVWSdvArJzumhm:matrix.org",
      "estimated_size": 47325417353
    }
  ]
}
```

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

### Run unit tests with trial

Source: https://github.com/element-hq/synapse/blob/develop/docs/development/contributing_guide.md

Executes the full suite of unit tests using the poetry environment.

```sh
poetry run trial tests
```

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

### Inspect installed package version in Docker

Source: https://github.com/element-hq/synapse/blob/develop/docs/development/dependencies.md

Verifies the actual version of a package installed within a Synapse Docker image.

```bash
$ docker pull matrixdotorg/synapse:latest
...
$ docker run --entrypoint pip matrixdotorg/synapse:latest show phonenumbers
Name: phonenumbers
Version: 9.0.15
Summary: Python version of Google's common library for parsing, formatting, storing and validating international phone numbers.
Home-page: https://github.com/daviddrysdale/python-phonenumbers
Author: David Drysdale
Author-email: dmd@lurklurk.org
License: Apache License 2.0
Location: /usr/local/lib/python3.12/site-packages
Requires:
Required-by: matrix-synapse
```

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

### Generate Synapse Configuration

Source: https://github.com/element-hq/synapse/blob/develop/docs/setup/installation.md

Command to initialize the homeserver configuration file.

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

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

### Install Synapse from Downstream Debian Repository

Source: https://github.com/element-hq/synapse/blob/develop/docs/setup/installation.md

Command to install the community-maintained Synapse package available in Debian repositories for specific releases.

```sh
sudo apt install matrix-synapse
```

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

### SAML Mapping Provider __init__ Method

Source: https://github.com/element-hq/synapse/blob/develop/docs/sso_mapping_providers.md

The `__init__` method is used to initialize the mapping provider with configuration and the module API. It should set up any necessary configuration options.

```python
def __init__(self, parsed_config, module_api)
```

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

### User Media Statistics Response Example

Source: https://github.com/element-hq/synapse/blob/develop/docs/admin_api/statistics.md

Example JSON response body for the user media statistics endpoint, showing user details and media counts.

```json
{
  "users": [
    {
      "displayname": "foo_user_0",
      "media_count": 2,
      "media_length": 134,
      "user_id": "@foo_user_0:test"
    },
    {
      "displayname": "foo_user_1",
      "media_count": 2,
      "media_length": 134,
      "user_id": "@foo_user_1:test"
    }
  ],
  "next_token": 3,
  "total": 10
}
```

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

### Build a test wheel

Source: https://github.com/element-hq/synapse/blob/develop/docs/development/dependencies.md

Uses the build tool to create a distribution wheel. This is the preferred method for CI consistency.

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

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

### Run tests with existing PostgreSQL installation

Source: https://github.com/element-hq/synapse/blob/develop/docs/development/contributing_guide.md

Configures environment variables to point to a local PostgreSQL instance.

```shell
export SYNAPSE_POSTGRES=1
export SYNAPSE_POSTGRES_HOST=localhost
export SYNAPSE_POSTGRES_USER=postgres
export SYNAPSE_POSTGRES_PASSWORD=mydevenvpassword
trial
```

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

### Example Registration Flow Submission

Source: https://github.com/element-hq/synapse/blob/develop/docs/upgrade.md

An example of submitting registration data using the m.login.password flow. This format is used for user registration and closely matches the login API.

```json
{
  type: m.login.password,
  user: foo,
  password: bar
}
```