Matrix synapse raspberry pi


Choosing your server name

It is important to choose the name for your server before you install Synapse, because it cannot be changed later.

The server name determines the «domain» part of user-ids for users on your server: these will all be of the format . 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 ( ) rather than a matrix-specific hostname here (in the same way that your email address is probably rather than ) — but doing so may require more advanced setup: see Setting up Federation.

Installing Synapse

Prebuilt packages

Prebuilt packages are available for a number of platforms. These are recommended for most users.

Docker images and Ansible playbooks

There is an official synapse image available at which can be used with the docker-compose file available at contrib/docker. Further information on this including configuration options is available in the README on

Alternatively, Andreas Peters (previously Silvio Fricke) has contributed a Dockerfile to automate a synapse server in a single Docker image, at

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, Element, coturn, ma1sd, SSL support, etc.). For more details, see

Debian/Ubuntu packages provides Debian/Ubuntu packages of Synapse, for the amd64 architecture via

To install the latest release:

Packages are also published for release candidates. To enable the prerelease channel, add prerelease to the sources.list line. For example:

The fingerprint of the repository signing key (as shown by gpg /usr/share/keyrings/matrix-org-archive-keyring.gpg ) is AAF9AE843A7584B5A3E4CD2BCF45A512DE2DA058 .

When installing with Debian packages, you might prefer to place files in /etc/matrix-synapse/conf.d/ to override your configuration without editing the main configuration file at /etc/matrix-synapse/homeserver.yaml . By doing that, you won’t be asked if you want to replace your configuration file when you upgrade the Debian package to a later version.

Downstream Debian packages

Andrej Shadura maintains a matrix-synapse package in the Debian repositories. For bookworm and sid , it can be installed simply with:

Synapse is also avaliable in bullseye-backports . Please see the Debian documentation for information on how to use backports.

matrix-synapse is no longer maintained for buster and older.

Downstream Ubuntu packages

We do not recommend using the packages in the default Ubuntu repository at this time, as they are old and suffer from known security vulnerabilities. The latest version of Synapse can be installed from our repository.


Synapse is in the Fedora repositories as matrix-synapse :


Synapse is in the OpenSUSE repositories as matrix-synapse :

SUSE Linux Enterprise Server

Unofficial package are built for SLES 15 in the openSUSE:Backports:SLE-15 repository at


The quickest way to get up and running with ArchLinux is probably with the community package, 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 ):

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):

Void Linux

Synapse can be found in the void repositories as ‘synapse’:


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 py38-matrix-synapse


As of OpenBSD 6.7 Synapse is available as a pre-compiled binary. The filesystem underlying the homeserver directory (defaults to /var/synapse ) has to be mounted with wxallowed (cf. mount(8) ), so creating a separate filesystem and mounting it to /var/synapse should be taken into consideration.


Installing as a Python module from PyPI

It’s also possible to install Synapse as a Python module from PyPI.

When following this route please make sure that the Platform-specific prerequisites are already installed.

  • POSIX-compliant system (tested on Linux & OS X)
  • Python 3.7 or later, up to Python 3.10.
  • At least 1GB of free RAM if you want to join large public rooms like

If building on an uncommon architecture for which pre-built wheels are unavailable, you will need to have a recent Rust compiler installed. The easiest way of installing the latest version is to use rustup.

To install the Synapse homeserver run:

This will download Synapse from PyPI and install it, along with the python libraries it uses, into a virtual environment under

/synapse/env . Feel free to pick a different directory if you prefer.

This Synapse installation can then be later upgraded by using pip again with the update flag:

Before you can start Synapse, you will need to generate a configuration file. To do this, run (in your virtualenv, as before):

. substituting an appropriate value for —server-name and choosing whether or not to report usage statistics (hostname, Synapse version, uptime, total users, etc.) to the developers via the —report-stats argument.

This command will generate you a config file that you can then customise, but it will also generate a set of keys for you. These keys will allow your homeserver to identify itself to other homeserver, so don’t lose or delete them. It would be wise to back them up somewhere safe. (If, for whatever reason, you do need to change your homeserver’s keys, you may find that other homeserver have the old key cached. If you update the signing key, you should change the name of the key in the .signing.key file (the second word) to something different. See the spec for more information on key management).

