meta data for this page
  •  

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
digital:server:matrixsynapse [2019/05/30 11:10]
natrius Step 3 - deleted FIXME
digital:server:matrixsynapse [2022/01/14 00:15] (current)
natrius riot -> element; minor rewrite of Step 9
Line 1: Line 1:
 # Matrix Synapse # Matrix Synapse
  
-[[https://matrix.org/|Matrix]] is an open standard for interoperable, decentralised, real-time communication over IP. It can be used to power Instant Messaging, VoIP and Internet of Things communication - or anywhere you need a standard HTTP API for publishing and subscribing to data whilst tracking the conversation history.+[[https://matrix.org/|Matrix]] is an open standard for interoperable, decentralised, real-time communication over IP. It can be used to power Instant Messaging, VoIP and Internet of Things communication - or anywhere you need a standard HTTP API for publishing and subscribing to data whilst tracking the conversation history. 
  
 Synapse is a reference homeserver implementation from the core development team at matrix.org, written in Python/Twisted. Synapse is a reference homeserver implementation from the core development team at matrix.org, written in Python/Twisted.
Line 9: Line 9:
 This guide explains one way to setup a Synapse server. There are many other correct ways to setup a Matrix server and that is the reason why there are so many guides. Feel free to choose the guide that suits your setup the best. This guide explains one way to setup a Synapse server. There are many other correct ways to setup a Matrix server and that is the reason why there are so many guides. Feel free to choose the guide that suits your setup the best.
  
-## How to install Synapse on Ubuntu 18.04 LTS+## How to install Synapse on Ubuntu Server 18.04 LTS (and Ubuntu Server 20.04.1 LTS)
  
 ### Prerequisites ### Prerequisites
Line 39: Line 39:
 sudo apt install -y lsb-release wget apt-transport-https sudo apt install -y lsb-release wget apt-transport-https
 sudo wget -O /usr/share/keyrings/matrix-org-archive-keyring.gpg https://packages.matrix.org/debian/matrix-org-archive-keyring.gpg sudo wget -O /usr/share/keyrings/matrix-org-archive-keyring.gpg https://packages.matrix.org/debian/matrix-org-archive-keyring.gpg
-echo "deb [signed-by=/usr/share/keyrings/matrix-org-archive-keyring.gpg] https://packages.matrix.org/debian/ $(lsb_release -cs) main" | +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
-    sudo tee /etc/apt/sources.list.d/matrix-org.list+
 </code> </code>
  
Line 53: Line 52:
     sudo apt install matrix-synapse-py3     sudo apt install matrix-synapse-py3
  
-During the installation, it will ask you about the matrix server name - type in your domain ''example.com''. (We will not use ''matrix.example.com'', because we also don't use ''mail.example.com'' for our E-Mails. This will work with well.known, SRV-records and nginx.+During the installation, it will ask you about the matrix server name - type in your domain ''homeserver.example''. (We will not use ''matrix.homeserver.example'', because we also don't use ''mail.homeserver.example'' for our E-Mails. This will work with well.known, SRV-records and nginx.
  
 **Don't leave the hostname blank during setup.** **Don't leave the hostname blank during setup.**
Line 64: Line 63:
     sudo systemctl enable matrix-synapse.service     sudo systemctl enable matrix-synapse.service
  
-Synapse is now up and running using the default configuration on port '8008' and '8448'. Check the open ports using netstat command.+Synapse is now up and running using the default configuration on port '8008'. Check the open ports using ss (former netstatcommand.
  
-    sudo ss -plntu +    ss -plntu
- +
-#### Set up well.known +
- +
-FIXME +
- +
-#### Set up SRV +
- +
-By setting an SRV record in your DNS provider, it is possible to tell other matrix servers where to connect to the server, pointing them to the correct hostname and port, in this example the default port (8448) is still used: +
- +
-<code> +
- _matrix._tcp.example.com. 3600 IN SRV 10 5 443 synapse.example.com. +
-</code> +
- +
-There is still an A record needed, pointing to the IP-addess of synapse on the subdomain (matrix.example.com). This way others can add your user with ''@user:example.com'' instead of ''@user:matrix.example.com''.+
  
 ### Step 3 - Configure Synapse ### Step 3 - Configure Synapse
Line 96: Line 81:
 ''%%enable_registration%%: False'' ''%%enable_registration%%: False''
  
-''%%registration_shared_secret%%: "%%[shared_secred_key]%%"''+''%%registration_shared_secret%%: %%[shared_secred_key]%%''
  
-#### Check listener and federation port+#### Check ports
  
-Now check the HTTP and HTTPS listener port '8008' and the federation port '8448'**The best is to leave it default as it comes delivered** (watch here https://github.com/matrix-org/synapse/blob/master/docs/sample_config.yaml ), so check if it matches the follwing:+**The best is to leave it default as it comes delivered** (watch here https://github.com/matrix-org/synapse/blob/master/docs/sample_config.yaml ), so check if it matches the follwing:
  
 <code>sudoedit /etc/matrix-synapse/homeserver.yaml</code> <code>sudoedit /etc/matrix-synapse/homeserver.yaml</code>
Line 120: Line 105:
 Now restart the Synapse services. Now restart the Synapse services.
  
-    sudo systemctl reload matrix-synapse.service+    sudo systemctl restart matrix-synapse.service
  
 Check the homeserver service with the following command Check the homeserver service with the following command
  
-    sudo ss -plntu+    ss -plntu
  
 You will get the Synapse service is now on the local IP address. And we have completed the Synapse installation and configuration. You will get the Synapse service is now on the local IP address. And we have completed the Synapse installation and configuration.
Line 141: Line 126:
  
     sudo add-apt-repository ppa:certbot/certbot     sudo add-apt-repository ppa:certbot/certbot
-    sudo apt-get install certbot python-certbot-nginx+    sudo apt-get install certbot python3-certbot-nginx
  
-Generate the SSL certificate files for the matrix domain name ''example.com'' using the certbot command as shown below.+Generate the SSL certificate files for the matrix domain name ''homeserver.example'' using the certbot command as shown below.
  
     sudo certbot --nginx     sudo certbot --nginx
  
-The Letsencrypt tool will generate SSL certificate files by running the 'standalone' temporary web server for verification. When it's complete, you will get the information that its done and where the certificates are stored. Usally the SSL certificate files for the Synapse domain name ''example.com'' are generated inside the ''/etc/letsencrypt/live/'' directory.+The Letsencrypt tool will generate SSL certificate files by running the 'standalone' temporary web server for verification. When it's complete, you will get the information that its done and where the certificates are stored. Usally the SSL certificate files for the Synapse domain name ''homeserver.example'' are generated inside the ''/etc/letsencrypt/live/'' directory.
  
 <code> <code>
Line 154: Line 139:
 Obtaining a new certificate Obtaining a new certificate
 Performing the following challenges: Performing the following challenges:
-http-01 challenge for example.com+http-01 challenge for homeserver.example
 Waiting for verification... Waiting for verification...
 Cleaning up challenges Cleaning up challenges
Line 160: Line 145:
 IMPORTANT NOTES: IMPORTANT NOTES:
  - Congratulations! Your certificate and chain have been saved at:  - Congratulations! Your certificate and chain have been saved at:
-   /etc/letsencrypt/live/example.com/fullchain.pem+   /etc/letsencrypt/live/homeserver.example/fullchain.pem
    Your key file has been saved at:    Your key file has been saved at:
-   /etc/letsencrypt/live/example.com/privkey.pem+   /etc/letsencrypt/live/homeserver.example/privkey.pem
    Your cert will expire on 2019-03-03. To obtain a new or tweaked    Your cert will expire on 2019-03-03. To obtain a new or tweaked
    version of this certificate in the future, simply run certbot    version of this certificate in the future, simply run certbot
Line 181: Line 166:
  
 <code>sudo certbot renew --dry-run</code> <code>sudo certbot renew --dry-run</code>
- 
-FIXME We need infos here how and where to edit the homeserver.yaml to add our certificates. 
  
 ### Step 5 - Install and configure Nginx as a reverse proxy ### Step 5 - Install and configure Nginx as a reverse proxy
Line 195: Line 178:
     sudo systemctl enable nginx.service     sudo systemctl enable nginx.service
  
-Next, we will create a new virtual host configuration for the domain name ''example.com''. Go to the '/etc/nginx' configuration directory and create a new virtual host file 'matrix'.+Next, we will create a new virtual host configuration for the domain name ''homeserver.example''. Go to the '/etc/nginx' configuration directory and create a new virtual host file 'matrix'.
  
 <code>sudoedit /etc/nginx/sites-available/matrix</code> <code>sudoedit /etc/nginx/sites-available/matrix</code>
  
-Paste the following configuration there, changing the domain ''example.com'' to your own:+Paste the following configuration there, changing the domain ''homeserver.example'' to your own:
  
 <code> <code>
 server { server {
        listen 80;        listen 80;
-       server_name example.com;+       server_name homeserver.example;
        return 301 https://$server_name$request_uri;        return 301 https://$server_name$request_uri;
 } }
Line 211: Line 194:
     listen 443 ssl;     listen 443 ssl;
     listen [::]:443 ssl;     listen [::]:443 ssl;
-    server_name example.com;+    server_name homeserver.example;
  
-    ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem; +    ssl_certificate /etc/letsencrypt/live/homeserver.example/fullchain.pem; 
-    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;+    ssl_certificate_key /etc/letsencrypt/live/homeserver.example/privkey.pem;
  
     # If you don't wanna serve a site, comment this out     # If you don't wanna serve a site, comment this out
Line 225: Line 208:
     }     }
     location /.well-known/matrix/server {     location /.well-known/matrix/server {
-      return 200 '{"m.server": "example.com:443"}';+      return 200 '{"m.server": "homeserver.example:443"}';
       add_header Content-Type application/json;       add_header Content-Type application/json;
     }     }
     location /.well-known/matrix/client {     location /.well-known/matrix/client {
-      return 200 '{"m.homeserver": {"base_url": "https://example.com"},"m.identity_server": {"base_url": "https://vector.im"}}';+      return 200 '{"m.homeserver": {"base_url": "https://homeserver.example"},"m.identity_server": {"base_url": "https://vector.im"}}';
       add_header Content-Type application/json;       add_header Content-Type application/json;
       add_header "Access-Control-Allow-Origin" *;       add_header "Access-Control-Allow-Origin" *;
Line 235: Line 218:
 } }
 </code> </code>
- 
-FIXME ''location ~ ^/.well-known/matrix/client$ {'' might need to escape the . Check it! 
- 
-FIXME Same for ''location ~ ^/.well-known/matrix/server$ {''? 
  
 Save and exit. Save and exit.
Line 259: Line 238:
 Nginx installation and configuration as a reverse proxy for the Synapse homeserver has been completed. Nginx installation and configuration as a reverse proxy for the Synapse homeserver has been completed.
  
-### (Optional) Step 6 - Postgre instead of sqlite+#### Set up .well-known 
 + 
 +On your webserver a file at ''%%/.well-known/matrix/server%%'' has to be set up with the following content  
 + 
 +<code> 
 +
 +    "m.server": "synapse.homeserver.example:443" 
 +
 +</code> 
 + 
 +Where ''/'' is the root of your webserver. So if you navigate to ''https://homeserver.example/.well-known/matrix/server'' it may try to download the ''server'' file or show it directly. 
 + 
 +### (Optional) Step 6 - PostgreSQL instead of sqlite
  
 While the step is marked as optional, it is **strongly encouraged** for any server that isn't purely for testing. While the step is marked as optional, it is **strongly encouraged** for any server that isn't purely for testing.
  
-#### Initial Postgresql setup+#### Initial PostgreSQL setup
  
 <code>sudo apt install postgresql</code> <code>sudo apt install postgresql</code>
Line 271: Line 262:
 <code>postgres=# CREATE DATABASE synapse ENCODING 'UTF8' LC_COLLATE='C' LC_CTYPE='C' template=template0 OWNER "username";</code> <code>postgres=# CREATE DATABASE synapse ENCODING 'UTF8' LC_COLLATE='C' LC_CTYPE='C' template=template0 OWNER "username";</code>
  
-Where username can be "matrix_synapse", and password is a new strong password you set for postgresql.+Where username can be ''synapse_user'', and password is a new strong password you set for postgresql.
  
 To end the postgre line just type in ''\q'' and close the postegre-usershell with ''exit'' To end the postgre line just type in ''\q'' and close the postegre-usershell with ''exit''
  
-#### Set up Postgre for Synapse+#### Set up PostgreSQL for Synapse
  
 <code>sudo apt install python3-psycopg2</code> <code>sudo apt install python3-psycopg2</code>
Line 296: Line 287:
  
   * ''user'' is in this case ''synapse_user''   * ''user'' is in this case ''synapse_user''
-  * ''Database'' should be the full path to the db, example ''"/var/lib/matrix-synapse/homeserver.db"''+  * ''Database'' should be the above created db, example ''synapse''
   * ''Host'' is the postgre hostname, usally ''/var/run/postgresql/'' or ''127.0.0.1''   * ''Host'' is the postgre hostname, usally ''/var/run/postgresql/'' or ''127.0.0.1''
  
Line 302: Line 293:
  
 <code> <code>
-sudo systemctl reload matrix-synapse.service+sudo systemctl restart matrix-synapse.service
 </code> </code>
  
 ### Migrating from SQlite to PostgreSQL ### Migrating from SQlite to PostgreSQL
  
-There is no need for this if you have nothing done yet with synapse, otherwise, please refer to https://github.com/matrix-org/synapse/blob/master/docs/postgres.rst+Assuming you already followed step 6, there is no need for a migration. If you already used your Synapse and want to migrate, please refer to https://github.com/matrix-org/synapse/blob/master/docs/postgres.md
  
 ### Step 7 - Setup UFW Firewall ### Step 7 - Setup UFW Firewall
  
-Open the needed ports for our services. We will only allow SSH, HTTP, HTTPS and 8448 (for federation) connection on the UFW firewall configuration. To add them to the UFW firewall configuration, run the following commands.+Open the needed ports for our services. We will only allow SSH, HTTP, and HTTPS connection on the UFW firewall configuration. To add them to the UFW firewall configuration, run the following commands.
  
     sudo ufw allow ssh     sudo ufw allow ssh
     sudo ufw allow http     sudo ufw allow http
     sudo ufw allow https     sudo ufw allow https
-    sudo ufw allow 8448 
  
 Now enable the UFW firewall service and then check the status. Now enable the UFW firewall service and then check the status.
Line 327: Line 317:
 At this stage, the Synapse homeserver installation and configuration is complete. And in this step, we need to add a new matrix user from the command line on the server. To create a new matrix user, run the command below. At this stage, the Synapse homeserver installation and configuration is complete. And in this step, we need to add a new matrix user from the command line on the server. To create a new matrix user, run the command below.
  
-    register_new_matrix_user -c homeserver.yaml http://localhost:8008+    register_new_matrix_user -c /etc/matrix-synapse/homeserver.yaml http://localhost:8008
  
 Now you need to input the user name, password, and decide whether the user will have the admin privileges or not. And we have created a new matrix user with admin privilege. Now you need to input the user name, password, and decide whether the user will have the admin privileges or not. And we have created a new matrix user with admin privilege.
  
-### Step 9 - Federation+### Step 9 - Testing
  
-You can test if federation is working using https://federationtester.matrix.org. If any of the checks show an error then federation won't workOther federation-testers include:+If you have used Element with the desktop application before you may not want to log out, so it is better to go to [[https://element.io/get-started]] and press "Launch Element Web". If you have used the web client before, download the Element desktop application, install it and open Element. With both you will get a login page. Type the matrix username and password that were created before, then choose the 'Custom server' option and type the domain name from your server ''homeserver.example'' in. Click the ''Sign In'' button and you will get to the Element Dashboard.
  
-  * https://fed.mau.dev/+The Synapse homeserver is up and running under the Nginx reverse proxy HTTPS connection, and the user is now logged in to the Synapse homeserver using the Element application.
  
-### Step 10 - Testing+If you need two instances of Element instead, you can start it with argument, refer to [[digital:software:riotim|Riot.im]].
  
-If you have used Riot with the desktop application before you may not want to log outso it is better to go to [[https://riot.im/app/]] and press "Launch now". If you have used the web client before, download the Riot desktop application, install it and open the Riot software. With both you will get the Matrix login page now. Type the matrix username and password, then choose the 'Custom serveroption and type the domain name from your server ''example.com'' in. Click the ''Sign In'' button and you will get to the Riot Dashboard. +For another way to test it, go to ''https://homeserver.example/_matrix/static/'' and you will be presented with a ''**It works! Synapse is running**'' screen or go to ''https://homeserver.example/_matrix/client/versions'' and the output should look like the following:
- +
-The Synapse homeserver is up and running under the Nginx reverse proxy HTTPS connection, and the user is now logged in to the Synapse homeserver using the Riot application. +
- +
-If you need two instances of riot instead, you can start it with argument, refer to [[digital:software:riotim|Riot.im]]. +
- +
-For another way to test it, go to ''https://example.com/_matrix/client/versions'' and the output should look like the following:+
  
 <code xml> <code xml>
Line 356: Line 340:
 3 "r0.3.0" 3 "r0.3.0"
 </code> </code>
 +
 +### Step 10 - Federation
 +
 +You can test if federation is working using https://federationtester.matrix.org. If any of the checks show an error then federation won't work. Other federation-testers include:
 +
 +  * https://fed.mau.dev/
  
 ## Explanations ## Explanations
Line 361: Line 351:
 ### Presence ### Presence
  
-Unfortunately presence is right now broken and generates a high load. It is possible to deactivate it, but the user avatars will be grey afterwards on the homeserver. To deactivate, open ''homeserver.yaml'' and add+Unfortunately presence is right now broken and generates a high load. Until this issue https://github.com/matrix-org/synapse/issues/3971 is resolved, i suggest in deactivating presence, but the user avatars will be grey afterwards on the homeserver. To deactivate, open
  
 <code>sudoedit /etc/matrix-synapse/homeserver.yaml</code> <code>sudoedit /etc/matrix-synapse/homeserver.yaml</code>
 +
 + and add
  
 ''%%use_presence%%: False'' ''%%use_presence%%: False''
Line 369: Line 361:
 ### Do i need a TURN-Server (ex. COTURN) ### Do i need a TURN-Server (ex. COTURN)
  
-It's only necessary when both parties are behind NAT. Otherwise 1-on-1 communication should work fine. Group-Calls via Riot will be handled with jitsi.riot.im and are not handled by the homeserver.+It's only necessary when both parties are behind NAT. Otherwise 1-on-1 communication should work fine. Group-Calls via Element will be handled with jitsi.element.io and are not handled by the homeserver.
  
 ### Port 8008 and 8448 ### Port 8008 and 8448
Line 415: Line 407:
  
 If your need help, get as much information as possible ([[#whats_my_version|Installed version]], ...) and join https://matrix.to/#/#synapse:matrix.org. If it worked before, try to remember what was changed. If your need help, get as much information as possible ([[#whats_my_version|Installed version]], ...) and join https://matrix.to/#/#synapse:matrix.org. If it worked before, try to remember what was changed.
 +
 +### Problems with sending pictures
 +
 +Open the ''%%nano nginx.conf%%'' file and find change ''%%client_max_body_size 1M;%%'' to 
 +
 +
 +<code>
 + http{
 +    ...
 +    client_max_body_size 50M;
 +    ...
 + }
 +</code>
 +
  
 ### Whats my version ### Whats my version
  
-  * https://example.com/_matrix/federation/v1/version+  * https://homeserver.example/_matrix/federation/v1/version
  
 ### Location of logs ### Location of logs
 +
 +Check matrix with ''%%journalctl -xe%%'' and ''%%systemctl status matrix-synapse%%''
 +
 +A good way to check the logs is ''%%tail -20 [PATH]%%''. ''tail'' will show the last lines of a file, with ''-20'' it is possible to see the last 20 lines.
 +
 +#### Matrix
  
 <code> <code>
-/etc/matrix-synapse/homeserver.log  
 /var/log/matrix-synapse/homeserver.log /var/log/matrix-synapse/homeserver.log
 +</code>
 +
 +#### Nginx
 +
 +<code>
 +/var/log/nginx/error.log
 +/var/log/nginx/application.log
 </code> </code>
  
Line 458: Line 476:
  
 For feedback about this guide or tips on how to improve it visit https://matrix.to/#/#synapseguide:matrix.org For feedback about this guide or tips on how to improve it visit https://matrix.to/#/#synapseguide:matrix.org
- 
-### ToDo 
- 
-  * More explanations (explain more, because open source documentation is famously sparse) 
-    * what nginx 
-    * reverse proxy 
-    * what is postgre and why is it preferred over sqlite