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

CHANGELOG.md

@@ -1,5 +1,12 @@
 # 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
 
 The following playbook variables were renamed:

docs/README.md

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

docs/configuring-playbook-own-webserver.md

@@ -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,
 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

docs/configuring-well-known.md

@@ -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`.

docs/installing.md

@@ -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.
 
 
-# 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:
 
@@ -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)
 
 
-# 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):
 
@@ -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
 ```
 
-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)

docs/registering-users.md

@@ -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>
 
-**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)

roles/matrix-server/defaults/main.yml

@@ -116,6 +116,7 @@ matrix_coturn_base_path: "{{ matrix_base_data_path }}/coturn"
 matrix_coturn_config_path: "{{ matrix_coturn_base_path }}/turnserver.conf"
 matrix_scratchpad_dir: "{{ matrix_base_data_path }}/scratchpad"
 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_v10: "postgres:10.5-alpine"

roles/matrix-server/tasks/main.yml

@@ -58,10 +58,18 @@
     - setup-all
     - 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
   tags:
     - setup-all
     - setup-nginx-proxy
+    - setup-well-known
 
 - include: tasks/start.yml
   tags:

roles/matrix-server/tasks/setup_well_known.yml

@@ -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 }}"

roles/matrix-server/templates/nginx-conf.d/matrix-synapse.conf.j2

@@ -39,6 +39,12 @@ server {
 	ssl_prefer_server_ciphers on;
 	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 %}
 	location /_matrix/corporal {
 		{% if matrix_nginx_proxy_enabled %}

roles/matrix-server/templates/systemd/matrix-nginx-proxy.service.j2

@@ -23,6 +23,7 @@ ExecStart=/usr/bin/docker run --rm --name matrix-nginx-proxy \
 			-p 443:443 \
 			-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_static_files_base_path }}:{{ matrix_static_files_base_path }}:ro \
 			{{ matrix_docker_image_nginx }}
 ExecStop=-/usr/bin/docker kill matrix-nginx-proxy
 ExecStop=-/usr/bin/docker rm matrix-nginx-proxy

roles/matrix-server/templates/well-known/matrix-client.j2

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