INSTALL.md

• Choosing your server name
• Picking a database engine
• Installing Synapse
  • Installing from source
    • Platform-Specific Instructions
  • Prebuilt packages
• Setting up Synapse
  • TLS certificates
  • Client Well-Known URI
  • Email
  • Registering a user
  • Setting up a TURN server
  • URL previews
• Troubleshooting Installation

Choosing your server name

It is important to choose the name for your server before you install Synapse, because it cannot be changed later.

The server name determines the "domain" part of user-ids for users on your server: these will all be of the format @user:my.domain.name. It also determines how other matrix servers will reach yours for federation.

For a test configuration, set this to the hostname of your server. For a more production-ready setup, you will probably want to specify your domain (example.com) rather than a matrix-specific hostname here (in the same way that your email address is probably user@example.com rather than user@email.example.com) - but doing so may require more advanced setup: see Setting up Federation.

Picking a database engine

Synapse offers two database engines:

• PostgreSQL
• SQLite

Almost all installations should opt to use PostgreSQL. Advantages include:

• significant performance improvements due to the superior threading and caching model, smarter query optimiser
• allowing the DB to be run on separate hardware

For information on how to install and use PostgreSQL, please see docs/postgres.md

By default Synapse uses SQLite and in doing so trades performance for convenience. SQLite is only recommended in Synapse for testing purposes or for servers with light workloads.

Installing Synapse

Installing from source

(Prebuilt packages are available for some platforms - see Prebuilt packages.)

System requirements:

• POSIX-compliant system (tested on Linux & OS X)
• Python 3.5.2 or later, up to Python 3.9.
• At least 1GB of free RAM if you want to join large public rooms like #matrix:matrix.org

Synapse is written in Python but some of the libraries it uses are written in C. So before we can install Synapse itself we need a working C compiler and the header files for Python C extensions. See Platform-Specific Instructions for information on installing these on various platforms.

To install the Synapse homeserver run:

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

This will download Synapse from PyPI and install it, along with the python libraries it uses, into a virtual environment under ~/synapse/env. Feel free to pick a different directory if you prefer.

This Synapse installation can then be later upgraded by using pip again with the update flag:

source ~/synapse/env/bin/activate
pip install -U matrix-synapse

Before you can start Synapse, you will need to generate a configuration file. To do this, run (in your virtualenv, as before):

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

... substituting an appropriate value for --server-name.

This command will generate you a config file that you can then customise, but it will also generate a set of keys for you. These keys will allow your homeserver to identify itself to other homeserver, so don't lose or delete them. It would be wise to back them up somewhere safe. (If, for whatever reason, you do need to change your homeserver's keys, you may find that other homeserver have the old key cached. If you update the signing key, you should change the name of the key in the <server name>.signing.key file (the second word) to something different. See the spec for more information on key management).

To actually run your new homeserver, pick a working directory for Synapse to run (e.g. ~/synapse), and:

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

Platform-Specific Instructions

Debian/Ubuntu/Raspbian

Installing prerequisites on Ubuntu or Debian:

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

ArchLinux

Installing prerequisites on ArchLinux:

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

CentOS/Fedora

Installing prerequisites on CentOS 8 or Fedora>26:

sudo dnf install libtiff-devel libjpeg-devel libzip-devel freetype-devel \
                 libwebp-devel tk-devel redhat-rpm-config \
                 python3-virtualenv libffi-devel openssl-devel
sudo dnf groupinstall "Development Tools"

Installing prerequisites on CentOS 7 or Fedora<=25: