finallycoffee/matrix-docker-ansible-deploy
5
1
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Initial work on Synapse 0.99/1.0 preparation

Browse Source
This commit is contained in:
Slavi Pantaleev
2019-02-05 11:07:08 +02:00
parent e06e5dd208
commit f6ebd4ce62
19 changed files with 416 additions and 130 deletions
Download Patch File Download Diff File Expand all files Collapse all files

48
docs/configuring-dns.md
View File

@ -5,26 +5,50 @@ To set up Matrix on your domain, you'd need to do some DNS configuration.
To use an identifier like `@<username>:<your-domain>`, you don't actually need
to install anything on the actual `<your-domain>` server.
## General outline of DNS settings you need to do
| Type | Host | Priority | Weight | Port | Target |
| ----- | ----------------------- | -------- | ------ | ---- | ---------------------- |
| A | `matrix` | - | - | - | `matrix-server-IP` |
| CNAME | `riot` | - | - | - | `matrix.<your-domain>` |
| SRV | `_matrix._tcp` | 10 | 0 | 8448 | `matrix.<your-domain>` |
| SRV | `_matrix-identity._tcp` | 10 | 0 | 443 | `matrix.<your-domain>` |
The `_matrix._tcp` SRV record is a temporary measure and will not be necessary in the near future.
In fact, it will have to be removed at some point. To learn more about that, read below.
## Subdomains setup
As the table above illustrates, you need to create 2 subdomains (`matrix.<your-domain>` and `riot.<your-domain>`) and point both of them to your new server's IP address (DNS `A` record or `CNAME` record is fine).
The `riot.<your-domain>` subdomain is necessary, because this playbook installs the Riot web client for you.
If you'd rather instruct the playbook not to install Riot (`matrix_riot_web_enabled: false` when [Configuring the playbook](configuring-playbook.md) later), feel free to skip the `riot.<your-domain>` DNS record.
## `_matrix._tcp` SRV record setup (temporary requirement)
All services created by this playbook are meant to be installed on their own server (such as `matrix.<your-domain>`).
To accomplish such a "redirect", you need to instruct the Matrix network of this by setting up a DNS SRV record.
To use a Matrix user identifier like `@<username>:<your-domain>` while hosting services on `matrix.<your-domain>`, we need to instruct the Matrix network of such a delegation/redirection by means of setting up a DNS SRV record.
The SRV record should look like this:
- Name: `_matrix._tcp` (use this text as-is)
- Content: `10 0 8448 matrix.<your-domain>` (replace `<your-domain>` with your own)
A [new file-based mechanism for Federation Server Discovery](configuring-well-known.md#introduction-to-federation-server-discovery) is superseding the `_matrix._tcp` SRV record. **During the transition phase, you'll need to set up both mechanisms**. We'll instruct you how to set up the file-based mechanism after the [installation phase](installing.md) for this playbook.
Doing delegation/redirection of Matrix services using a DNS SRV record (`_matrix._tcp`) is a **temporary measure** that is only necessary before Synapse v1.0 is released.
As more and more people upgrade to the Synapse v0.99 transitional release and just before the final Synapse v1.0 gets released, at some point in the near future **you will need to remove the `_matrix._tcp` SRV record** and leave only the [new file-based mechanism for Federation Server Discovery](configuring-well-known.md#introduction-to-federation-server-discovery) in place.
## `_matrix-identity._tcp` SRV record setup
To make the [mxisd](https://github.com/kamax-io/mxisd) Identity Server (which this playbook installs for you) be authoritative for your domain name, set up one more SRV record that looks like this:
- Name: `_matrix-identity._tcp` (use this text as-is)
- Content: `10 0 443 matrix.<your-domain>` (replace `<your-domain>` with your own)
Once you've set up these DNS SRV records, you should create 2 other domain names (`matrix.<your-domain>` and `riot.<your-domain>`) and point both of them to your new server's IP address (DNS `A` record or `CNAME` is fine).
This playbook can then install all the services on that new server and you'll be able to join the Matrix network as `@<username>:<your-domain>`.
| Type | Host | Priority | Weight | Port | Target |
| ----- | ----------------------- | -------- | ------ | ---- | ---------------------- |
| SRV | `_matrix._tcp` | 10 | 0 | 8448 | `matrix.<your-domain>` |
| SRV | `_matrix-identity._tcp` | 10 | 0 | 443 | `matrix.<your-domain>` |
| A | `matrix` | - | - | - | `server-IP` |
| CNAME | `riot` | - | - | - | `matrix.<your-domain>` |
When ready to proceed, continue with [Configuring this Ansible playbook](configuring-playbook.md).
When you're done with the DNS configuration and ready to proceed, continue with [Configuring this Ansible playbook](configuring-playbook.md).

2
docs/configuring-playbook.md
View File

@ -1,6 +1,6 @@
# Configuring the Ansible playbook
Once you have your server and you have [configured your DNS records](configuring-dns.md#configuring-dns), you can proceed with configuring this playbook, so that it knows what to install and where.
Once you have your server and you have [configured your DNS records](configuring-dns.md), you can proceed with configuring this playbook, so that it knows what to install and where.
You can follow these steps:

61
docs/configuring-well-known.md
View File

@ -1,44 +1,66 @@
# Configuring service discovery via .well-known
# Configuring Service Discovery via .well-known
Service discovery is a way for the Matrix network to discover where a Matrix server is.
There are 2 types of well-known service discovery that Matrix makes use of:
- (important) **Federation Server discovery** (`/.well-known/matrix/server`) -- assists other servers in the Matrix network with finding your server. Without a proper configuration, your server will effectively not be part of the Matrix network. Learn more in [Introduction to Federation Server Discovery](#introduction-to-federation-server-discovery)
- (not that important) **Client Server discovery** (`/.well-known/matrix/client`) -- assists programs that you use to connect to your server (e.g. Riot), so that they can make it more convenient for you by automatically configuring the "Homeserver URL" and "Identity Server URL" addresses. Learn more in [Introduction to Client Server Discovery](#introduction-to-client-server-discovery)
## Introduction
## Introduction to Federation Server Discovery
Service discovery lets various client programs which support it, to receive a full user id (e.g. `@username:example.com`) and determine where the Matrix server is automatically (e.g. `https://matrix.example.com`).
All services created by this playbook are meant to be installed on their own server (such as `matrix.<your-domain>`).
This lets your users easily connect to your Matrix server without having to customize connection URLs.
As [per the Server-Server specification](https://matrix.org/docs/spec/server_server/r0.1.0.html#server-discovery), to use a Matrix user identifier like `@<username>:<your-domain>` while hosting services on a subdomain like `matrix.<your-domain>`, we need to instruct the Matrix network of such a delegation/redirection by means of setting up a `/.well-known/matrix/server` file on the base domain (`<your-domain.com>).
As [per the specification](https://matrix.org/docs/spec/client_server/r0.4.0.html#server-discovery) Matrix does service discovery using a `/.well-known/matrix/client` file hosted on the base domain (e.g. `example.com`).
We have discussed this same thing already in the "`_matrix._tcp` SRV record setup (temporary requirement)" section of [Configuring DNS](configuring-dns.md).
In short, you are required to set up both a `_matrix._tcp` DNS SRV record and the `/.well-known/matrix/server` file at the moment.
As the Synapse server progresses towards v1.0, only the `/.well-known/matrix/server` file will be used. At that future moment, you would need to remove the `_matrix._tcp` SRV record because Synapse v1.0+ will do the wrong thing if a SRV record exists. During the transitional phase (before Synapse 1.0), we do need to have both a SRV record and a `/.well-known/matrix/server` file, in order to federate correctly with v0.99 and older Synapse versions.
To learn how to set it up, read the Installing section below.
## Introduction to Client Server Discovery
Client Server Service discovery lets various client programs which support it, to receive a full user id (e.g. `@username:example.com`) and determine where the Matrix server is automatically (e.g. `https://matrix.example.com`).
This lets you (and your users) easily connect to your Matrix server without having to customize connection URLs. When using client programs that support it, you won't need to point them to `https://matrix.example.com` in Custom Server options manually anymore. The connection URL would be discovered automatically from your full username.
As [per the Client-Server specification](https://matrix.org/docs/spec/client_server/r0.4.0.html#server-discovery) Matrix does Client Server service discovery using a `/.well-known/matrix/client` file hosted on the base domain (e.g. `example.com`).
However, this playbook installs your Matrix server on another domain (e.g. `matrix.example.com`) and not on the base domain (e.g. `example.com`), so it takes a little extra manual effort to set up the file.
## Prerequisites
To implement service discovery, your base domain's server (e.g. `example.com`) needs to support HTTPS.
To learn how to set it up, read the Installing section below.
## Setting it up
## Installing well-known files on the base domain's server
To make things easy for you to set up, this playbook generates and hosts the well-known file on the Matrix domain's server (e.g. `https://matrix.example.com/.well-known/matrix/client`), even though this is the wrong place to host it.
To implement the two service discovery mechanisms, your base domain's server (e.g. `example.com`) needs to support HTTPS.
You have 2 options when it comes to installing the file on the base domain's server:
To make things easy for you to set up, this playbook generates and hosts 2 well-known files on the Matrix domain's server (e.g. `https://matrix.example.com/.well-known/matrix/server` and `https://matrix.example.com/.well-known/matrix/client`), even though this is the wrong place to host them.
You have 2 options when it comes to installing the files on the base domain's server:
### (Option 1): **Copying the file manually** to your base domain's server
### (Option 1): **Copying the files manually** to your base domain's server
**Hint**: Option 2 (below) is generally a better way to do this. Make sure to go with that one, if possible.
All you need to do is:
- copy the `/.well-known/matrix/client` from the Matrix server (e.g. `matrix.example.com`) to your base domain's server (`example.com`).
- copy `/.well-known/matrix/server` and `/.well-known/matrix/client` from the Matrix server (e.g. `matrix.example.com`) to your base domain's server (`example.com`).
- set up the server at your base domain (e.g. `example.com`) so that it adds an extra HTTP header when serving the `/.well-known/matrix/client` file. [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS), the `Access-Control-Allow-Origin` header should be set with a value of `*`. If you don't do this step, web-based Matrix clients (like Riot) may fail to work.
- set up the server at your base domain (e.g. `example.com`) so that it adds an extra HTTP header when serving the `/.well-known/matrix/client` file. [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS), the `Access-Control-Allow-Origin` header should be set with a value of `*`. If you don't do this step, web-based Matrix clients (like Riot) may fail to work. Setting up headers for the `/.well-known/matrix/server` file is not necessary, as this file is only consumed by non-browsers, which don't care about CORS.
This is relatively easy to do and possibly your only choice if you can only host static files from the base domain's server.
It is, however, **a little fragile**, as future updates performed by this playbook may regenerate the well-known file and you may need to notice that and copy it again.
It is, however, **a little fragile**, as future updates performed by this playbook may regenerate the well-known files and you may need to notice that and copy them over again.
### (Option 2): **Setting up reverse-proxying** of the well-known file from the base domain's server to the Matrix server
### (Option 2): **Setting up reverse-proxying** of the well-known files from the base domain's server to the Matrix server
This option is less fragile and generally better.
@ -91,6 +113,9 @@ Make sure to:
## Confirming it works
No matter which method you've used to set up the well-known file, if you've done it correctly you should be able to see a JSON file at a URL like this: `https://<domain>/.well-known/matrix/client`.
No matter which method you've used to set up the well-known files, if you've done it correctly you should be able to see a JSON file at both of these URLs:
- `https://<domain>/.well-known/matrix/server`
- `https://<domain>/.well-known/matrix/client`
You can also check if everything is configured correctly, by [checking if services work](maintenance-checking-services.md).

6
docs/installing.md
View File

@ -34,7 +34,7 @@ ansible-playbook -i inventory/hosts setup.yml --tags=start
Now that the services are running, you might want to:
- [create your first user account](registering-users.md)
- or **finalize the installation process** by [Configuring service discovery via .well-known](configuring-well-known.md)
- or [Check if services work](maintenance-checking-services.md)
- **finalize the installation process** (required for federation to work!) by [Configuring Service Discovery via .well-known](configuring-well-known.md)
- or [create your first user account](registering-users.md)
- or [check if services work](maintenance-checking-services.md)
- or learn how to [upgrade your services when new versions are released](maintenance-upgrading-services.md)

8
docs/prerequisites.md
View File

@ -6,12 +6,10 @@
- the [Ansible](http://ansible.com/) program being installed on your own computer. It's used to run this playbook and configures your server for you. Take a look at [our guide about Ansible](ansible.md) for version requirements or alternative ways to run Ansible.
- properly configured DNS SRV record for `<your-domain>` (details in [Configuring DNS](configuring-dns.md#configuring-dns) below)
- an HTTPS-capable web server at the base domain name (`<your-domain>`) which is capable of serving static files
- `matrix.<your-domain>` domain name pointing to your new server - this is where the Matrix Synapse server will live (details in [Configuring DNS](configuring-dns.md#configuring-dns) below)
- `riot.<your-domain>` domain name pointing to your new server - this is where the Riot web UI will live (details in [Configuring DNS](configuring-dns.md#configuring-dns) below)
- properly configured DNS records for `<your-domain>` (details in [Configuring DNS](configuring-dns.md))
- some TCP/UDP ports open. This playbook configures the server's internal firewall for you. In most cases, you don't need to do anything special. But **if your server is running behind another firewall**, you'd need to open these ports: `80/tcp` (HTTP webserver), `443/tcp` (HTTPS webserver), `3478/tcp` (STUN over TCP), `3478/udp` (STUN over UDP), `8448/tcp` (Matrix federation HTTPS webserver), `49152-49172/udp` (TURN over UDP).
When ready to proceed, continue with [Configuring DNS](configuring-dns.md).
When ready to proceed, continue with [Configuring DNS](configuring-dns.md).