diff --git a/docs/configuring-well-known.md b/docs/configuring-well-known.md index 36e53996b..d52bef73f 100644 --- a/docs/configuring-well-known.md +++ b/docs/configuring-well-known.md @@ -36,6 +36,33 @@ However, this playbook installs your Matrix server on another domain (e.g. `matr To learn how to set it up, read the Installing section below. +## (Optional) Introduction to Homeserver Admin Contact and Support page + +[MSC 1929](https://github.com/matrix-org/matrix-spec-proposals/pull/1929) specifies a way to add contact details of admins, as well as a link to a support page for users who are having issues with the service. + +This MSC did not get accepted yet, but we think it might already be useful to Homeserver admins who wish to provide this information to end-users. + +The two playbook variables that you could look for, if you're interested in being an early adopter, are: `matrix_homeserver_admin_contacts` and `matrix_homeserver_support_url`. + +Example snippet for `vars.yml`: +``` +# Homeserver admin contacts as per MSC 1929 https://github.com/matrix-org/matrix-spec-proposals/pull/1929 +matrix_homeserver_admin_contacts: + - matrix_id: @admin1:domain.tld + email_address: admin@domain.tld + role: admin + - matrix_id: @admin2:domain.tld + email_address: admin@domain.tld + role: admin + - email_address: security@domain.tld + role: security + +matrix_homeserver_support_url: "https://example.domain.tld/support" +``` + +To learn how to set up `/.well-known/matrix/support` for the base domain, read the Installing section below. + + ## Installing well-known files on the base domain's server To implement the two service discovery mechanisms, your base domain's server (e.g. `example.com`) needs to run an HTTPS-capable webserver. @@ -185,5 +212,6 @@ No matter which method you've used to set up the well-known files, if you've don - `https:///.well-known/matrix/server` - `https:///.well-known/matrix/client` +- `https:///.well-known/matrix/support` You can also check if everything is configured correctly, by [checking if services work](maintenance-checking-services.md). diff --git a/roles/matrix-base/defaults/main.yml b/roles/matrix-base/defaults/main.yml index 9b6d45f84..b8bea562a 100644 --- a/roles/matrix-base/defaults/main.yml +++ b/roles/matrix-base/defaults/main.yml @@ -12,6 +12,19 @@ matrix_domain: ~ # Example value: "@someone:{{ matrix_domain }}" matrix_admin: '' +# Homeserver admin contacts and support page as per MSC 1929 +# See: https://github.com/matrix-org/matrix-spec-proposals/pull/1929 +# Users in form: +# matrix_homeserver_admin_contacts: +# - matrix_id: @admin:domain.tld +# email_address: admin@domain.tld +# role: admin +# - email_address: security@domain.tld +# role: security +matrix_homeserver_admin_contacts: [] +# Url string like https://domain.tld/support.html +matrix_homeserver_support_url: '' + # This will contain the homeserver implementation that is in use. # Valid values: synapse, dendrite # @@ -225,6 +238,18 @@ matrix_well_known_matrix_server_configuration_extension: "{{ matrix_well_known_m # You most likely don't need to touch this variable. Instead, see `matrix_well_known_matrix_server_configuration_default` and `matrix_well_known_matrix_server_configuration_extension_json`. matrix_well_known_matrix_server_configuration: "{{ matrix_well_known_matrix_server_configuration_default|combine(matrix_well_known_matrix_server_configuration_extension, recursive=True) }}" +# The side-effect of this lookup is that Ansible would even parse the JSON for us, returning a dict. +# This is unlike what it does when looking up YAML template files (no automatic parsing there). +matrix_well_known_matrix_support_configuration_default: "{{ lookup('template', 'templates/static-files/well-known/matrix-support.j2') }}" + +matrix_well_known_matrix_support_configuration_extension_json: '{}' + +matrix_well_known_matrix_support_configuration_extension: "{{ matrix_well_known_matrix_support_configuration_extension_json|from_json if matrix_well_known_matrix_support_configuration_extension_json|from_json is mapping else {} }}" + +# Holds the final `/.well-known/matrix/support` configuration (a combination of the default and its extension). +# You most likely don't need to touch this variable. Instead, see `matrix_well_known_matrix_support_configuration_default` and `matrix_well_known_matrix_support_configuration_extension_json`. +matrix_well_known_matrix_support_configuration: "{{ matrix_well_known_matrix_support_configuration_default|combine(matrix_well_known_matrix_support_configuration_extension, recursive=True) }}" + # The Docker network that all services would be put into matrix_docker_network: "matrix" diff --git a/roles/matrix-base/tasks/setup_well_known.yml b/roles/matrix-base/tasks/setup_well_known.yml index 3f475950b..44ef3d28a 100644 --- a/roles/matrix-base/tasks/setup_well_known.yml +++ b/roles/matrix-base/tasks/setup_well_known.yml @@ -35,3 +35,11 @@ path: "{{ matrix_static_files_base_path }}/.well-known/matrix/server" state: absent when: "not matrix_well_known_matrix_server_enabled|bool" + +- name: Ensure Matrix /.well-known/matrix/support file configured + copy: + content: "{{ matrix_well_known_matrix_support_configuration|to_nice_json }}" + dest: "{{ matrix_static_files_base_path }}/.well-known/matrix/support" + mode: 0644 + owner: "{{ matrix_user_username }}" + group: "{{ matrix_user_groupname }}" diff --git a/roles/matrix-base/templates/static-files/well-known/matrix-support.j2 b/roles/matrix-base/templates/static-files/well-known/matrix-support.j2 new file mode 100644 index 000000000..71567abbe --- /dev/null +++ b/roles/matrix-base/templates/static-files/well-known/matrix-support.j2 @@ -0,0 +1,7 @@ +#jinja2: lstrip_blocks: "True" +{ + "admins": {{ matrix_homeserver_admin_contacts|to_json }} + {% if matrix_homeserver_support_url %}, + "support_page": "{{ matrix_homeserver_support_url|to_json }}" + {% endif %} +}