To actually run your new homeserver, pick a working directory for Synapse to run (e.g.

Platform-specific prerequisites

Synapse is written in Python but some of the libraries it uses are written in C. So before we can install Synapse itself we need a working C compiler and the header files for Python C extensions.


Installing prerequisites on Ubuntu or Debian:


Installing prerequisites on ArchLinux:


Installing prerequisites on CentOS or Fedora Linux:


Installing prerequisites on macOS:

You may need to install the latest Xcode developer tools:

On ARM-based Macs you may need to install libjpeg and libpq. You can use Homebrew (

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


Installing prerequisites on openSUSE:


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

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

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

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

Setting the WRKOBJDIR for building python:


Running Synapse natively on Windows is not officially supported.

If you wish to run or develop Synapse on Windows, the Windows Subsystem for Linux provides a Linux environment which is capable of using the Debian, Fedora, or source installation methods. More information about WSL can be found at for Windows 10/11 and for Windows Server.

Setting up Synapse

Once you have installed synapse as above, you will need to configure it.

Using PostgreSQL

By default Synapse uses an SQLite database and in doing so trades performance for convenience. Almost all installations should opt to use PostgreSQL instead. Advantages include:

  • significant performance improvements due to the superior threading and caching model, smarter query optimiser
  • allowing the DB to be run on separate hardware

For information on how to install and use PostgreSQL in Synapse, please see Using Postgres

SQLite is only acceptable for testing purposes. SQLite should not be used in a production server. Synapse will perform poorly when using SQLite, especially when participating in large rooms.

TLS certificates

The default configuration exposes a single HTTP port on the local interface: http://localhost:8008 . It is suitable for local testing, but for any practical use, you will need Synapse’s APIs to be served over HTTPS.

The recommended way to do so is to set up a reverse proxy on port 8448 . You can find documentation on doing so in the reverse proxy documentation.

Alternatively, you can configure Synapse to expose an HTTPS port. To do so, you will need to edit homeserver.yaml , as follows:

  • First, under the listeners option, add the configuration for the TLS-enabled listener like so:

    You will also need to add the options tls_certificate_path and tls_private_key_path . to your configuration file. You will need to manage provisioning of these certificates yourself.

    You can find more information about these options as well as how to configure synapse in the configuration manual.

    If you are using your own certificate, be sure to use a .pem file that includes the full certificate chain including any intermediate certificates (for instance, if using certbot, use fullchain.pem as your certificate, not cert.pem ).

    For a more detailed guide to configuring your server for federation, see Federation.

    Client Well-Known URI

    Setting up the client Well-Known URI is optional but if you set it up, it will allow users to enter their full username (e.g. @user: ) into clients which support well-known lookup to automatically configure the homeserver and identity server URLs. This is useful so that users don’t have to memorize or think about the actual homeserver URL you are using.

    The URL https:// /.well-known/matrix/client should return JSON in the following format.

    It can optionally contain identity server information as well.

    To work in browser based clients, the file must be served with the appropriate Cross-Origin Resource Sharing (CORS) headers. A recommended value would be Access-Control-Allow-Origin: * which would allow all browser based clients to view it.

    In nginx this would be something like:

    You should also ensure the public_baseurl option in homeserver.yaml is set correctly. public_baseurl should be set to the URL that clients will use to connect to your server. This is the same URL you put for the m.homeserver base_url above.


    It is desirable for Synapse to have the capability to send email. This allows Synapse to send password reset emails, send verifications when an email address is added to a user’s account, and send email notifications to users when they receive new messages.

    To configure an SMTP server for Synapse, modify the configuration section headed email , and be sure to have at least the smtp_host , smtp_port and notif_from fields filled out. You may also need to set smtp_user , smtp_pass , and require_transport_security .

    If email is not configured, password reset, registration and notifications via email will be disabled.

    Registering a user

    One way to create a new user is to do so from a client like Element. This requires registration to be enabled via the enable_registration setting.

    Alternatively, you can create new users from the command line. This can be done as follows:

    1. If synapse was installed via pip, activate the virtualenv as follows (if Synapse was installed via a prebuilt package, register_new_matrix_user should already be on the search path):
    2. Run the following command:

    This will prompt you to add details for the new user, and will then connect to the running Synapse to create the new user. For example:

    This process uses a setting registration_shared_secret , 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, including admin accounts, 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 TURN setup 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 python dependency 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.


    Setting up a Matrix chat server on a Raspberry Pi

    By Nicholas Masso

    Written July 2020

    Update August 2021: Added a comments section.


    This guide will explain all the steps required to set up and run a matrix server, a federated (decentralized) and encrypted chat service. This will allow users with any compatible client to create accounts, join groups, and send messages. The most popular client is Element which was previously known as Riot. While you and your friends can create accounts on your homeserver, the federated nature of matrix allows these accounts to join groups hosted on any server, around the world.

    In a time when more and more of our communication is done through large, centralized corporations, it is important to take back control of your data. In this setup, all message logs and VoIP services will be managed by the Raspberry Pi in your home.

    Anyone trying to follow this guide should be familiar with working in the terminal on a Unix machine, as well as managing their local network. The steps performed in this tutorial could possibly open your home network to vulnerabilities if not performed correctly.

    To fully complete every step will take roughly three hours, with large amounts of that time spent waiting for program installs and setup.


    To set up a server like this, you will need to have a domain name registered to redirect to your home IP address. You can attain these in various ways, and can set this up for free with a site like freeDNS.

    You must also have administrator rights to your home network. This guide requires changing port forwarding rules, so you must be able to log into your home router.

    The items needed are:

    • A computer to run the setup on
    • Raspberry Pi (Version 3B+ or newer)
    • Optional: a case for the Raspberry Pi
    • A power supply for the RPI capable of at least 2A
    • A microSD card, with at least 8GB of space
    • An ethernet cable

    Your computer will also need to be able to resolve zero-configuration networking addresses.

    • All computers running a Unix-based OS (including all Mac OS versions) can do this by default. No action is required.
    • Computers running Windows must install a Zeroconf resolution service. Apple has a patent on Bonjour which you will have to download and install.


    Preparing the Raspberry Pi

    This installation includes the least amount of software required to run a full Debian-based OS on the Raspberry Pi. This will save us memory and disk space for this dedicated server. It does not have a graphical desktop environment, as we do not require one.

    Flash the disk image to the SD card using your preferred disk imaging software. I use Rufus for most of my disk creation.

    Create an empty file called “ssh” and copy it to the boot directory of the SD card. This will enable SSH communication on the Raspberry Pi without connecting a keyboard.

    WARNING: If you do not have a case for the Raspberry Pi, make sure it is not resting on a metal or otherwise conductive surface when you power it on. This could cause a short between the exposed pins of the Pi and destroy it. If necessary, put a nonconductive object underneath it.

    Power on the Pi and connect it to your local network using ethernet or Wi-Fi.

    Establish an SSH connection to the pi using your terminal of choice. The default address is “raspberrypi.local” The default username is “pi” The default password is “raspberry”

    Use the Raspberry Pi Software Configuration Tool to change defaults of the Pi. Running this command will open the graphical program to assist with changing some of the system details.

    a. Change the user password to something strong. Keep track of this password. A typical way to set strong passwords is to use 3-4 short words. This is easy to remember and hard to break.

    b. In “Network Settings” change the hostname to something recognizable like “matrix”.

    c. If you desire, in this tool you can also connect to a nearby Wi-Fi network.

    Exit the utility and reboot the raspberry pi.

    Setting up the Network

    Log into your router and assign the raspberry pi to an unused static IP address. Remember, we made the hostname “matrix” so it should be easy to identify from within the router’s settings.

    Allow ports 80, 443, and 8448 to be forwarded to the Raspberry Pi.

    Port 443 is dedicated to HTTPS encrypted data transfer and will be used by clients to receive and view messages. Port 8448 is the port used for server-to-server communications, so that users registered with other servers can get information about any groups hosted on our server. Port 80 will only be used to communicate with the certification servers, which will handle user authentication. This port will also refuse users who try to connect via HTTP protocol without encryption.

    Log out of your router’s settings. Reboot the router if necessary.

    Now we can SSH back into the Pi. We changed the hostname, so now you can either SSH to the new hostname (example, matrix.local) or directly to the static IP address you set.

    Open the DHCPCD configuration file. We will be changing the Pi’s DHCP settings so that it knows it has a static IP address.

    Scroll down and uncomment the “example static IP configuration” options as shown in the example below. Replace “” with whatever IP address you set in the router configuration. You can leave the IPv6 address commented out, unless you are using it – in which case replace it with your value as well.

    Reboot the pi again with this command.

    Install Prerequisites

    Most commands we are going to run in this section of the guide will be done with the superuser authority.

    Enter the superuser by running the command:

    WARNING: be careful with all commands run while logged in as the root user. this user has the highest level of permissions on the computer and can seriously damage the operating system if not handled properly.

    The command prompt should change as shown below. This terminal session now has root authority.

    Now we have to update all the software that came with the image for the pi. this may take a moment, as there may be several updates.

    Next we are going to install all software that is required by the matrix and synapse services.

    We are also going to set python 3 as our default python version using this command.

    Note that at the time of writing, python 3.7 is the newest version. When a later version is released, make sure to update the path to the executable.

    Now we will leave the superuser by typing

    Setting up Synapse Server

    Now we get to start installing the programs which run the server itself.

    We will create a python virtual environment in a new folder where we will keep all our files.

    Now we will enter the virtual environment with

    Inside the virtual environment, we must update and install some programs.

    Now we will install synapse in the virtual environment. This may take a while, but it will complete eventually.

    Configure the server by running the following command with “” replaced with your own domain name.

    Next we will activate the certification program. This will trigger a series of prompts, which you can fill out.

    We will abide by good practice for matrix and configure a reverse proxy with Nginx. This will involve modifying a file and restarting Nginx

    Copy these contents into the empty file, with replaced with your domain name.

    Save and close the file.

    Restart the Nginx service to apply the changes.

    Next we will enable user registration on your server. We will still have to create an admin account manually, but this will allow friends to use your homeserver to store their accounts.

    First we will open the server settings file

    Now we will find the line we want to uncomment by searching for enable_registration (ctrl+w). Find the correct line and uncomment it, and change false to true

    Save and close the file once you are done.

    Registering a User

    These steps will register the first user so that we can log into the server and manage it from a GUI client installed on our computer.

    These steps should be performed from inside the Python virtual environment, and in the synapse folder. Make sure the command prompt looks like this:

    Start the synapse server with this command:

    Several messages will be printed to the screen. At the end, the program should say the program has been started.

    Run the user configuration program with

    Follow the prompts to enter the username, password, and “yes” to make this user an admin.

    You can now use a client to log into this server. Leave the python environment with

    And disconnect from the SSH session with

    Note: if you ever want to change settings for the server, stop the server first with

    And then you can edit the homeserver.yaml file. Remember to start the server again with

    Logging into the Server

    Now that the server is running, you can download a messaging client to your computer, smartphone, or simply navigate to with a web browser.

    When you are at the login screen, click “change” to specify your own homeserver to log into.

    Enter your domain name here, and click next.

    You should be able to enter the username and password you created in the earlier steps. You will be greeted by a homepage, were you can create and join communities.


    At the end of this document, you should have logged in to your server. You will have to create and manage rooms, which is a task specific to your client. You can send the URL of your server to your friends, and they can create user accounts in their own clients and message you! You can also join servers hosted by other people, and start talking in those groups. You can try joining the server at, which is hosted by the Matrix Foundation itself. This is the largest public server, and you can talk to other people who are interested in freeware and privacy.

    You also need to be mindful of the Raspberry Pi running the server. If you unplug the device, nobody who has an account on the server will be able to send messages – you could possibly invest in an uninterruptible power supply (UPS) to power your router and Raspberry Pi with, in the event your house loses power. Perhaps supply your email address to your members so that they can contact you if a problem arises.

    An Uninterruptible Power Supply could last without mains power for a long time!

    As the owner and administrator of your server, you need to be responsible for the things that go on inside your server. Perhaps create a set of rules for people who join, and make sure to remove people who spread hate or are not trustworthy. The security of your server’s content depends on the least trustworthy person who can read your messages! Most of all, have fun! You are now a pioneer of a new, safer form of communication.

    Make sure rooms you chat in have a notification like this.