Add Service Discovery (/.well-known/matrix/client) support

This commit is contained in:
Slavi Pantaleev 2018-09-17 10:51:46 +03:00
parent 38e3ffa29c
commit 0d0ccde286
12 changed files with 153 additions and 5 deletions

View File

@ -1,5 +1,12 @@
# 2018-09-17 # 2018-09-17
## Service discovery support
The playbook now helps you set up [service discovery](https://matrix.org/docs/spec/client_server/r0.4.0.html#server-discovery) using a `/.well-known/matrix/client` file.
Additional details are available in [Configuring service discovery via .well-known](docs/configuring-well-known.md).
## (BC Break) Renaming playbook variables ## (BC Break) Renaming playbook variables
The following playbook variables were renamed: The following playbook variables were renamed:

View File

@ -10,6 +10,8 @@
- [Registering users](registering-users.md) - [Registering users](registering-users.md)
- [Configuring service discovery via .well-known](configuring-well-known.md)
- [Maintenance / upgrading services](maintenance-upgrading-services.md) - [Maintenance / upgrading services](maintenance-upgrading-services.md)
- [Maintenance / upgrading PostgreSQL](maintenance-upgrading-postgres.md) - [Maintenance / upgrading PostgreSQL](maintenance-upgrading-postgres.md)

View File

@ -6,7 +6,11 @@ If that's alright, you can skip this.
If you don't want this playbook's nginx webserver to take over your server's 80/443 ports like that, If you don't want this playbook's nginx webserver to take over your server's 80/443 ports like that,
and you'd like to use your own webserver (be it nginx, Apache, Varnish Cache, etc.), you can. and you'd like to use your own webserver (be it nginx, Apache, Varnish Cache, etc.), you can.
All it takes is editing your configuration file (`inventory/matrix.<your-domain>/vars.yml`): All it takes is:
1) making sure your web server user (something like `http`, `apache`, `www-data`, `nginx`) is part of the `matrix` group. You should run something like this: `usermod -a -G matrix nginx`
2) editing your configuration file (`inventory/matrix.<your-domain>/vars.yml`):
``` ```
matrix_nginx_proxy_enabled: false matrix_nginx_proxy_enabled: false

View File

@ -0,0 +1,78 @@
# Configuring service discovery via .well-known
## Introduction
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 your users easily connect to your Matrix server without having to customize connection URLs.
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`).
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.
## Setting it up
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.
You have 2 options when it comes to installing the file on the base domain's server:
1) (Option 1): **Copying the file manually** to your base domain's server
All it takes is copying the `/.well-known/matrix/client` from the Matrix server (e.g. `matrix.example.com`) to your base domain's server (`example.com`).
This is 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.
2) (Option 2): **Setting up reverse-proxying** of the well-known file from the base domain's server to the Matrix server.
This option is less fragile and generally better.
On the base domain's server (e.g. `example.com`), you can set up reverse-proxying, so that any access for the `/.well-known/matrix` location prefix is forwarded to the Matrix domain's server (e.g. `matrix.example.com`).
**For nginx**, it would be something like this:
```nginx
# This is your HTTPS-enabled server for DOMAIN.
server {
server_name DOMAIN;
location /.well-known/matrix {
proxy_pass https://matrix.DOMAIN/.well-known/matrix;
proxy_set_header X-Forwarded-For $remote_addr;
}
# other configuration
}
```
**For Apache**, it would be something like this:
```apache
<VirtualHost *:443>
ServerName DOMAIN
SSLProxyEngine on
<Location /.well-known/matrix>
ProxyPass "https://matrix.DOMAIN/.well-known/matrix"
</Location>
# other configuration
</VirtualHost>
```
Make sure to:
- **replace `DOMAIN`** in the server configuration with your actual domain name
- and: to **do this for the HTTPS-enabled server block**, as that's where Matrix expects the file to be
## 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://matrix.<domain>/.well-known/matrix/client`.

View File

@ -13,7 +13,7 @@ This **doesn't start any services just yet** (another step does this later - bel
Feel free to **re-run this any time** you think something is off with the server configuration. Feel free to **re-run this any time** you think something is off with the server configuration.
# Things you might want to do after installing ## Things you might want to do after installing
After installing, but before starting the services, you may want to do additional things like: After installing, but before starting the services, you may want to do additional things like:
@ -22,7 +22,7 @@ After installing, but before starting the services, you may want to do additiona
- [Restoring `media_store` data files from an existing installation](restoring-media-store.md) (optional) - [Restoring `media_store` data files from an existing installation](restoring-media-store.md) (optional)
# Starting the services ## Starting the services
When you're ready to start the Matrix services (and set them up to auto-start in the future): When you're ready to start the Matrix services (and set them up to auto-start in the future):
@ -30,4 +30,7 @@ When you're ready to start the Matrix services (and set them up to auto-start in
ansible-playbook -i inventory/hosts setup.yml --tags=start 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) 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)

View File

