10 KiB

Raw Blame History

Matrix

Matrix is an open network for secure, decentralized communication.

Setup

The matrix server is a complex setup of servers and services. Please note that this configuration is a composition of Docker images. Therefore a shared docker-compose.yml file is used. This setup guide follows a modified version of the guide by matusnovak. Furthermore this guide will assume you already have a traefik v2.4 instance setup as described in the traefik docker image article.

DNS records

You will need to create some DNS entries in order for synapse to function correctly. Additionally you will need 2 subdomains (this guide will assume you use the domain example.com with the subdomains matrix and synapse).

Create the following DNS records:

example.com.        A      <ip of your server>
matrix.             A      <ip of your server>
synapse.            A      <ip of your server>
_matrix._tcp.matrix. <TTL> class SRV 1 10 443 synapse.example.com

Synapse

The docker-image used for the synapse matrix server can be found in the docker-image directory. Create the docker-compose.yml file at a location of your choice (this guide will assume and recommend the file lies in a directory called matrix) with the following contents:

version: "3.4"

services:
  synapse:
    image: "matrixdotorg/synapse:latest"
    restart: "unless-stopped"
    environment:
      SYNAPSE_CONFIG_DIR: "/data"
      SYNAPSE_CONFIG_PATH: "/data/homeserver.yaml"
      UID: "1000"
      GID: "1000"
      TZ: "Europe/London"
    volumes:
      - synapse:/data
    networks:
      - proxy
    labels:
      - "traefik.enable=true"
      - "traefik.http.services.synapse.loadbalancer.server.port=8008"
      - "traefik.http.routers.synapse.rule=Host(`synapse.example.com`)"
      - "traefik.http.routers.synapse.entrypoints=websecure"

networks:
  proxy:
    external: true

volumes:
  synapse:
    driver: local

Now manually create the synapse volume you referenced in this file by running: docker volume create matrix_synapse

After that you will need to create the basic configuration files for synapse by running:

docker run -it --rm \
    -v matrix_synapse:/data \
    -e SYNAPSE_SERVER_NAME=matrix.example.com \
    -e SYNAPSE_REPORT_STATS=no \
    -e UID=1000 \
    -e GID=1000 \
    matrixdotorg/synapse:latest generate

If you want to enable/disable registration go to the homeserver.yaml and add the following line either set to true or false: enable_registration: true.

Additionally create the following lines:

federation_ip_range_blacklist:
  - '127.0.0.0/8'
  - '10.0.0.0/8'
  - '172.16.0.0/12'
  - '192.168.0.0/16'
  - '100.64.0.0/10'
  - '169.254.0.0/16'
  - '::1/128'
  - 'fe80::/64'
  - 'fc00::/7'
retention:
  enabled: true

If you start the docker container with docker-compose up and navigate to https://synapse.example.com you should be redirected to https://synapse.example.com/_matrix/static where a success message should be given out. If this is not the case please check your configuration.

Create an admin user in the docker containers shell with the command: register_new_matrix_user -c /data/homeserver.yaml https://synapse.example.com

Finally shut down the container using docker-compose down to be able to keep following the guide (this applies to any following step).

Nginx

The docker-image used for the nginx instance can be found in the docker-image directory. For federation to work properly an nginx container is needed aswell. In the directory containing your docker-compose.yml create the file data/matrix/nginx/matrix.conf and fill in the following lines:

server {
  listen         80 default_server;
  server_name    matrix.example.com;

 # Traefik -> nginx -> synapse
 location /_matrix {
    proxy_pass http://synapse:8008;
    proxy_set_header X-Forwarded-For $remote_addr;
    client_max_body_size 128m;
  }

  location /.well-known/matrix/ {
    root /var/www/;
    default_type application/json;
    add_header Access-Control-Allow-Origin  *;
  }
}

Create the file data/matrix/nginx/www/.well-known/matrix/client and set the contents as follows:

{
  "m.homeserver": {
    "base_url": "https://matrix.example.com"
  }
}

Create the file data/matrix/nginx/www/.well-known/matrix/server and set the contents as follows:

{
  "m.server": "synapse.example.com:443"
}

After that add the following lines in the service section in your docker-compse.yml:

