Skip to content
Snippets Groups Projects
Select Git revision
  • tedomum default
  • deploy-exploding-state-groups
  • fix-exploding-state-groups
  • v1.127.1+tedomum.1
  • v1.125.0+tedomum.1
  • v1.123.0+tedomum.1
  • v1.122.0+tedomum.1
  • v1.121.1+tedomum.1
  • v1.119.0+tedomum.1
  • v1.118.0+tedomum.1
  • v1.114.0+tedomum.1
  • v1.109.0+tedomum.1
  • v1.105.1+tedomum.1
  • v1.98.0+tedomum.1
  • v1.97.0+tedomum.1
  • v1.96.1+tedomum.1
  • v1.95.1+tedomum.1
  • v1.88.0+tedomum.1
  • v1.73.0
  • v1.73.0rc2
  • v1.73.0rc1
  • v1.72.0
  • v1.72.0rc1
23 results
Blame Permalink
INSTALL.md 20.16 KiB

Installation Instructions

There are 3 steps to follow under Installation Instructions.

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.

Installing Synapse

Installing from source

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

When installing from source please make sure that the Platform-specific prerequisites are already installed.

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

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 prerequisites

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.

Debian/Ubuntu/Raspbian

Installing prerequisites on Ubuntu or Debian:

sudo apt 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 or Fedora Linux:

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
sudo dnf groupinstall "Development Tools"
macOS

Installing prerequisites on macOS:

xcode-select --install
sudo easy_install pip
sudo pip install virtualenv
brew install pkg-config libffi

On macOS Catalina (10.15) you may need to explicitly install OpenSSL via brew and inform pip about it so that psycopg2 builds:

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

Installing prerequisites on openSUSE:

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
OpenBSD

A port of Synapse is available under net/synapse. The filesystem underlying the homeserver directory (defaults to /var/synapse) has to be mounted with wxallowed (cf. mount(8)), so creating a separate filesystem and mounting it to /var/synapse should be taken into consideration.

To be able to build Synapse's dependency on python the WRKOBJDIR (cf. bsd.port.mk(5)) for building python, too, needs to be on a filesystem mounted with wxallowed (cf. mount(8)).

Creating a WRKOBJDIR for building python under /usr/local (which on a default OpenBSD installation is mounted with wxallowed):

doas mkdir /usr/local/pobj_wxallowed

Assuming PORTS_PRIVSEP=Yes (cf. bsd.port.mk(5)) and SUDO=doas are configured in /etc/mk.conf:

doas chown _pbuild:_pbuild /usr/local/pobj_wxallowed