488 lines
17 KiB
Markdown
488 lines
17 KiB
Markdown
![]() |
* [Installing Synapse](#installing-synapse)
|
||
|
* [Installing from source](#installing-from-source)
|
||
|
* [Platform-Specific Instructions](#platform-specific-instructions)
|
||
|
* [Troubleshooting Installation](#troubleshooting-installation)
|
||
|
* [Prebuilt packages](#prebuilt-packages)
|
||
|
* [Setting up Synapse](#setting-up-synapse)
|
||
|
* [TLS certificates](#tls-certificates)
|
||
|
* [Registering a user](#registering-a-user)
|
||
|
* [Setting up a TURN server](#setting-up-a-turn-server)
|
||
|
* [URL previews](#url-previews)
|
||
|
|
||
|
# Installing Synapse
|
||
|
|
||
|
## Installing from source
|
||
|
|
||
|
(Prebuilt packages are available for some platforms - see [Prebuilt packages](#prebuilt-packages).)
|
||
|
|
||
|
System requirements:
|
||
|
|
||
|
- POSIX-compliant system (tested on Linux & OS X)
|
||
|
- Python 3.5, 3.6, 3.7, or 2.7
|
||
|
- 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](#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[all]
|
||
|
```
|
||
|
|
||
|
This will download Synapse from [PyPI](https://pypi.org/project/matrix-synapse)
|
||
|
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[all]
|
||
|
```
|
||
|
|
||
|
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`. 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](README.rst#setting-up-federation). Beware that the server name cannot be changed later.
|
||
|
|
||
|
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 Home Server to
|
||
|
identify itself to other Home Servers, 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 Home Server's keys, you may find that other Home Servers 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](https://matrix.org/docs/spec/server_server/latest.html#retrieving-server-keys)
|
||
|
for more information on key management.)
|
||
|
|
||
|
You will need to give Synapse a TLS certficate before it will start - see [TLS
|
||
|
certificates](#tls-certificates).
|
||
|
|
||
|
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 \
|
||
|
python-pip python-setuptools sqlite3 \
|
||
|
libssl-dev python-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 7 or Fedora 25:
|
||
|
|
||
|
```
|
||
|
sudo yum install libtiff-devel libjpeg-devel libzip-devel freetype-devel \
|
||
|
lcms2-devel libwebp-devel tcl-devel tk-devel redhat-rpm-config \
|
||
|
python-virtualenv libffi-devel openssl-devel
|
||
|
sudo yum groupinstall "Development Tools"
|
||
|
```
|
||
|
|
||
|
#### Mac OS X
|
||
|
|
||
|
Installing prerequisites on Mac OS X:
|
||
|
|
||
|
```
|
||
|
xcode-select --install
|
||
|
sudo easy_install pip
|
||
|
sudo pip install virtualenv
|
||
|
brew install pkg-config libffi
|
||
|
```
|
||
|
|
||
|
#### 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
|
||
|
|
||
|
Installing prerequisites on OpenBSD:
|
||
|
|
||
|
```
|
||
|
doas pkg_add python libffi py-pip py-setuptools sqlite3 py-virtualenv \
|
||
|
libxslt jpeg
|
||
|
```
|
||
|
|
||
|
There is currently no port for OpenBSD. Additionally, OpenBSD's security
|
||
|
settings require a slightly more difficult installation process.
|
||
|
|
||
|
XXX: I suspect this is out of date.
|
||
|
|
||
|
1. Create a new directory in `/usr/local` called `_synapse`. Also, create a
|
||
|
new user called `_synapse` and set that directory as the new user's home.
|
||
|
This is required because, by default, OpenBSD only allows binaries which need
|
||
|
write and execute permissions on the same memory space to be run from
|
||
|
`/usr/local`.
|
||
|
2. `su` to the new `_synapse` user and change to their home directory.
|
||
|
3. Create a new virtualenv: `virtualenv -p python2.7 ~/.synapse`
|
||
|
4. Source the virtualenv configuration located at
|
||
|
`/usr/local/_synapse/.synapse/bin/activate`. This is done in `ksh` by
|
||
|
using the `.` command, rather than `bash`'s `source`.
|
||
|
5. Optionally, use `pip` to install `lxml`, which Synapse needs to parse
|
||
|
webpages for their titles.
|
||
|
6. Use `pip` to install this repository: `pip install matrix-synapse`
|
||
|
7. Optionally, change `_synapse`'s shell to `/bin/false` to reduce the
|
||
|
chance of a compromised Synapse server being used to take over your box.
|
||
|
|
||
|
After this, you may proceed with the rest of the install directions.
|
||
|
|
||
|
#### Windows
|
||
|
|
||
|
If you wish to run or develop Synapse on Windows, the Windows Subsystem For
|
||
|
Linux provides a Linux environment on Windows 10 which is capable of using the
|
||
|
Debian, Fedora, or source installation methods. More information about WSL can
|
||
|
be found at https://docs.microsoft.com/en-us/windows/wsl/install-win10 for
|
||
|
Windows 10 and https://docs.microsoft.com/en-us/windows/wsl/install-on-server
|
||
|
for Windows Server.
|
||
|
|
||
|
### Troubleshooting Installation
|
||
|
|
||
|
XXX a bunch of this is no longer relevant.
|
||
|
|
||
|
Synapse requires pip 8 or later, so if your OS provides too old a version you
|
||
|
may need to manually upgrade it::
|
||
|
|
||
|
sudo pip install --upgrade pip
|
||
|
|
||
![]() |
Installing may fail with `Could not find any downloads that satisfy the requirement pymacaroons-pynacl (from matrix-synapse==0.12.0)`.
|
||
![]() |
You can fix this by manually upgrading pip and virtualenv::
|
||
|
|
||
|
sudo pip install --upgrade virtualenv
|
||
|
|
||
![]() |
You can next rerun `virtualenv -p python3 synapse` to update the virtual env.
|
||
![]() |
|
||
![]() |
Installing may fail during installing virtualenv with `InsecurePlatformWarning: A true SSLContext object is not available. This prevents urllib3 from configuring SSL appropriately and may cause certain SSL connections to fail. For more information, see https://urllib3.readthedocs.org/en/latest/security.html#insecureplatformwarning.`
|
||
![]() |
You can fix this by manually installing ndg-httpsclient::
|
||
|
|
||
|
pip install --upgrade ndg-httpsclient
|
||
|
|
||
![]() |
Installing may fail with `mock requires setuptools>=17.1. Aborting installation`.
|
||
![]() |
You can fix this by upgrading setuptools::
|
||
|
|
||
|
pip install --upgrade setuptools
|
||
|
|
||
|
If pip crashes mid-installation for reason (e.g. lost terminal), pip may
|
||
|
refuse to run until you remove the temporary installation directory it
|
||
|
created. To reset the installation::
|
||
|
|
||
|
rm -rf /tmp/pip_install_matrix
|
||
|
|
||
|
pip seems to leak *lots* of memory during installation. For instance, a Linux
|
||
|
host with 512MB of RAM may run out of memory whilst installing Twisted. If this
|
||
|
happens, you will have to individually install the dependencies which are
|
||
|
failing, e.g.::
|
||
|
|
||
|
pip install twisted
|
||
|
|
||
|
## Prebuilt packages
|
||
|
|
||
|
As an alternative to installing from source, prebuilt packages are available
|
||
|
for a number of platforms.
|
||
|
|
||
|
### Docker images and Ansible playbooks
|
||
|
|
||
|
There is an offical synapse image available at
|
||
|
https://hub.docker.com/r/matrixdotorg/synapse which can be used with
|
||
|
the docker-compose file available at [contrib/docker](contrib/docker). Further information on
|
||
|
this including configuration options is available in the README on
|
||
|
hub.docker.com.
|
||
|
|
||
|
Alternatively, Andreas Peters (previously Silvio Fricke) has contributed a
|
||
|
Dockerfile to automate a synapse server in a single Docker image, at
|
||
|
https://hub.docker.com/r/avhost/docker-matrix/tags/
|
||
|
|
||
|
Slavi Pantaleev has created an Ansible playbook,
|
||
|
which installs the offical Docker image of Matrix Synapse
|
||
|
along with many other Matrix-related services (Postgres database, riot-web, coturn, mxisd, SSL support, etc.).
|
||
|
For more details, see
|
||
|
https://github.com/spantaleev/matrix-docker-ansible-deploy
|
||
|
|
||
|
|
||
|
### Debian/Ubuntu
|
||
|
|
||
|
#### Matrix.org packages
|
||
|
|
||
|
Matrix.org provides Debian/Ubuntu packages of the latest stable version of
|
||
|
Synapse via https://matrix.org/packages/debian/. To use them:
|
||
|
|
||
|
```
|
||
|
sudo apt install -y lsb-release curl apt-transport-https
|
||
|
echo "deb https://matrix.org/packages/debian `lsb_release -cs` main" |
|
||
|
sudo tee /etc/apt/sources.list.d/matrix-org.list
|
||
|
curl "https://matrix.org/packages/debian/repo-key.asc" |
|
||
|
sudo apt-key add -
|
||
|
sudo apt update
|
||
|
sudo apt install matrix-synapse-py3
|
||
|
```
|
||
|
|
||
|
#### Downstream Debian/Ubuntu packages
|
||
|
|
||
|
For `buster` and `sid`, Synapse is available in the Debian repositories and
|
||
|
it should be possible to install it with simply:
|
||
|
|
||
|
```
|
||
|
sudo apt install matrix-synapse
|
||
|
```
|
||
|
|
||
|
There is also a version of `matrix-synapse` in `stretch-backports`. Please see
|
||
|
the [Debian documentation on
|
||
|
backports](https://backports.debian.org/Instructions/) for information on how
|
||
|
to use them.
|
||
|
|
||
|
We do not recommend using the packages in downstream Ubuntu at this time, as
|
||
|
they are old and suffer from known security vulnerabilities.
|
||
|
|
||
|
### Fedora
|
||
|
|
||
|
Synapse is in the Fedora repositories as `matrix-synapse`:
|
||
|
|
||
|
```
|
||
|
sudo dnf install matrix-synapse
|
||
|
```
|
||
|
|
||
|
Oleg Girko provides Fedora RPMs at
|
||
|
https://obs.infoserver.lv/project/monitor/matrix-synapse
|
||
|
|
||
|
### OpenSUSE
|
||
|
|
||
|
Synapse is in the OpenSUSE repositories as `matrix-synapse`:
|
||
|
|
||
|
```
|
||
|
sudo zypper install matrix-synapse
|
||
|
```
|
||
|
|
||
|
### SUSE Linux Enterprise Server
|
||
|
|
||
|
Unofficial package are built for SLES 15 in the openSUSE:Backports:SLE-15 repository at
|
||
|
https://download.opensuse.org/repositories/openSUSE:/Backports:/SLE-15/standard/
|
||
|
|
||
|
### ArchLinux
|
||
|
|
||
|
The quickest way to get up and running with ArchLinux is probably with the community package
|
||
|
https://www.archlinux.org/packages/community/any/matrix-synapse/, which should pull in most of
|
||
|
the necessary dependencies.
|
||
|
|
||
|
pip may be outdated (6.0.7-1 and needs to be upgraded to 6.0.8-1 ):
|
||
|
|
||
|
```
|
||
|
sudo pip install --upgrade pip
|
||
|
```
|
||
|
|
||
|
If you encounter an error with lib bcrypt causing an Wrong ELF Class:
|
||
|
ELFCLASS32 (x64 Systems), you may need to reinstall py-bcrypt to correctly
|
||
|
compile it under the right architecture. (This should not be needed if
|
||
|
installing under virtualenv):
|
||
|
|
||
|
```
|
||
|
sudo pip uninstall py-bcrypt
|
||
|
sudo pip install py-bcrypt
|
||
|
```
|
||
|
|
||
|
### FreeBSD
|
||
|
|
||
|
Synapse can be installed via FreeBSD Ports or Packages contributed by Brendan Molloy from:
|
||
|
|
||
|
- Ports: `cd /usr/ports/net-im/py-matrix-synapse && make install clean`
|
||
|
- Packages: `pkg install py27-matrix-synapse`
|
||
|
|
||
|
|
||
|
### NixOS
|
||
|
|
||
|
Robin Lambertz has packaged Synapse for NixOS at:
|
||
|
https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/services/misc/matrix-synapse.nix
|
||
|
|
||
|
# Setting up Synapse
|
||
|
|
||
|
Once you have installed synapse as above, you will need to configure it.
|
||
|
|
||
|
## TLS certificates
|
||
|
|
||
|
The default configuration exposes two HTTP ports: 8008 and 8448. Port 8008 is
|
||
|
configured without TLS; it should be behind a reverse proxy for TLS/SSL
|
||
|
termination on port 443 which in turn should be used for clients. Port 8448
|
||
|
is configured to use TLS for Federation with a self-signed or verified
|
||
|
certificate, but please be aware that a valid certificate will be required in
|
||
|
Synapse v1.0.
|
||
|
|
||
|
If you would like to use your own certificates, you can do so by changing
|
||
|
`tls_certificate_path` and `tls_private_key_path` in `homeserver.yaml`;
|
||
|
alternatively, you can use a reverse-proxy. Apart from port 8448 using TLS,
|
||
|
both ports are the same in the default configuration.
|
||
|
|
||
|
### ACME setup
|
||
|
|
||
|
Synapse v1.0 will require valid TLS certificates for communication between servers
|
||
|
(port `8448` by default) in addition to those that are client-facing (port
|
||
|
`443`). In the case that your `server_name` config variable is the same as
|
||
|
the hostname that the client connects to, then the same certificate can be
|
||
|
used between client and federation ports without issue. Synapse v0.99.0+
|
||
|
**will provision server-to-server certificates automatically for you for
|
||
|
free** through [Let's Encrypt](https://letsencrypt.org/) if you tell it to.
|
||
|
|
||
|
In order for Synapse to complete the ACME challenge to provision a
|
||
|
certificate, it needs access to port 80. Typically listening on port 80 is
|
||
|
only granted to applications running as root. There are thus two solutions to
|
||
|
this problem.
|
||
|
|
||
|
#### Using a reverse proxy
|
||
|
|
||
|
A reverse proxy such as Apache or nginx allows a single process (the web
|
||
|
server) to listen on port 80 and proxy traffic to the appropriate program
|
||
|
running on your server. It is the recommended method for setting up ACME as
|
||
|
it allows you to use your existing webserver while also allowing Synapse to
|
||
|
provision certificates as needed.
|
||
|
|
||
|
For nginx users, add the following line to your existing `server` block:
|
||
|
|
||
|
```
|
||
|
location /.well-known/acme-challenge {
|
||
|
proxy_pass http://localhost:8009/;
|
||
|
}
|
||
|
```
|
||
|
|
||
|
For Apache, add the following to your existing webserver config::
|
||
|
|
||
|
```
|
||
|
ProxyPass /.well-known/acme-challenge http://localhost:8009/.well-known/acme-challenge
|
||
|
```
|
||
|
|
||
|
Make sure to restart/reload your webserver after making changes.
|
||
|
|
||
|
|
||
|
#### Authbind
|
||
|
|
||
|
`authbind` allows a program which does not run as root to bind to
|
||
|
low-numbered ports in a controlled way. The setup is simpler, but requires a
|
||
|
webserver not to already be running on port 80. **This includes every time
|
||
|
Synapse renews a certificate**, which may be cumbersome if you usually run a
|
||
|
web server on port 80. Nevertheless, if you're sure port 80 is not being used
|
||
|
for any other purpose then all that is necessary is the following:
|
||
|
|
||
|
Install `authbind`. For example, on Debian/Ubuntu:
|
||
|
|
||
|
```
|
||
|
sudo apt-get install authbind
|
||
|
```
|
||
|
|
||
|
Allow `authbind` to bind port 80:
|
||
|
|
||
|
```
|
||
|
sudo touch /etc/authbind/byport/80
|
||
|
sudo chmod 777 /etc/authbind/byport/80
|
||
|
```
|
||
|
|
||
|
When Synapse is started, use the following syntax::
|
||
|
|
||
|
```
|
||
|
authbind --deep <synapse start command>
|
||
|
```
|
||
|
|
||
|
Finally, once Synapse is able to listen on port 80 for ACME challenge
|
||
|
requests, it must be told to perform ACME provisioning by setting `enabled`
|
||
|
to true under the `acme` section in `homeserver.yaml`:
|
||
|
|
||
|
```
|
||
|
acme:
|
||
|
enabled: true
|
||
|
```
|
||
|
|
||
|
## Registering a user
|
||
|
|
||
|
You will need at least one user on your server in order to use a Matrix
|
||
|
client. Users can be registered either via a Matrix client, or via a
|
||
|
commandline script.
|
||
|
|
||
|
To get started, it is easiest to use the command line to register new
|
||
|
users. This can be done as follows:
|
||
|
|
||
|
```
|
||
|
$ source ~/synapse/env/bin/activate
|
||
|
$ synctl start # if not already running
|
||
|
$ register_new_matrix_user -c homeserver.yaml https://localhost:8448
|
||
|
New user localpart: erikj
|
||
|
Password:
|
||
|
Confirm password:
|
||
|
Make admin [no]:
|
||
|
Success!
|
||
|
```
|
||
|
|
||
![]() |
This process uses a setting `registration_shared_secret` in
|
||
|
`homeserver.yaml`, which is shared between Synapse itself and the
|
||
|
`register_new_matrix_user` script. It doesn't matter what it is (a random
|
||
|
value is generated by `--generate-config`), but it should be kept secret, as
|
||
![]() |
anyone with knowledge of it can register users on your server even if
|
||
![]() |
`enable_registration` is `false`.
|
||
![]() |
|
||
|
## Setting up a TURN server
|
||
|
|
||
|
For reliable VoIP calls to be routed via this homeserver, you MUST configure
|
||
|
a TURN server. See [docs/turn-howto.rst](docs/turn-howto.rst) for details.
|
||
|
|
||
|
## URL previews
|
||
|
|
||
|
Synapse includes support for previewing URLs, which is disabled by default. To
|
||
![]() |
turn it on you must enable the `url_preview_enabled: True` config parameter
|
||
![]() |
and explicitly specify the IP ranges that Synapse is not allowed to spider for
|
||
![]() |
previewing in the `url_preview_ip_range_blacklist` configuration parameter.
|
||
![]() |
This is critical from a security perspective to stop arbitrary Matrix users
|
||
|
spidering 'internal' URLs on your network. At the very least we recommend that
|
||
|
your loopback and RFC1918 IP addresses are blacklisted.
|
||
|
|
||
|
This also requires the optional lxml and netaddr python dependencies to be
|
||
|
installed. This in turn requires the libxml2 library to be available - on
|
||
![]() |
Debian/Ubuntu this means `apt-get install libxml2-dev`, or equivalent for
|
||
![]() |
your OS.
|