From 0d0ccde286ac395d58c4457d724de76722d103e0 Mon Sep 17 00:00:00 2001 From: Slavi Pantaleev Date: Mon, 17 Sep 2018 10:51:46 +0300 Subject: [PATCH] Add Service Discovery (/.well-known/matrix/client) support --- CHANGELOG.md | 7 ++ docs/README.md | 2 + docs/configuring-playbook-own-webserver.md | 6 +- docs/configuring-well-known.md | 78 +++++++++++++++++++ docs/installing.md | 9 ++- docs/registering-users.md | 8 +- roles/matrix-server/defaults/main.yml | 1 + roles/matrix-server/tasks/main.yml | 8 ++ .../matrix-server/tasks/setup_well_known.yml | 24 ++++++ .../nginx-conf.d/matrix-synapse.conf.j2 | 6 ++ .../systemd/matrix-nginx-proxy.service.j2 | 1 + .../templates/well-known/matrix-client.j2 | 8 ++ 12 files changed, 153 insertions(+), 5 deletions(-) create mode 100644 docs/configuring-well-known.md create mode 100644 roles/matrix-server/tasks/setup_well_known.yml create mode 100644 roles/matrix-server/templates/well-known/matrix-client.j2 diff --git a/CHANGELOG.md b/CHANGELOG.md index 0d6a622e..a688911e 100644 --- a/CHANGELOG.md +++ b/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: diff --git a/docs/README.md b/docs/README.md index 621644b5..e56affaf 100644 --- a/docs/README.md +++ b/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) diff --git a/docs/configuring-playbook-own-webserver.md b/docs/configuring-playbook-own-webserver.md index 112e8918..437cba69 100644 --- a/docs/configuring-playbook-own-webserver.md +++ b/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./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./vars.yml`): ``` matrix_nginx_proxy_enabled: false diff --git a/docs/configuring-well-known.md b/docs/configuring-well-known.md new file mode 100644 index 00000000..62adcf51 --- /dev/null +++ b/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 + + ServerName DOMAIN + + SSLProxyEngine on + + ProxyPass "https://matrix.DOMAIN/.well-known/matrix" + + + # other configuration + +``` + +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./.well-known/matrix/client`. \ No newline at end of file diff --git a/docs/installing.md b/docs/installing.md index b8e4ac08..74434722 100644 --- a/docs/installing.md +++ b/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) \ No newline at end of file diff --git a/docs/registering-users.md b/docs/registering-users.md index 99105285..b934a55a 100644 --- a/docs/registering-users.md +++ b/docs/registering-users.md @@ -10,4 +10,10 @@ You can do it via this Ansible playbook (make sure to edit the `` /usr/local/bin/matrix-synapse-register-user -**Note**: `` is just a plain username (like `john`), not your full `@:` identifier. \ No newline at end of file +**Note**: `` is just a plain username (like `john`), not your full `@:` 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./`. + +----- + +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) \ No newline at end of file diff --git a/roles/matrix-server/defaults/main.yml b/roles/matrix-server/defaults/main.yml index dc4371e2..7a8559a6 100644 --- a/roles/matrix-server/defaults/main.yml +++ b/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" diff --git a/roles/matrix-server/tasks/main.yml b/roles/matrix-server/tasks/main.yml index 01f5832b..36346512 100644 --- a/roles/matrix-server/tasks/main.yml +++ b/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: diff --git a/roles/matrix-server/tasks/setup_well_known.yml b/roles/matrix-server/tasks/setup_well_known.yml new file mode 100644 index 00000000..d6c4eebd --- /dev/null +++ b/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 }}" \ No newline at end of file diff --git a/roles/matrix-server/templates/nginx-conf.d/matrix-synapse.conf.j2 b/roles/matrix-server/templates/nginx-conf.d/matrix-synapse.conf.j2 index f7ff6255..c5b537ec 100644 --- a/roles/matrix-server/templates/nginx-conf.d/matrix-synapse.conf.j2 +++ b/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 %} diff --git a/roles/matrix-server/templates/systemd/matrix-nginx-proxy.service.j2 b/roles/matrix-server/templates/systemd/matrix-nginx-proxy.service.j2 index 82a7bedf..ef5067f6 100644 --- a/roles/matrix-server/templates/systemd/matrix-nginx-proxy.service.j2 +++ b/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 diff --git a/roles/matrix-server/templates/well-known/matrix-client.j2 b/roles/matrix-server/templates/well-known/matrix-client.j2 new file mode 100644 index 00000000..e3b0d767 --- /dev/null +++ b/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 }}" + } +}