Fediversity/matrix/synapse/README.md

---
gitea: none
include_toc: true
---

# Installation and configuration of Synapse

Mind you: this an installation on Debian Linux (at least for now).

Start by installing the latest Synapse server, see the [upstream
documentation](https://element-hq.github.io/synapse/latest/setup/installation.html).

```
apt install -y lsb-release wget apt-transport-https build-essential python3-dev libffi-dev \
               python3-pip python3-setuptools sqlite3 \
               libssl-dev virtualenv libjpeg-dev libxslt1-dev libicu-dev

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" |
    tee /etc/apt/sources.list.d/matrix-org.list

apt update
apt install matrix-synapse-py3
```

This leaves a very basic configuration in `/etc/matrix-synapse/homeserver.yaml`
and  two settings under `/etc/conf.d`. All other configuration items will also
be configured with yaml-files in this directory.

Configure the domain you with to use in `/etc/matrix-synapse/conf.d/server_name.yaml`.
What you configure here will also be the global part of your Matrix handles
(the part after the colon).

You now have a standard Matrix server that uses sqlite. You really don't want
to use this in production, so probably want to replace this with PostgreSQL.

There are two different ways to configure Synapse, documented here:

* [Monolithic](monolithic)
* [Workers](workers)

We'll use Synapse, using the workers architecture to make it scalable, flexible and reusable.


## Listeners

A fresh installation configures one listener, for both client and federation
traffic. This listens on port 8008 on localhost (IPv4 and IPv6) and does not
do TLS:

```
listeners:
  - port: 8008
    tls: false
    type: http
    x_forwarded: true
    bind_addresses: ['::1', '127.0.0.1']
    resources:
      - names: [client, federation]
        compress: false
```

## Database

The default installation leaves you with an sqlite3 database. Nice for experimenting, but
unsuitable for a production environment.

[Here's how you setup PostgreSQL](../postgresql).

Once you've created a database and user in PostgreSQL, you configure Synapse
to use it.

First delete (or comment out) the SQLITE datbase in `homeserver.yaml`:

```
#database:
#  name: sqlite3
#  args:
#    database: /var/lib/matrix-synapse/homeserver.db
```

Then create the database configuration for PostgreSQL in
`conf.d/database.yaml`:

```
database:
  name: psycopg2
  args:
    user: synapse
    password: <password>
    dbname: synapse
    host: /var/run/postgresql
    cp_min: 5
    cp_max: 10
```

Note: you configure the directory where the UNIX socket file lives, not the
actual file.

Of course, if you use localhost, you should configure it like this:

```
    host: localhost
    port: 5432
```

After changing the database, restart Synapse and check whether it can connect
and create the tables it needs.


## Create admin

Synapse doesn't create an admin account at install time, so you'll have to do
that yourself.

You need to set a `registration_shared_secret` for this, set that in
`conf.d/keys.yaml` like this:

```
registration_shared_secret: xxxx
```

You can create such a key by running `pwgen -csn 52 1`. Restart Synapse after
setting this key.

Now create an admin user. Login and issue this command:

```
register_new_matrix_user -u admin -a -c /etc/matrix-synapse/conf.d/keys.yaml
```

This will ask for a password, choose a safe one.


## Logging

Logging is configured in `log.yaml`. Some logging should go to systemd, the
more specific logging to Synapse's own logfile(s).


# Delegation and DNS

If you run your server under a different FQDN than just the domain name you
want to use, you need to delegate: point from your domain to the server.

Example. You want to use example.com for your domain, but your server is
called matrix.example.com. To make that work, you need to serve 2 bits of
JSON-code on example.com to point clients and servers to the correct
machine: matrix.example.com.

Pointing servers to the correct server is done by publishing this bit of
JSON-code under `https://example.com/.well-known/matrix/server`:

```
{
  "m.homeserver": {"base_url": "https://matrix.example.com"},
  "org.matrix.msc3575.proxy": {"url": "https://matrix.example.com"}
}
```

Pointing clients to the correct server needs this at
`https://example.com/.well-known/matrix/client`:

```
{
  "m.server": "matrix.example.com"
}
```

Very important: both names (example.com and matrix.example.com) must be A
and/or AAAA records in DNS, not CNAME.