Install Matrix Synapse Home Server on Debian Linux


What is Matrix?

Matrix is an open source project that publishes the
Matrix open standard for secure, decentralised, real-time communication, and its Apache licensed
reference implementations. -https://matrix.org

What is Synapse?

Synapse is a Matrix "homeserver" implementation developed by the matrix.org core team, written in Python 3/Twisted. -https://github.com/matrix-org/synapse/

Installing Synapse

  1. Log into the Linux device
  2. Run the following commands in terminal
    # update software repositories
    sudo apt update
    # install available software updates
    sudo apt upgrade
    # install prerequisites
    sudo apt install lsb-release wget openssl apt-transport-https -y
    # add matrix gpg key
    sudo wget -O /usr/share/keyrings/matrix-org-archive-keyring.gpg https://packages.matrix.org/debian/matrix-org-archive-keyring.gpg
    # add matrix apt repository
    echo "deb [signed-by=/usr/share/keyrings/matrix-org-archive-keyring.gpg] https://packages.matrix.org/debian/ $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/matrix-org.list
    # update software repositories
    sudo apt update
    # install synapse
    sudo apt install matrix-synapse-py3 -y
    # when prompted, enter localhost as the name of the matrix server
    # choose whether to share statistics with matrix
    # install postgresql
    sudo apt install libpq5 postgresql -y
    # enable the postgresql service and start it
    sudo systemctl enable postgresql --now
    # connect to postgresql
    sudo -u postgres psql postgres
    # create synapse database user
    create user matrix_synapse_rw with password 'm@trix!';
    # create matrix_synapse database
    create database matrix_synapse with encoding='UTF8' lc_collate='C' lc_ctype='C' template='template0' owner='matrix_synapse_rw';
    # close postgresql connection
    exit
    # edit the homeserver.yaml file
    sudo nano /etc/matrix-synapse/homeserver.yaml
  3. Press CTRL+W and search for name: sqlite3
  4. Comment out the sqlite database parameters by adding a # to the beginning of each of the lines
  5. Paste the following psycopg2 (Postgres) database connection and update it as needed:

    database:
     name: psycopg2
     txn_limit: 10000
     args:
      user: matrix_synapse_rw
      password: m@trix!
      database: matrix_synapse
      host: localhost
      port: 5432
      cp_min: 5
      cp_max: 10

  6. Press CTRL+W and search for name: bind_addresses: [
  7. Edit the bind addresses value to add either the host servers IP address or set the value to '0.0.0.0' to listen on all interfaces
  8. Add the following line at the bottom of the file

    suppress_key_server_warning: true

  9. Press CTRL+O, Enter, CTRL+X to write the changes
  10. Continue with the following commands
    # generate a randoml string
    RANDOMSTRING=$(openssl rand -base64 30)
    # write the random string as registration_shared_secret
    echo "registration_shared_secret: $RANDOMSTRING" | sudo tee -a /etc/matrix-synapse/homeserver.yaml > /dev/null
    # restart the synapse service
    sudo systemctl restart matrix-synapse
    # create a new synapse user
    register_new_matrix_user -c /etc/matrix-synapse/homeserver.yaml http://localhost:8008
  11. Enter a username, enter and confirm the password and choose if the user is an admin
  12. At this point the Matrix Synapse server is running, but only over http
  13. Open a web browser and navigate to the http://DNSorIP:8008
  14. A message stating It works! Synapse is running should be displayed

Testing with Element Desktop Application (Optional)

  1. To test the Synapse server with a matrix client, continue with the following commands
    # add the element.io gpg key
    sudo wget -O /usr/share/keyrings/element-io-archive-keyring.gpg https://packages.element.io/debian/element-io-archive-keyring.gpg
    # add the element.io apt repository
    echo "deb [signed-by=/usr/share/keyrings/element-io-archive-keyring.gpg] https://packages.element.io/debian/ default main" | sudo tee /etc/apt/sources.list.d/element-io.list
    # update software repositories
    sudo apt update
    # install element desktop
    sudo apt install element-desktop -y
  2. Launch the Element application
  3. Click Sign In
  4. Click the Edit link next to matrix.org
  5. Select Other homeserver > type http://DNSorIP:8008 > Click Continue
  6. Login using the Synapse username and password created earlier
  7. After testing, logout by clicking the username in the top left of the application > Sign out > Select I don't want my encrypted messages

Enabling SSL Using Let's Encrypt

NOTE: In order for Let's Encrypt to verify ownership of the DNS name, the host certbot is running from must be accessible via port 80 (http) or port 443 (https). For homelab users, this will normally involve port forwarding from the router to the certbot host, which is beyond the scope of this tutorial. Just note, I have forwarded port 80 on my router to the host running certbot for this handshake to complete successfully.

  1. Continue with the following commands in a terminal window
    # remove apt version of certbot if installed
    sudo apt remove certbot -y
    # install snapd
    sudo apt install snapd -y
    # install snap core and update
    sudo snap install core; sudo snap refresh core
    # install certbot snap
    sudo snap install --classic certbot
    # create certbot symbolic link
    sudo ln -s /snap/bin/certbot /usr/bin/certbot
    # if a web server process is currently using port 80, stop it before proceeding
    # generate a certificate
    sudo certbot certonly --standalone --preferred-challenges http -d <%DNS NAME%>
  2. When prompted, enter an email address and agree to the terms of service
  3. Choose whether to share your email and receive emails from certbot
  4. Certbot will output information regarding the location of the certificate files
  5. Continue with the following commands in a terminal window
    # create ssl-certs group
    sudo groupadd ssl-certs
    # add matrix-synapse and root users to group
    sudo usermod -aG ssl-certs matrix-synapse
    sudo usermod -aG ssl-certs root
    # verify the members of ssl-cert
    getent group ssl-certs
    # set owner group of /etc/letsencrypt
    sudo chgrp -R ssl-certs /etc/letsencrypt
    # set permissions on /etc/letsencrypt
    sudo chmod -R g=rX /etc/letsencrypt
    # edit the homeserver.yaml file
    sudo nano /etc/matrix-synapse/homeserver.yaml
  6. Press CTRL+W and search for port: 8008
  7. Change the tls: false value to true (tls: true)
  8. Press CTRL+W and search for tls_certificate_path:
  9. Uncomment the line and update to /etc/letsencrypt/live/<%DNS NAME%>/fullchain.pem
  10. Arrow down a few lines to find tls_private_key_path
  11. Uncomment the line and update to /etc/letsencrypt/live/<%DNS NAME%>/privkey.pem
  12. Press CTRL+O, Enter, CTRL+X to write the changes
  13. Continue with the following commands in a terminal window
    # restart the synapse service
    sudo systemctl restart matrix-synapse

Installing Element Web Client (Optional)

  1. Continue with the following commands to install the Element web client
    # install apache2
    sudo apt install apache2 -y
    # lookup the latest release tag
    regex='<link rel="alternate" type="text\/html" href="https:\/\/github\.com\/vector-im\/element-web\/releases\/tag\/([^/]*)"' && response=$(curl -s https://github.com/vector-im/element-web/releases.atom) && [[ $response =~ $regex ]] && latestTag="${BASH_REMATCH[1]}"
    # download element-web
    wget -O element.tar.gz https://github.com/vector-im/element-web/releases/download/$latestTag/element-$latestTag.tar.gz
    # extract element to wwwroot
    sudo tar xzvf element.tar.gz -C /var/www/html
    # rename the extracted folder
    sudo mv /var/www/html/element* /var/www/html/element
    # set the owner to www-data
    sudo chown -R www-data:www-data /var/www/html/element
    # make a copy of the sample config file
    sudo cp /var/www/html/element/config.sample.json /var/www/html/element/config.json
    # edit the config file
    sudo nano /var/www/html/element/config.json
  2. Edit the m.homeserver values, replacing the the server_name with an alias and base_url with https://YOURDNSNAME:8008
  3. Press CTRL+O, Enter, CTRL+X to write the changes
  4. Open a web browser and navigate to http://DNSorIP/element
  5. Log in using the Synapse username and password created earlier