nginx:
    image: "nginx:latest"
    restart: "unless-stopped"
    volumes:
      - "./data/matrix/nginx/matrix.conf:/etc/nginx/conf.d/matrix.conf"
      - ./data/matrix/nginx/www:/var/www/
    networks:
      - proxy
    labels:
      - "traefik.enable=true"
      - "traefik.http.services.matrix.loadbalancer.server.port=80"
      - "traefik.http.routers.martix.rule=Host(`matrix.example.com`)"
      - "traefik.http.routers.matrix.entrypoints=websecure"

Now start the container again and navigate to https://matrix.example.com/.well-known/matrix/client which should give you back something like: "base_url": "https://matrix.example.com". If you navigate to https://matrix.example.com/.well-known/matrix/server you should see: "m.server": "synapse.example.com:443". If you navigate to https://matrix.example.com/_matrix/static/ you should see the same page as shown at https://synapse.example.com/_matrix/static/.

If that works you can try to visit https://federationtester.matrix.org/ to check if your federation is working properly. Your servername is matrix.example.com (do not include https://). You should see a green sign that indicates success.

If one of these does not work (but synapse works) your nginx configuration is not correctly set up.

Element web client

The docker-image used for the web client can be found in the docker-image directory. This section will add a self hosted Matrix web client in form of Element (which was previously called riot).

First you will need to create another DNS record:

chat.            A      <ip of your server>

In the directory containing your docker-compose.yml file create the file data/matrix/element/config.json with the contents as follows:

{
  "default_server_config": {
    "m.homeserver": {
      "base_url": "https://matrix.example.com",
      "server_name": "matrix.example.com"
    },
    "m.identity_server": {
      "base_url": "https://vector.im"
    }
  },
  "disable_custom_urls": false,
  "disable_guests": false,
  "disable_login_language_selector": false,
  "disable_3pid_login": false,
  "brand": "Element",
  "integrations_ui_url": "https://scalar.vector.im/",
  "integrations_rest_url": "https://scalar.vector.im/api",
  "integrations_widgets_urls": [
    "https://scalar.vector.im/_matrix/integrations/v1",
    "https://scalar.vector.im/api",
    "https://scalar-staging.vector.im/_matrix/integrations/v1",
    "https://scalar-staging.vector.im/api",
    "https://scalar-staging.riot.im/scalar/api"
  ],
  "bug_report_endpoint_url": "https://riot.im/bugreports/submit",
  "defaultCountryCode": "GB",
  "showLabsSettings": false,
  "features": {
    "feature_new_spinner": "labs",
    "feature_pinning": "labs",
    "feature_custom_status": "labs",
    "feature_custom_tags": "labs",
    "feature_state_counters": "labs"
  },
  "default_federate": true,
  "default_theme": "light",
  "roomDirectory": {
    "servers": [
      "matrix.org"
    ]
  },
  "welcomeUserId": "@riot-bot:matrix.org",
  "piwik": {
    "url": "https://piwik.riot.im/",
    "whitelistedHSUrls": [
      "https://matrix.org"
    ],
    "whitelistedISUrls": [
      "https://vector.im",
      "https://matrix.org"
    ],
    "siteId": 1
  },
  "enable_presence_by_hs_url": {
    "https://matrix.org": false,
    "https://matrix-client.matrix.org": false
  },
  "settingDefaults": {
    "breadcrumbs": true
  },
  "jitsi": {
    "preferredDomain": "jitsi.riot.im"
  }
}

After that add the following lines to your docker-compose.yml in the service section:

  element:
    image: vectorim/riot-web:latest
    restart: unless-stopped
    volumes:
        - "./data/matrix/element/config.json:/app/config.json:ro"
    networks:
      - proxy
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.element-secure.entrypoints=websecure"
      - "traefik.http.routers.element-secure.rule=Host(`chat.example.com`)"
      - "traefik.http.routers.element-secure.service=element"
      - "traefik.http.services.element.loadbalancer.server.port=80"

Add the following line to the homeserver.yaml of the synapse server to indicate your element domain: web_client_location: https://chat.example.com.

Start the container. You should now be able to navigate to https://chat.example.com where you are prompted with a log in window. If you already created an account you should be able to log in. If any of that is not working there is something wrong with your configuration.

Administration interface

The docker-image used for the administration interface can be found in the docker-image directory. This section will add a self hosted Matrix administration interface. This is especially useful if you have enable_registration set to false because you can dynamically create and administrate users and rooms.