mirror of
https://git.anonymousland.org/anonymousland/synapse-product.git
synced 2024-09-09 15:02:09 +00:00
Merge branch 'release-v0.99.0' of github.com:matrix-org/synapse into anoa/self_signed_upgrade
This commit is contained in:
commit
c433d4c4d2
@ -4,8 +4,8 @@ jobs:
|
|||||||
machine: true
|
machine: true
|
||||||
steps:
|
steps:
|
||||||
- checkout
|
- checkout
|
||||||
- run: docker build -f docker/Dockerfile --label gitsha1=${CIRCLE_SHA1} -t matrixdotorg/synapse:${CIRCLE_TAG} .
|
- run: docker build -f docker/Dockerfile --label gitsha1=${CIRCLE_SHA1} -t matrixdotorg/synapse:${CIRCLE_TAG}-py2 .
|
||||||
- run: docker build -f docker/Dockerfile --label gitsha1=${CIRCLE_SHA1} -t matrixdotorg/synapse:${CIRCLE_TAG}-py3 --build-arg PYTHON_VERSION=3.6 .
|
- run: docker build -f docker/Dockerfile --label gitsha1=${CIRCLE_SHA1} -t matrixdotorg/synapse:${CIRCLE_TAG} -t matrixdotorg/synapse:${CIRCLE_TAG}-py3 --build-arg PYTHON_VERSION=3.6 .
|
||||||
- run: docker login --username $DOCKER_HUB_USERNAME --password $DOCKER_HUB_PASSWORD
|
- run: docker login --username $DOCKER_HUB_USERNAME --password $DOCKER_HUB_PASSWORD
|
||||||
- run: docker push matrixdotorg/synapse:${CIRCLE_TAG}
|
- run: docker push matrixdotorg/synapse:${CIRCLE_TAG}
|
||||||
- run: docker push matrixdotorg/synapse:${CIRCLE_TAG}-py3
|
- run: docker push matrixdotorg/synapse:${CIRCLE_TAG}-py3
|
||||||
@ -13,8 +13,8 @@ jobs:
|
|||||||
machine: true
|
machine: true
|
||||||
steps:
|
steps:
|
||||||
- checkout
|
- checkout
|
||||||
- run: docker build -f docker/Dockerfile --label gitsha1=${CIRCLE_SHA1} -t matrixdotorg/synapse:latest .
|
- run: docker build -f docker/Dockerfile --label gitsha1=${CIRCLE_SHA1} -t matrixdotorg/synapse:latest-py2 .
|
||||||
- run: docker build -f docker/Dockerfile --label gitsha1=${CIRCLE_SHA1} -t matrixdotorg/synapse:latest-py3 --build-arg PYTHON_VERSION=3.6 .
|
- run: docker build -f docker/Dockerfile --label gitsha1=${CIRCLE_SHA1} -t matrixdotorg/synapse:latest -t matrixdotorg/synapse:latest-py3 --build-arg PYTHON_VERSION=3.6 .
|
||||||
- run: docker login --username $DOCKER_HUB_USERNAME --password $DOCKER_HUB_PASSWORD
|
- run: docker login --username $DOCKER_HUB_USERNAME --password $DOCKER_HUB_PASSWORD
|
||||||
- run: docker push matrixdotorg/synapse:latest
|
- run: docker push matrixdotorg/synapse:latest
|
||||||
- run: docker push matrixdotorg/synapse:latest-py3
|
- run: docker push matrixdotorg/synapse:latest-py3
|
||||||
|
487
INSTALL.md
Normal file
487
INSTALL.md
Normal file
@ -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.
|
375
README.rst
375
README.rst
@ -81,191 +81,8 @@ Thanks for using Matrix!
|
|||||||
Synapse Installation
|
Synapse Installation
|
||||||
====================
|
====================
|
||||||
|
|
||||||
Synapse is the reference Python/Twisted Matrix homeserver implementation.
|
For details on how to install synapse, see `<INSTALL.md>`_.
|
||||||
|
|
||||||
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
|
|
||||||
|
|
||||||
Installing from source
|
|
||||||
----------------------
|
|
||||||
|
|
||||||
(Prebuilt packages are available for some platforms - see `Platform-Specific
|
|
||||||
Instructions`_.)
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
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
|
|
||||||
|
|
||||||
Installing prerequisites on ArchLinux::
|
|
||||||
|
|
||||||
sudo pacman -S base-devel python python-pip \
|
|
||||||
python-setuptools python-virtualenv sqlite3
|
|
||||||
|
|
||||||
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"
|
|
||||||
|
|
||||||
Installing prerequisites on Mac OS X::
|
|
||||||
|
|
||||||
xcode-select --install
|
|
||||||
sudo easy_install pip
|
|
||||||
sudo pip install virtualenv
|
|
||||||
brew install pkg-config libffi
|
|
||||||
|
|
||||||
Installing prerequisites on Raspbian::
|
|
||||||
|
|
||||||
sudo apt-get install build-essential python3-dev libffi-dev \
|
|
||||||
python-pip python-setuptools sqlite3 \
|
|
||||||
libssl-dev python-virtualenv libjpeg-dev
|
|
||||||
|
|
||||||
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
|
|
||||||
|
|
||||||
Installing prerequisites on OpenBSD::
|
|
||||||
|
|
||||||
doas pkg_add python libffi py-pip py-setuptools sqlite3 py-virtualenv \
|
|
||||||
libxslt jpeg
|
|
||||||
|
|
||||||
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 installs Synapse, along with the 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]
|
|
||||||
|
|
||||||
In case of problems, please see the _`Troubleshooting` section below.
|
|
||||||
|
|
||||||
There is an offical synapse image available at
|
|
||||||
https://hub.docker.com/r/matrixdotorg/synapse/tags/ 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
|
|
||||||
|
|
||||||
Configuring 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``. 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`_. 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`__ for more information on key management.)
|
|
||||||
|
|
||||||
.. __: `key_management`_
|
|
||||||
|
|
||||||
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
|
|
||||||
----------
|
|
||||||
|
|
||||||
For details on having Synapse manage your federation TLS certificates
|
|
||||||
automatically, please see `<docs/ACME.md>`_.
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
.. __: `client-user-reg`_
|
|
||||||
|
|
||||||
To get started, it is easiest to use the command line to register new users::
|
|
||||||
|
|
||||||
$ 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>`_ for details.
|
|
||||||
|
|
||||||
Running Synapse
|
|
||||||
===============
|
|
||||||
|
|
||||||
To actually run your new homeserver, pick a working directory for Synapse to
|
To actually run your new homeserver, pick a working directory for Synapse to
|
||||||
run (e.g. ``~/synapse``), and::
|
run (e.g. ``~/synapse``), and::
|
||||||
@ -334,177 +151,11 @@ server on the same domain.
|
|||||||
See https://github.com/vector-im/riot-web/issues/1977 and
|
See https://github.com/vector-im/riot-web/issues/1977 and
|
||||||
https://developer.github.com/changes/2014-04-25-user-content-security for more details.
|
https://developer.github.com/changes/2014-04-25-user-content-security for more details.
|
||||||
|
|
||||||
|
|
||||||
Platform-Specific Instructions
|
|
||||||
==============================
|
|
||||||
|
|
||||||
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``
|
|
||||||
|
|
||||||
|
|
||||||
OpenBSD
|
|
||||||
-------
|
|
||||||
|
|
||||||
There is currently no port for OpenBSD. Additionally, OpenBSD's security
|
|
||||||
settings require a slightly more difficult installation process.
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
NixOS
|
|
||||||
-----
|
|
||||||
|
|
||||||
Robin Lambertz has packaged Synapse for NixOS at:
|
|
||||||
https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/services/misc/matrix-synapse.nix
|
|
||||||
|
|
||||||
Windows Install
|
|
||||||
---------------
|
|
||||||
|
|
||||||
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
|
Troubleshooting
|
||||||
===============
|
===============
|
||||||
|
|
||||||
Troubleshooting Installation
|
|
||||||
----------------------------
|
|
||||||
|
|
||||||
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
|
|
||||||
|
|
||||||
Running out of File Handles
|
Running out of File Handles
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
---------------------------
|
||||||
|
|
||||||
If synapse runs out of filehandles, it typically fails badly - live-locking
|
If synapse runs out of filehandles, it typically fails badly - live-locking
|
||||||
at 100% CPU, and/or failing to accept new TCP connections (blocking the
|
at 100% CPU, and/or failing to accept new TCP connections (blocking the
|
||||||
@ -546,7 +197,7 @@ Federation is the process by which users on different servers can participate
|
|||||||
in the same room. For this to work, those other servers must be able to contact
|
in the same room. For this to work, those other servers must be able to contact
|
||||||
yours to send messages.
|
yours to send messages.
|
||||||
|
|
||||||
As explained in `Configuring synapse`_, the ``server_name`` in your
|
The ``server_name`` in your
|
||||||
``homeserver.yaml`` file determines the way that other servers will reach
|
``homeserver.yaml`` file determines the way that other servers will reach
|
||||||
yours. By default, they will treat it as a hostname and try to connect to
|
yours. By default, they will treat it as a hostname and try to connect to
|
||||||
port 8448. This is easy to set up and will work with the default configuration,
|
port 8448. This is easy to set up and will work with the default configuration,
|
||||||
@ -733,24 +384,6 @@ an email address with your account, or send an invite to another user via their
|
|||||||
email address.
|
email address.
|
||||||
|
|
||||||
|
|
||||||
URL Previews
|
|
||||||
============
|
|
||||||
|
|
||||||
Synapse 0.15.0 introduces a new API for previewing URLs at
|
|
||||||
``/_matrix/media/r0/preview_url``. This 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.
|
|
||||||
|
|
||||||
|
|
||||||
Password reset
|
Password reset
|
||||||
==============
|
==============
|
||||||
|
|
||||||
@ -852,5 +485,3 @@ by installing the ``libjemalloc1`` package and adding this line to
|
|||||||
``/etc/default/matrix-synapse``::
|
``/etc/default/matrix-synapse``::
|
||||||
|
|
||||||
LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libjemalloc.so.1
|
LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libjemalloc.so.1
|
||||||
|
|
||||||
.. _`key_management`: https://matrix.org/docs/spec/server_server/unstable.html#retrieving-server-keys
|
|
||||||
|
1
changelog.d/4557.misc
Normal file
1
changelog.d/4557.misc
Normal file
@ -0,0 +1 @@
|
|||||||
|
Fix comment typo in TLS section of config
|
1
changelog.d/4558.feature
Normal file
1
changelog.d/4558.feature
Normal file
@ -0,0 +1 @@
|
|||||||
|
The matrixdotorg/synapse Docker images now use Python 3 by default.
|
1
changelog.d/4562.misc
Normal file
1
changelog.d/4562.misc
Normal file
@ -0,0 +1 @@
|
|||||||
|
Docker: only copy what we need to the build image
|
1
changelog.d/4564.bugfix
Normal file
1
changelog.d/4564.bugfix
Normal file
@ -0,0 +1 @@
|
|||||||
|
Fix default ACME config for py2
|
1
changelog.d/4566.feature
Normal file
1
changelog.d/4566.feature
Normal file
@ -0,0 +1 @@
|
|||||||
|
enable ACME support in the docker image
|
@ -1,3 +1,16 @@
|
|||||||
|
# Dockerfile to build the matrixdotorg/synapse docker images.
|
||||||
|
#
|
||||||
|
# To build the image, run `docker build` command from the root of the
|
||||||
|
# synapse repository:
|
||||||
|
#
|
||||||
|
# docker build -f docker/Dockerfile .
|
||||||
|
#
|
||||||
|
# There is an optional PYTHON_VERSION build argument which sets the
|
||||||
|
# version of python to build against: for example:
|
||||||
|
#
|
||||||
|
# docker build -f docker/Dockerfile --build-arg PYTHON_VERSION=3.6 .
|
||||||
|
#
|
||||||
|
|
||||||
ARG PYTHON_VERSION=2
|
ARG PYTHON_VERSION=2
|
||||||
|
|
||||||
###
|
###
|
||||||
@ -31,7 +44,10 @@ RUN pip install --prefix="/install" --no-warn-script-location \
|
|||||||
|
|
||||||
# now install synapse and all of the python deps to /install.
|
# now install synapse and all of the python deps to /install.
|
||||||
|
|
||||||
COPY . /synapse
|
COPY synapse /synapse/synapse/
|
||||||
|
COPY scripts /synapse/scripts/
|
||||||
|
COPY MANIFEST.in README.rst setup.py synctl /synapse/
|
||||||
|
|
||||||
RUN pip install --prefix="/install" --no-warn-script-location \
|
RUN pip install --prefix="/install" --no-warn-script-location \
|
||||||
/synapse[all]
|
/synapse[all]
|
||||||
|
|
||||||
@ -56,6 +72,6 @@ COPY ./docker/conf /conf
|
|||||||
|
|
||||||
VOLUME ["/data"]
|
VOLUME ["/data"]
|
||||||
|
|
||||||
EXPOSE 8008/tcp 8448/tcp
|
EXPOSE 8008/tcp 8009/tcp 8448/tcp
|
||||||
|
|
||||||
ENTRYPOINT ["/start.py"]
|
ENTRYPOINT ["/start.py"]
|
||||||
|
@ -1,22 +1,21 @@
|
|||||||
# Synapse Docker
|
# Synapse Docker
|
||||||
|
|
||||||
This Docker image will run Synapse as a single process. It does not provide a database
|
This Docker image will run Synapse as a single process. By default it uses a
|
||||||
server or a TURN server, you should run these separately.
|
sqlite database; for production use you should connect it to a separate
|
||||||
|
postgres database.
|
||||||
|
|
||||||
|
The image also does *not* provide a TURN server.
|
||||||
|
|
||||||
## Run
|
## Run
|
||||||
|
|
||||||
We do not currently offer a `latest` image, as this has somewhat undefined semantics.
|
|
||||||
We instead release only tagged versions so upgrading between releases is entirely
|
|
||||||
within your control.
|
|
||||||
|
|
||||||
### Using docker-compose (easier)
|
### Using docker-compose (easier)
|
||||||
|
|
||||||
This image is designed to run either with an automatically generated configuration
|
This image is designed to run either with an automatically generated
|
||||||
file or with a custom configuration that requires manual editing.
|
configuration file or with a custom configuration that requires manual editing.
|
||||||
|
|
||||||
An easy way to make use of this image is via docker-compose. See the
|
An easy way to make use of this image is via docker-compose. See the
|
||||||
[contrib/docker](../contrib/docker)
|
[contrib/docker](../contrib/docker) section of the synapse project for
|
||||||
section of the synapse project for examples.
|
examples.
|
||||||
|
|
||||||
### Without Compose (harder)
|
### Without Compose (harder)
|
||||||
|
|
||||||
@ -32,7 +31,7 @@ docker run \
|
|||||||
-v ${DATA_PATH}:/data \
|
-v ${DATA_PATH}:/data \
|
||||||
-e SYNAPSE_SERVER_NAME=my.matrix.host \
|
-e SYNAPSE_SERVER_NAME=my.matrix.host \
|
||||||
-e SYNAPSE_REPORT_STATS=yes \
|
-e SYNAPSE_REPORT_STATS=yes \
|
||||||
docker.io/matrixdotorg/synapse:latest
|
matrixdotorg/synapse:latest
|
||||||
```
|
```
|
||||||
|
|
||||||
## Volumes
|
## Volumes
|
||||||
@ -53,6 +52,28 @@ In order to setup an application service, simply create an ``appservices``
|
|||||||
directory in the data volume and write the application service Yaml
|
directory in the data volume and write the application service Yaml
|
||||||
configuration file there. Multiple application services are supported.
|
configuration file there. Multiple application services are supported.
|
||||||
|
|
||||||
|
## TLS certificates
|
||||||
|
|
||||||
|
Synapse requires a valid TLS certificate. You can do one of the following:
|
||||||
|
|
||||||
|
* Provide your own certificate and key (as
|
||||||
|
`${DATA_PATH}/${SYNAPSE_SERVER_NAME}.crt` and
|
||||||
|
`${DATA_PATH}/${SYNAPSE_SERVER_NAME}.key`, or elsewhere by providing an
|
||||||
|
entire config as `${SYNAPSE_CONFIG_PATH}`).
|
||||||
|
|
||||||
|
* Use a reverse proxy to terminate incoming TLS, and forward the plain http
|
||||||
|
traffic to port 8008 in the container. In this case you should set `-e
|
||||||
|
SYNAPSE_NO_TLS=1`.
|
||||||
|
|
||||||
|
* Use the ACME (Let's Encrypt) support built into Synapse. This requires
|
||||||
|
`${SYNAPSE_SERVER_NAME}` port 80 to be forwarded to port 8009 in the
|
||||||
|
container, for example with `-p 80:8009`. To enable it in the docker
|
||||||
|
container, set `-e SYNAPSE_ACME=1`.
|
||||||
|
|
||||||
|
If you don't do any of these, Synapse will fail to start with an error similar to:
|
||||||
|
|
||||||
|
synapse.config._base.ConfigError: Error accessing file '/data/<server_name>.tls.crt' (config for tls_certificate): No such file or directory
|
||||||
|
|
||||||
## Environment
|
## Environment
|
||||||
|
|
||||||
Unless you specify a custom path for the configuration file, a very generic
|
Unless you specify a custom path for the configuration file, a very generic
|
||||||
@ -71,7 +92,7 @@ then customize it manually. No other environment variable is required.
|
|||||||
Otherwise, a dynamic configuration file will be used. The following environment
|
Otherwise, a dynamic configuration file will be used. The following environment
|
||||||
variables are available for configuration:
|
variables are available for configuration:
|
||||||
|
|
||||||
* ``SYNAPSE_SERVER_NAME`` (mandatory), the current server public hostname.
|
* ``SYNAPSE_SERVER_NAME`` (mandatory), the server public hostname.
|
||||||
* ``SYNAPSE_REPORT_STATS``, (mandatory, ``yes`` or ``no``), enable anonymous
|
* ``SYNAPSE_REPORT_STATS``, (mandatory, ``yes`` or ``no``), enable anonymous
|
||||||
statistics reporting back to the Matrix project which helps us to get funding.
|
statistics reporting back to the Matrix project which helps us to get funding.
|
||||||
* ``SYNAPSE_NO_TLS``, set this variable to disable TLS in Synapse (use this if
|
* ``SYNAPSE_NO_TLS``, set this variable to disable TLS in Synapse (use this if
|
||||||
@ -80,7 +101,6 @@ variables are available for configuration:
|
|||||||
the Synapse instance.
|
the Synapse instance.
|
||||||
* ``SYNAPSE_ALLOW_GUEST``, set this variable to allow guest joining this server.
|
* ``SYNAPSE_ALLOW_GUEST``, set this variable to allow guest joining this server.
|
||||||
* ``SYNAPSE_EVENT_CACHE_SIZE``, the event cache size [default `10K`].
|
* ``SYNAPSE_EVENT_CACHE_SIZE``, the event cache size [default `10K`].
|
||||||
* ``SYNAPSE_CACHE_FACTOR``, the cache factor [default `0.5`].
|
|
||||||
* ``SYNAPSE_RECAPTCHA_PUBLIC_KEY``, set this variable to the recaptcha public
|
* ``SYNAPSE_RECAPTCHA_PUBLIC_KEY``, set this variable to the recaptcha public
|
||||||
key in order to enable recaptcha upon registration.
|
key in order to enable recaptcha upon registration.
|
||||||
* ``SYNAPSE_RECAPTCHA_PRIVATE_KEY``, set this variable to the recaptcha private
|
* ``SYNAPSE_RECAPTCHA_PRIVATE_KEY``, set this variable to the recaptcha private
|
||||||
@ -88,7 +108,9 @@ variables are available for configuration:
|
|||||||
* ``SYNAPSE_TURN_URIS``, set this variable to the coma-separated list of TURN
|
* ``SYNAPSE_TURN_URIS``, set this variable to the coma-separated list of TURN
|
||||||
uris to enable TURN for this homeserver.
|
uris to enable TURN for this homeserver.
|
||||||
* ``SYNAPSE_TURN_SECRET``, set this to the TURN shared secret if required.
|
* ``SYNAPSE_TURN_SECRET``, set this to the TURN shared secret if required.
|
||||||
* ``SYNAPSE_MAX_UPLOAD_SIZE``, set this variable to change the max upload size [default `10M`].
|
* ``SYNAPSE_MAX_UPLOAD_SIZE``, set this variable to change the max upload size
|
||||||
|
[default `10M`].
|
||||||
|
* ``SYNAPSE_ACME``: set this to enable the ACME certificate renewal support.
|
||||||
|
|
||||||
Shared secrets, that will be initialized to random values if not set:
|
Shared secrets, that will be initialized to random values if not set:
|
||||||
|
|
||||||
@ -99,27 +121,25 @@ Shared secrets, that will be initialized to random values if not set:
|
|||||||
|
|
||||||
Database specific values (will use SQLite if not set):
|
Database specific values (will use SQLite if not set):
|
||||||
|
|
||||||
* `POSTGRES_DB` - The database name for the synapse postgres database. [default: `synapse`]
|
* `POSTGRES_DB` - The database name for the synapse postgres
|
||||||
* `POSTGRES_HOST` - The host of the postgres database if you wish to use postgresql instead of sqlite3. [default: `db` which is useful when using a container on the same docker network in a compose file where the postgres service is called `db`]
|
database. [default: `synapse`]
|
||||||
* `POSTGRES_PASSWORD` - The password for the synapse postgres database. **If this is set then postgres will be used instead of sqlite3.** [default: none] **NOTE**: You are highly encouraged to use postgresql! Please use the compose file to make it easier to deploy.
|
* `POSTGRES_HOST` - The host of the postgres database if you wish to use
|
||||||
* `POSTGRES_USER` - The user for the synapse postgres database. [default: `matrix`]
|
postgresql instead of sqlite3. [default: `db` which is useful when using a
|
||||||
|
container on the same docker network in a compose file where the postgres
|
||||||
|
service is called `db`]
|
||||||
|
* `POSTGRES_PASSWORD` - The password for the synapse postgres database. **If
|
||||||
|
this is set then postgres will be used instead of sqlite3.** [default: none]
|
||||||
|
**NOTE**: You are highly encouraged to use postgresql! Please use the compose
|
||||||
|
file to make it easier to deploy.
|
||||||
|
* `POSTGRES_USER` - The user for the synapse postgres database. [default:
|
||||||
|
`matrix`]
|
||||||
|
|
||||||
Mail server specific values (will not send emails if not set):
|
Mail server specific values (will not send emails if not set):
|
||||||
|
|
||||||
* ``SYNAPSE_SMTP_HOST``, hostname to the mail server.
|
* ``SYNAPSE_SMTP_HOST``, hostname to the mail server.
|
||||||
* ``SYNAPSE_SMTP_PORT``, TCP port for accessing the mail server [default ``25``].
|
* ``SYNAPSE_SMTP_PORT``, TCP port for accessing the mail server [default
|
||||||
* ``SYNAPSE_SMTP_USER``, username for authenticating against the mail server if any.
|
``25``].
|
||||||
* ``SYNAPSE_SMTP_PASSWORD``, password for authenticating against the mail server if any.
|
* ``SYNAPSE_SMTP_USER``, username for authenticating against the mail server if
|
||||||
|
any.
|
||||||
## Build
|
* ``SYNAPSE_SMTP_PASSWORD``, password for authenticating against the mail
|
||||||
|
server if any.
|
||||||
Build the docker image with the `docker build` command from the root of the synapse repository.
|
|
||||||
|
|
||||||
```
|
|
||||||
docker build -t docker.io/matrixdotorg/synapse . -f docker/Dockerfile
|
|
||||||
```
|
|
||||||
|
|
||||||
The `-t` option sets the image tag. Official images are tagged `matrixdotorg/synapse:<version>` where `<version>` is the same as the release tag in the synapse git repository.
|
|
||||||
|
|
||||||
You may have a local Python wheel cache available, in which case copy the relevant
|
|
||||||
packages in the ``cache/`` directory at the root of the project.
|
|
||||||
|
17
docker/conf/dummy.tls.crt
Normal file
17
docker/conf/dummy.tls.crt
Normal file
@ -0,0 +1,17 @@
|
|||||||
|
-----BEGIN CERTIFICATE-----
|
||||||
|
MIICnTCCAYUCAgPoMA0GCSqGSIb3DQEBCwUAMBQxEjAQBgNVBAMMCWxvY2FsaG9z
|
||||||
|
dDAeFw0xOTAxMTUwMDQxNTBaFw0yOTAxMTIwMDQxNTBaMBQxEjAQBgNVBAMMCWxv
|
||||||
|
Y2FsaG9zdDCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAMKqm81/8j5d
|
||||||
|
R1s7VZ8ueg12gJrPVCCAOkp0UnuC/ZlXhN0HTvnhQ+B0IlSgB4CcQZyf4jnA6o4M
|
||||||
|
rwSc7VX0MPE9x/idoA0g/0WoC6tsxugOrvbzCw8Tv+fnXglm6uVc7aFPfx69wU3q
|
||||||
|
lUHGD/8jtEoHxmCG177Pt2lHAfiVLBAyMQGtETzxt/yAfkloaybe316qoljgK5WK
|
||||||
|
cokdAt9G84EEqxNeEnx5FG3Vc100bAqJS4GvQlFgtF9KFEqZKEyB1yKBpPMDfPIS
|
||||||
|
V9hIV0gswSmYI8dpyBlGf5lPElY68ZGABmOQgr0RI5qHK/h28OpFPE0q3v4AMHgZ
|
||||||
|
I36wii4NrAUCAwEAATANBgkqhkiG9w0BAQsFAAOCAQEAfD8kcpZ+dn08xh1qtKtp
|
||||||
|
X+/YNZaOBIeVdlCzfoZKNblSFAFD/jCfObNJYvZMUQ8NX2UtEJp1lTA6m7ltSsdY
|
||||||
|
gpC2k1VD8iN+ooXklJmL0kxc7UUqho8I0l9vn35h+lhLF0ihT6XfZVi/lDHWl+4G
|
||||||
|
rG+v9oxvCSCWrNWLearSlFPtQQ8xPtOE0nLwfXtOI/H/2kOuC38ihaIWM4jjbWXK
|
||||||
|
E/ksgUfuDv0mFiwf1YdBF5/M3/qOowqzU8HgMJ3WoT/9Po5Ya1pWc+3BcxxytUDf
|
||||||
|
XdMu0tWHKX84tZxLcR1nZHzluyvFFM8xNtLi9xV0Z7WbfT76V0C/ulEOybGInYsv
|
||||||
|
nQ==
|
||||||
|
-----END CERTIFICATE-----
|
@ -2,10 +2,24 @@
|
|||||||
|
|
||||||
## TLS ##
|
## TLS ##
|
||||||
|
|
||||||
|
{% if SYNAPSE_NO_TLS %}
|
||||||
|
no_tls: True
|
||||||
|
|
||||||
|
# workaround for https://github.com/matrix-org/synapse/issues/4554
|
||||||
|
tls_certificate_path: "/conf/dummy.tls.crt"
|
||||||
|
|
||||||
|
{% else %}
|
||||||
|
|
||||||
tls_certificate_path: "/data/{{ SYNAPSE_SERVER_NAME }}.tls.crt"
|
tls_certificate_path: "/data/{{ SYNAPSE_SERVER_NAME }}.tls.crt"
|
||||||
tls_private_key_path: "/data/{{ SYNAPSE_SERVER_NAME }}.tls.key"
|
tls_private_key_path: "/data/{{ SYNAPSE_SERVER_NAME }}.tls.key"
|
||||||
no_tls: {{ "True" if SYNAPSE_NO_TLS else "False" }}
|
|
||||||
tls_fingerprints: []
|
{% if SYNAPSE_ACME %}
|
||||||
|
acme:
|
||||||
|
enabled: true
|
||||||
|
port: 8009
|
||||||
|
{% endif %}
|
||||||
|
|
||||||
|
{% endif %}
|
||||||
|
|
||||||
## Server ##
|
## Server ##
|
||||||
|
|
||||||
|
@ -47,9 +47,8 @@ if mode == "generate":
|
|||||||
|
|
||||||
# In normal mode, generate missing keys if any, then run synapse
|
# In normal mode, generate missing keys if any, then run synapse
|
||||||
else:
|
else:
|
||||||
# Parse the configuration file
|
|
||||||
if "SYNAPSE_CONFIG_PATH" in environ:
|
if "SYNAPSE_CONFIG_PATH" in environ:
|
||||||
args += ["--config-path", environ["SYNAPSE_CONFIG_PATH"]]
|
config_path = environ["SYNAPSE_CONFIG_PATH"]
|
||||||
else:
|
else:
|
||||||
check_arguments(environ, ("SYNAPSE_SERVER_NAME", "SYNAPSE_REPORT_STATS"))
|
check_arguments(environ, ("SYNAPSE_SERVER_NAME", "SYNAPSE_REPORT_STATS"))
|
||||||
generate_secrets(environ, {
|
generate_secrets(environ, {
|
||||||
@ -58,10 +57,21 @@ else:
|
|||||||
})
|
})
|
||||||
environ["SYNAPSE_APPSERVICES"] = glob.glob("/data/appservices/*.yaml")
|
environ["SYNAPSE_APPSERVICES"] = glob.glob("/data/appservices/*.yaml")
|
||||||
if not os.path.exists("/compiled"): os.mkdir("/compiled")
|
if not os.path.exists("/compiled"): os.mkdir("/compiled")
|
||||||
convert("/conf/homeserver.yaml", "/compiled/homeserver.yaml", environ)
|
|
||||||
|
config_path = "/compiled/homeserver.yaml"
|
||||||
|
|
||||||
|
convert("/conf/homeserver.yaml", config_path, environ)
|
||||||
convert("/conf/log.config", "/compiled/log.config", environ)
|
convert("/conf/log.config", "/compiled/log.config", environ)
|
||||||
subprocess.check_output(["chown", "-R", ownership, "/data"])
|
subprocess.check_output(["chown", "-R", ownership, "/data"])
|
||||||
args += ["--config-path", "/compiled/homeserver.yaml"]
|
|
||||||
|
|
||||||
|
args += [
|
||||||
|
"--config-path", config_path,
|
||||||
|
|
||||||
|
# tell synapse to put any generated keys in /data rather than /compiled
|
||||||
|
"--keys-directory", "/data",
|
||||||
|
]
|
||||||
|
|
||||||
# Generate missing keys and start synapse
|
# Generate missing keys and start synapse
|
||||||
subprocess.check_output(args + ["--generate-keys"])
|
subprocess.check_output(args + ["--generate-keys"])
|
||||||
os.execv("/sbin/su-exec", ["su-exec", ownership] + args)
|
os.execv("/sbin/su-exec", ["su-exec", ownership] + args)
|
||||||
|
@ -37,7 +37,7 @@ class TlsConfig(Config):
|
|||||||
|
|
||||||
self.acme_enabled = acme_config.get("enabled", False)
|
self.acme_enabled = acme_config.get("enabled", False)
|
||||||
self.acme_url = acme_config.get(
|
self.acme_url = acme_config.get(
|
||||||
"url", "https://acme-v01.api.letsencrypt.org/directory"
|
"url", u"https://acme-v01.api.letsencrypt.org/directory"
|
||||||
)
|
)
|
||||||
self.acme_port = acme_config.get("port", 80)
|
self.acme_port = acme_config.get("port", 80)
|
||||||
self.acme_bind_addresses = acme_config.get("bind_addresses", ['::', '0.0.0.0'])
|
self.acme_bind_addresses = acme_config.get("bind_addresses", ['::', '0.0.0.0'])
|
||||||
@ -199,10 +199,10 @@ class TlsConfig(Config):
|
|||||||
|
|
||||||
# If your server runs behind a reverse-proxy which terminates TLS connections
|
# If your server runs behind a reverse-proxy which terminates TLS connections
|
||||||
# (for both client and federation connections), it may be useful to disable
|
# (for both client and federation connections), it may be useful to disable
|
||||||
# All TLS support for incoming connections. Setting no_tls to False will
|
# All TLS support for incoming connections. Setting no_tls to True will
|
||||||
# do so (and avoid the need to give synapse a TLS private key).
|
# do so (and avoid the need to give synapse a TLS private key).
|
||||||
#
|
#
|
||||||
# no_tls: False
|
# no_tls: True
|
||||||
|
|
||||||
# List of allowed TLS fingerprints for this server to publish along
|
# List of allowed TLS fingerprints for this server to publish along
|
||||||
# with the signing keys for this server. Other matrix servers that
|
# with the signing keys for this server. Other matrix servers that
|
||||||
|
Loading…
Reference in New Issue
Block a user