1# Installation Instructions 2 3## Choosing your server name 4 5It is important to choose the name for your server before you install Synapse, 6because it cannot be changed later. 7 8The server name determines the "domain" part of user-ids for users on your 9server: these will all be of the format `@user:my.domain.name`. It also 10determines how other matrix servers will reach yours for federation. 11 12For a test configuration, set this to the hostname of your server. For a more 13production-ready setup, you will probably want to specify your domain 14(`example.com`) rather than a matrix-specific hostname here (in the same way 15that your email address is probably `user@example.com` rather than 16`user@email.example.com`) - but doing so may require more advanced setup: see 17[Setting up Federation](../federate.md). 18 19## Installing Synapse 20 21### Prebuilt packages 22 23Prebuilt packages are available for a number of platforms. These are recommended 24for most users. 25 26#### Docker images and Ansible playbooks 27 28There is an official synapse image available at 29<https://hub.docker.com/r/matrixdotorg/synapse> which can be used with 30the docker-compose file available at 31[contrib/docker](https://github.com/matrix-org/synapse/tree/develop/contrib/docker). 32Further information on this including configuration options is available in the README 33on hub.docker.com. 34 35Alternatively, Andreas Peters (previously Silvio Fricke) has contributed a 36Dockerfile to automate a synapse server in a single Docker image, at 37<https://hub.docker.com/r/avhost/docker-matrix/tags/> 38 39Slavi Pantaleev has created an Ansible playbook, 40which installs the offical Docker image of Matrix Synapse 41along with many other Matrix-related services (Postgres database, Element, coturn, 42ma1sd, SSL support, etc.). 43For more details, see 44<https://github.com/spantaleev/matrix-docker-ansible-deploy> 45 46#### Debian/Ubuntu 47 48##### Matrix.org packages 49 50Matrix.org provides Debian/Ubuntu packages of Synapse, for the amd64 51architecture via <https://packages.matrix.org/debian/>. 52 53To install the latest release: 54 55```sh 56sudo apt install -y lsb-release wget apt-transport-https 57sudo wget -O /usr/share/keyrings/matrix-org-archive-keyring.gpg https://packages.matrix.org/debian/matrix-org-archive-keyring.gpg 58echo "deb [signed-by=/usr/share/keyrings/matrix-org-archive-keyring.gpg] https://packages.matrix.org/debian/ $(lsb_release -cs) main" | 59 sudo tee /etc/apt/sources.list.d/matrix-org.list 60sudo apt update 61sudo apt install matrix-synapse-py3 62``` 63 64Packages are also published for release candidates. To enable the prerelease 65channel, add `prerelease` to the `sources.list` line. For example: 66 67```sh 68sudo wget -O /usr/share/keyrings/matrix-org-archive-keyring.gpg https://packages.matrix.org/debian/matrix-org-archive-keyring.gpg 69echo "deb [signed-by=/usr/share/keyrings/matrix-org-archive-keyring.gpg] https://packages.matrix.org/debian/ $(lsb_release -cs) main prerelease" | 70 sudo tee /etc/apt/sources.list.d/matrix-org.list 71sudo apt update 72sudo apt install matrix-synapse-py3 73``` 74 75The fingerprint of the repository signing key (as shown by `gpg 76/usr/share/keyrings/matrix-org-archive-keyring.gpg`) is 77`AAF9AE843A7584B5A3E4CD2BCF45A512DE2DA058`. 78 79When installing with Debian packages, you might prefer to place files in 80`/etc/matrix-synapse/conf.d/` to override your configuration without editing 81the main configuration file at `/etc/matrix-synapse/homeserver.yaml`. 82By doing that, you won't be asked if you want to replace your configuration 83file when you upgrade the Debian package to a later version. 84 85##### Downstream Debian packages 86 87We do not recommend using the packages from the default Debian `buster` 88repository at this time, as they are old and suffer from known security 89vulnerabilities. You can install the latest version of Synapse from 90[our repository](#matrixorg-packages) or from `buster-backports`. Please 91see the [Debian documentation](https://backports.debian.org/Instructions/) 92for information on how to use backports. 93 94If you are using Debian `sid` or testing, Synapse is available in the default 95repositories and it should be possible to install it simply with: 96 97```sh 98sudo apt install matrix-synapse 99``` 100 101##### Downstream Ubuntu packages 102 103We do not recommend using the packages in the default Ubuntu repository 104at this time, as they are old and suffer from known security vulnerabilities. 105The latest version of Synapse can be installed from [our repository](#matrixorg-packages). 106 107#### Fedora 108 109Synapse is in the Fedora repositories as `matrix-synapse`: 110 111```sh 112sudo dnf install matrix-synapse 113``` 114 115Oleg Girko provides Fedora RPMs at 116<https://obs.infoserver.lv/project/monitor/matrix-synapse> 117 118#### OpenSUSE 119 120Synapse is in the OpenSUSE repositories as `matrix-synapse`: 121 122```sh 123sudo zypper install matrix-synapse 124``` 125 126#### SUSE Linux Enterprise Server 127 128Unofficial package are built for SLES 15 in the openSUSE:Backports:SLE-15 repository at 129<https://download.opensuse.org/repositories/openSUSE:/Backports:/SLE-15/standard/> 130 131#### ArchLinux 132 133The quickest way to get up and running with ArchLinux is probably with the community package 134<https://www.archlinux.org/packages/community/any/matrix-synapse/>, which should pull in most of 135the necessary dependencies. 136 137pip may be outdated (6.0.7-1 and needs to be upgraded to 6.0.8-1 ): 138 139```sh 140sudo pip install --upgrade pip 141``` 142 143If you encounter an error with lib bcrypt causing an Wrong ELF Class: 144ELFCLASS32 (x64 Systems), you may need to reinstall py-bcrypt to correctly 145compile it under the right architecture. (This should not be needed if 146installing under virtualenv): 147 148```sh 149sudo pip uninstall py-bcrypt 150sudo pip install py-bcrypt 151``` 152 153#### Void Linux 154 155Synapse can be found in the void repositories as 'synapse': 156 157```sh 158xbps-install -Su 159xbps-install -S synapse 160``` 161 162#### FreeBSD 163 164Synapse can be installed via FreeBSD Ports or Packages contributed by Brendan Molloy from: 165 166- Ports: `cd /usr/ports/net-im/py-matrix-synapse && make install clean` 167- Packages: `pkg install py38-matrix-synapse` 168 169#### OpenBSD 170 171As of OpenBSD 6.7 Synapse is available as a pre-compiled binary. The filesystem 172underlying the homeserver directory (defaults to `/var/synapse`) has to be 173mounted with `wxallowed` (cf. `mount(8)`), so creating a separate filesystem 174and mounting it to `/var/synapse` should be taken into consideration. 175 176Installing Synapse: 177 178```sh 179doas pkg_add synapse 180``` 181 182#### NixOS 183 184Robin Lambertz has packaged Synapse for NixOS at: 185<https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/services/misc/matrix-synapse.nix> 186 187 188### Installing as a Python module from PyPI 189 190It's also possible to install Synapse as a Python module from PyPI. 191 192When following this route please make sure that the [Platform-specific prerequisites](#platform-specific-prerequisites) are already installed. 193 194System requirements: 195 196- POSIX-compliant system (tested on Linux & OS X) 197- Python 3.6 or later, up to Python 3.9. 198- At least 1GB of free RAM if you want to join large public rooms like #matrix:matrix.org 199 200To install the Synapse homeserver run: 201 202```sh 203mkdir -p ~/synapse 204virtualenv -p python3 ~/synapse/env 205source ~/synapse/env/bin/activate 206pip install --upgrade pip 207pip install --upgrade setuptools 208pip install matrix-synapse 209``` 210 211This will download Synapse from [PyPI](https://pypi.org/project/matrix-synapse) 212and install it, along with the python libraries it uses, into a virtual environment 213under `~/synapse/env`. Feel free to pick a different directory if you 214prefer. 215 216This Synapse installation can then be later upgraded by using pip again with the 217update flag: 218 219```sh 220source ~/synapse/env/bin/activate 221pip install -U matrix-synapse 222``` 223 224Before you can start Synapse, you will need to generate a configuration 225file. To do this, run (in your virtualenv, as before): 226 227```sh 228cd ~/synapse 229python -m synapse.app.homeserver \ 230 --server-name my.domain.name \ 231 --config-path homeserver.yaml \ 232 --generate-config \ 233 --report-stats=[yes|no] 234``` 235 236... substituting an appropriate value for `--server-name`. 237 238This command will generate you a config file that you can then customise, but it will 239also generate a set of keys for you. These keys will allow your homeserver to 240identify itself to other homeserver, so don't lose or delete them. It would be 241wise to back them up somewhere safe. (If, for whatever reason, you do need to 242change your homeserver's keys, you may find that other homeserver have the 243old key cached. If you update the signing key, you should change the name of the 244key in the `<server name>.signing.key` file (the second word) to something 245different. See the [spec](https://matrix.org/docs/spec/server_server/latest.html#retrieving-server-keys) for more information on key management). 246 247To actually run your new homeserver, pick a working directory for Synapse to 248run (e.g. `~/synapse`), and: 249 250```sh 251cd ~/synapse 252source env/bin/activate 253synctl start 254``` 255 256#### Platform-specific prerequisites 257 258Synapse is written in Python but some of the libraries it uses are written in 259C. So before we can install Synapse itself we need a working C compiler and the 260header files for Python C extensions. 261 262##### Debian/Ubuntu/Raspbian 263 264Installing prerequisites on Ubuntu or Debian: 265 266```sh 267sudo apt install build-essential python3-dev libffi-dev \ 268 python3-pip python3-setuptools sqlite3 \ 269 libssl-dev virtualenv libjpeg-dev libxslt1-dev 270``` 271 272##### ArchLinux 273 274Installing prerequisites on ArchLinux: 275 276```sh 277sudo pacman -S base-devel python python-pip \ 278 python-setuptools python-virtualenv sqlite3 279``` 280 281##### CentOS/Fedora 282 283Installing prerequisites on CentOS or Fedora Linux: 284 285```sh 286sudo dnf install libtiff-devel libjpeg-devel libzip-devel freetype-devel \ 287 libwebp-devel libxml2-devel libxslt-devel libpq-devel \ 288 python3-virtualenv libffi-devel openssl-devel python3-devel 289sudo dnf groupinstall "Development Tools" 290``` 291 292##### macOS 293 294Installing prerequisites on macOS: 295 296You may need to install the latest Xcode developer tools: 297```sh 298xcode-select --install 299``` 300 301On ARM-based Macs you may need to explicitly install libjpeg which is a pillow dependency. You can use Homebrew (https://brew.sh): 302```sh 303 brew install jpeg 304 ``` 305 306On macOS Catalina (10.15) you may need to explicitly install OpenSSL 307via brew and inform `pip` about it so that `psycopg2` builds: 308 309```sh 310brew install openssl@1.1 311export LDFLAGS="-L/usr/local/opt/openssl/lib" 312export CPPFLAGS="-I/usr/local/opt/openssl/include" 313``` 314 315##### OpenSUSE 316 317Installing prerequisites on openSUSE: 318 319```sh 320sudo zypper in -t pattern devel_basis 321sudo zypper in python-pip python-setuptools sqlite3 python-virtualenv \ 322 python-devel libffi-devel libopenssl-devel libjpeg62-devel 323``` 324 325##### OpenBSD 326 327A port of Synapse is available under `net/synapse`. The filesystem 328underlying the homeserver directory (defaults to `/var/synapse`) has to be 329mounted with `wxallowed` (cf. `mount(8)`), so creating a separate filesystem 330and mounting it to `/var/synapse` should be taken into consideration. 331 332To be able to build Synapse's dependency on python the `WRKOBJDIR` 333(cf. `bsd.port.mk(5)`) for building python, too, needs to be on a filesystem 334mounted with `wxallowed` (cf. `mount(8)`). 335 336Creating a `WRKOBJDIR` for building python under `/usr/local` (which on a 337default OpenBSD installation is mounted with `wxallowed`): 338 339```sh 340doas mkdir /usr/local/pobj_wxallowed 341``` 342 343Assuming `PORTS_PRIVSEP=Yes` (cf. `bsd.port.mk(5)`) and `SUDO=doas` are 344configured in `/etc/mk.conf`: 345 346```sh 347doas chown _pbuild:_pbuild /usr/local/pobj_wxallowed 348``` 349 350Setting the `WRKOBJDIR` for building python: 351 352```sh 353echo WRKOBJDIR_lang/python/3.7=/usr/local/pobj_wxallowed \\nWRKOBJDIR_lang/python/2.7=/usr/local/pobj_wxallowed >> /etc/mk.conf 354``` 355 356Building Synapse: 357 358```sh 359cd /usr/ports/net/synapse 360make install 361``` 362 363##### Windows 364 365Running Synapse natively on Windows is not officially supported. 366 367If you wish to run or develop Synapse on Windows, the Windows Subsystem for 368Linux provides a Linux environment which is capable of using the Debian, Fedora, 369or source installation methods. More information about WSL can be found at 370<https://docs.microsoft.com/en-us/windows/wsl/install> for Windows 10/11 and 371<https://docs.microsoft.com/en-us/windows/wsl/install-on-server> for 372Windows Server. 373 374## Setting up Synapse 375 376Once you have installed synapse as above, you will need to configure it. 377 378### Using PostgreSQL 379 380By default Synapse uses an [SQLite](https://sqlite.org/) database and in doing so trades 381performance for convenience. Almost all installations should opt to use [PostgreSQL](https://www.postgresql.org) 382instead. Advantages include: 383 384- significant performance improvements due to the superior threading and 385 caching model, smarter query optimiser 386- allowing the DB to be run on separate hardware 387 388For information on how to install and use PostgreSQL in Synapse, please see 389[Using Postgres](../postgres.md) 390 391SQLite is only acceptable for testing purposes. SQLite should not be used in 392a production server. Synapse will perform poorly when using 393SQLite, especially when participating in large rooms. 394 395### TLS certificates 396 397The default configuration exposes a single HTTP port on the local 398interface: `http://localhost:8008`. It is suitable for local testing, 399but for any practical use, you will need Synapse's APIs to be served 400over HTTPS. 401 402The recommended way to do so is to set up a reverse proxy on port 403`8448`. You can find documentation on doing so in 404[the reverse proxy documentation](../reverse_proxy.md). 405 406Alternatively, you can configure Synapse to expose an HTTPS port. To do 407so, you will need to edit `homeserver.yaml`, as follows: 408 409- First, under the `listeners` section, uncomment the configuration for the 410 TLS-enabled listener. (Remove the hash sign (`#`) at the start of 411 each line). The relevant lines are like this: 412 413```yaml 414 - port: 8448 415 type: http 416 tls: true 417 resources: 418 - names: [client, federation] 419 ``` 420 421- You will also need to uncomment the `tls_certificate_path` and 422 `tls_private_key_path` lines under the `TLS` section. You will need to manage 423 provisioning of these certificates yourself. 424 425 If you are using your own certificate, be sure to use a `.pem` file that 426 includes the full certificate chain including any intermediate certificates 427 (for instance, if using certbot, use `fullchain.pem` as your certificate, not 428 `cert.pem`). 429 430For a more detailed guide to configuring your server for federation, see 431[Federation](../federate.md). 432 433### Client Well-Known URI 434 435Setting up the client Well-Known URI is optional but if you set it up, it will 436allow users to enter their full username (e.g. `@user:<server_name>`) into clients 437which support well-known lookup to automatically configure the homeserver and 438identity server URLs. This is useful so that users don't have to memorize or think 439about the actual homeserver URL you are using. 440 441The URL `https://<server_name>/.well-known/matrix/client` should return JSON in 442the following format. 443 444```json 445{ 446 "m.homeserver": { 447 "base_url": "https://<matrix.example.com>" 448 } 449} 450``` 451 452It can optionally contain identity server information as well. 453 454```json 455{ 456 "m.homeserver": { 457 "base_url": "https://<matrix.example.com>" 458 }, 459 "m.identity_server": { 460 "base_url": "https://<identity.example.com>" 461 } 462} 463``` 464 465To work in browser based clients, the file must be served with the appropriate 466Cross-Origin Resource Sharing (CORS) headers. A recommended value would be 467`Access-Control-Allow-Origin: *` which would allow all browser based clients to 468view it. 469 470In nginx this would be something like: 471 472```nginx 473location /.well-known/matrix/client { 474 return 200 '{"m.homeserver": {"base_url": "https://<matrix.example.com>"}}'; 475 default_type application/json; 476 add_header Access-Control-Allow-Origin *; 477} 478``` 479 480You should also ensure the `public_baseurl` option in `homeserver.yaml` is set 481correctly. `public_baseurl` should be set to the URL that clients will use to 482connect to your server. This is the same URL you put for the `m.homeserver` 483`base_url` above. 484 485```yaml 486public_baseurl: "https://<matrix.example.com>" 487``` 488 489### Email 490 491It is desirable for Synapse to have the capability to send email. This allows 492Synapse to send password reset emails, send verifications when an email address 493is added to a user's account, and send email notifications to users when they 494receive new messages. 495 496To configure an SMTP server for Synapse, modify the configuration section 497headed `email`, and be sure to have at least the `smtp_host`, `smtp_port` 498and `notif_from` fields filled out. You may also need to set `smtp_user`, 499`smtp_pass`, and `require_transport_security`. 500 501If email is not configured, password reset, registration and notifications via 502email will be disabled. 503 504### Registering a user 505 506The easiest way to create a new user is to do so from a client like [Element](https://element.io/). 507 508Alternatively, you can do so from the command line. This can be done as follows: 509 510 1. If synapse was installed via pip, activate the virtualenv as follows (if Synapse was 511 installed via a prebuilt package, `register_new_matrix_user` should already be 512 on the search path): 513 ```sh 514 cd ~/synapse 515 source env/bin/activate 516 synctl start # if not already running 517 ``` 518 2. Run the following command: 519 ```sh 520 register_new_matrix_user -c homeserver.yaml http://localhost:8008 521 ``` 522 523This will prompt you to add details for the new user, and will then connect to 524the running Synapse to create the new user. For example: 525``` 526New user localpart: erikj 527Password: 528Confirm password: 529Make admin [no]: 530Success! 531``` 532 533This process uses a setting `registration_shared_secret` in 534`homeserver.yaml`, which is shared between Synapse itself and the 535`register_new_matrix_user` script. It doesn't matter what it is (a random 536value is generated by `--generate-config`), but it should be kept secret, as 537anyone with knowledge of it can register users, including admin accounts, 538on your server even if `enable_registration` is `false`. 539 540### Setting up a TURN server 541 542For reliable VoIP calls to be routed via this homeserver, you MUST configure 543a TURN server. See [TURN setup](../turn-howto.md) for details. 544 545### URL previews 546 547Synapse includes support for previewing URLs, which is disabled by default. To 548turn it on you must enable the `url_preview_enabled: True` config parameter 549and explicitly specify the IP ranges that Synapse is not allowed to spider for 550previewing in the `url_preview_ip_range_blacklist` configuration parameter. 551This is critical from a security perspective to stop arbitrary Matrix users 552spidering 'internal' URLs on your network. At the very least we recommend that 553your loopback and RFC1918 IP addresses are blacklisted. 554 555This also requires the optional `lxml` python dependency to be installed. This 556in turn requires the `libxml2` library to be available - on Debian/Ubuntu this 557means `apt-get install libxml2-dev`, or equivalent for your OS. 558 559### Troubleshooting Installation 560 561`pip` seems to leak *lots* of memory during installation. For instance, a Linux 562host with 512MB of RAM may run out of memory whilst installing Twisted. If this 563happens, you will have to individually install the dependencies which are 564failing, e.g.: 565 566```sh 567pip install twisted 568``` 569 570If you have any other problems, feel free to ask in 571[#synapse:matrix.org](https://matrix.to/#/#synapse:matrix.org). 572