@ -10,4 +10,10 @@ You can do it via this Ansible playbook (make sure to edit the `<your-username>`
/usr/local/bin/matrix-synapse-register-user <your-username> <your-password> <admin access: 0 or 1> /usr/local/bin/matrix-synapse-register-user <your-username> <your-password> <admin access: 0 or 1>
**Note**: `<your-username>` is just a plain username (like `john`), not your full `@<username>:<your-domain>` identifier. **Note**: `<your-username>` is just a plain username (like `john`), not your full `@<username>:<your-domain>` identifier.
**You can then log in with that user** via the riot-web service that this playbook has created for you at a URL like this: `https://riot.<domain>/`.
-----
If you've just installed Matrix, **to finalize the installation process**, it's best if you proceed to [Configuring service discovery via .well-known](configuring-well-known.md)

View File

@ -116,6 +116,7 @@ matrix_coturn_base_path: "{{ matrix_base_data_path }}/coturn"
matrix_coturn_config_path: "{{ matrix_coturn_base_path }}/turnserver.conf" matrix_coturn_config_path: "{{ matrix_coturn_base_path }}/turnserver.conf"
matrix_scratchpad_dir: "{{ matrix_base_data_path }}/scratchpad" matrix_scratchpad_dir: "{{ matrix_base_data_path }}/scratchpad"
matrix_mautrix_telegram_base_path: "{{ matrix_base_data_path }}/mautrix-telegram" matrix_mautrix_telegram_base_path: "{{ matrix_base_data_path }}/mautrix-telegram"
matrix_static_files_base_path: "{{ matrix_base_data_path }}/static-files"
matrix_docker_image_postgres_v9: "postgres:9.6.10-alpine" matrix_docker_image_postgres_v9: "postgres:9.6.10-alpine"
matrix_docker_image_postgres_v10: "postgres:10.5-alpine" matrix_docker_image_postgres_v10: "postgres:10.5-alpine"

View File

@ -58,10 +58,18 @@
- setup-all - setup-all
- setup-riot-web - setup-riot-web
- include: tasks/setup_well_known.yml
tags:
- setup-mxisd
- setup-synapse
- setup-nginx-proxy
- setup-well-known
- include: tasks/setup_nginx_proxy.yml - include: tasks/setup_nginx_proxy.yml
tags: tags:
- setup-all - setup-all
- setup-nginx-proxy - setup-nginx-proxy
- setup-well-known
- include: tasks/start.yml - include: tasks/start.yml
tags: tags:

View File

@ -0,0 +1,24 @@
- set_fact:
matrix_well_known_file_path: "{{ matrix_static_files_base_path }}/.well-known/matrix/client"
# We need others to be able to read these directories too,
# so that matrix-nginx-proxy's nginx user can access the files.
#
# For running with another webserver, we recommend being part of the `matrix` group.
- name: Ensure Matrix static-files path exists
file:
path: "{{ item }}"
state: directory
mode: 0755
owner: "{{ matrix_user_username }}"
group: "{{ matrix_user_username }}"
with_items:
- "{{ matrix_well_known_file_path|dirname }}"
- name: Ensure Matrix /.well-known/matrix/client configured
template:
src: "{{ role_path }}/templates/well-known/matrix-client.j2"
dest: "{{ matrix_well_known_file_path }}"
mode: 0644
owner: "{{ matrix_user_username }}"
group: "{{ matrix_user_username }}"

View File

@ -39,6 +39,12 @@ server {
ssl_prefer_server_ciphers on; ssl_prefer_server_ciphers on;
ssl_ciphers "EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH"; ssl_ciphers "EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH";
location /.well-known/matrix/client {
root {{ matrix_static_files_base_path }};
expires 1m;
default_type application/json;
}
{% if matrix_corporal_enabled and matrix_corporal_http_api_enabled %} {% if matrix_corporal_enabled and matrix_corporal_http_api_enabled %}
location /_matrix/corporal { location /_matrix/corporal {
{% if matrix_nginx_proxy_enabled %} {% if matrix_nginx_proxy_enabled %}

View File

@ -23,6 +23,7 @@ ExecStart=/usr/bin/docker run --rm --name matrix-nginx-proxy \
-p 443:443 \ -p 443:443 \
-v {{ matrix_nginx_proxy_confd_path }}:/etc/nginx/conf.d:ro \ -v {{ matrix_nginx_proxy_confd_path }}:/etc/nginx/conf.d:ro \
-v {{ matrix_ssl_config_dir_path }}:{{ matrix_ssl_config_dir_path }}:ro \ -v {{ matrix_ssl_config_dir_path }}:{{ matrix_ssl_config_dir_path }}:ro \
-v {{ matrix_static_files_base_path }}:{{ matrix_static_files_base_path }}:ro \
{{ matrix_docker_image_nginx }} {{ matrix_docker_image_nginx }}
ExecStop=-/usr/bin/docker kill matrix-nginx-proxy ExecStop=-/usr/bin/docker kill matrix-nginx-proxy
ExecStop=-/usr/bin/docker rm matrix-nginx-proxy ExecStop=-/usr/bin/docker rm matrix-nginx-proxy

View File

@ -0,0 +1,8 @@
{
"m.homeserver": {
"base_url": "{{ matrix_homeserver_url }}"
},
"m.identity_server": {
"base_url": "{{ matrix_identity_server_url }}"
}
}