diff options
Diffstat (limited to 'INSTALL.md')
| -rw-r--r-- | INSTALL.md | 487 |
1 files changed, 487 insertions, 0 deletions
diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 0000000000..a04524cdc7 --- /dev/null +++ b/INSTALL.md @@ -0,0 +1,487 @@ +* [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. |