From 8355348aae080da8eefac7c089a5c91480bd1888 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?B=C3=A9la=20Becker?= <bela@becker.rocks>
Date: Wed, 20 Jan 2021 15:52:26 +0100
Subject: [PATCH 01/66] Etherpad documentation

---
 README.md                             |  2 ++
 docs/configuring-playbook-etherpad.md | 26 ++++++++++++++++++++++++++
 2 files changed, 28 insertions(+)
 create mode 100644 docs/configuring-playbook-etherpad.md

diff --git a/README.md b/README.md
index 93c022d97..26e059af3 100644
--- a/README.md
+++ b/README.md
@@ -77,6 +77,8 @@ Using this playbook, you can get the following services configured on your serve
 
 - (optional) [Dimension](https://github.com/turt2live/matrix-dimension), an open source integrations manager for matrix clients - see [docs/configuring-playbook-dimension.md](docs/configuring-playbook-dimension.md) for setup documentation
 
+- (optional) [Etherpad](https://etherpad.org), an open source collaborative text editor - see [docs/configuring-playbook-etherpad.md](docs/configuring-playbook-etherpad.md) for setup documentation
+
 - (optional) [Jitsi](https://jitsi.org/), an open source video-conferencing platform - see [docs/configuring-playbook-jitsi.md](docs/configuring-playbook-jitsi.md) for setup documentation
 
 - (optional) [matrix-reminder-bot](https://github.com/anoadragon453/matrix-reminder-bot) for scheduling one-off & recurring reminders and alarms - see [docs/configuring-playbook-bot-matrix-reminder-bot.md](docs/configuring-playbook-bot-matrix-reminder-bot.md) for setup documentation
diff --git a/docs/configuring-playbook-etherpad.md b/docs/configuring-playbook-etherpad.md
new file mode 100644
index 000000000..9ec24d33a
--- /dev/null
+++ b/docs/configuring-playbook-etherpad.md
@@ -0,0 +1,26 @@
+# Setting up Etherpad (optional)
+
+[Etherpad](https://etherpad.org) is is an open source collaborative text editor that can be embedded in a Matrix chat room using the [Dimension integrations manager](https://dimension.t2bot.io)
+
+When enabled together with Jitsi, it will be made available as an option during the conferences.
+
+## Prerequisites
+
+For the self-hosted Etherpad instance to be available to your users, you must first enable and configure the **Dimension integrations manager** as described in [the playbook documentation](configuring-playbook-dimension.md)
+
+## Enable
+
+[Etherpad](https://etherpad.org) installation is disabled by default. You can enable it in your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
+
+```yaml
+matrix_etherpad_enabled: true
+```
+
+## Set Dimension default to the self-hosted Etherpad
+
+The Dimension administrator users can configure the default URL template. The Dimension configuration menu can be accessed with the sprocket icon as you begin to add a widget to a room in Element. There you will find the Etherpad Widget Configuration action beneath the _Widgets_ tab. Replace `scalar.vector.im` with your own Dimension domain.
+
+### Removing the integrated Etherpad chat
+
+If you wish to disable the Etherpad chat button, you can do it by appending `?showChat=false` to the end of the pad URL, or the template.
+Example: `https://dimension.<your-domain>/etherpad/p/$roomId_$padName?showChat=false`

From 4b451ff782000d49c1c5b601447bc240369a3f91 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?B=C3=A9la=20Becker?= <bela@becker.rocks>
Date: Thu, 21 Jan 2021 00:06:35 +0100
Subject: [PATCH 02/66] Etherpad role

---
 group_vars/matrix_servers                     |  29 +++++
 roles/matrix-etherpad/defaults/main.yml       |  93 +++++++++++++++
 roles/matrix-etherpad/tasks/init.yml          |   3 +
 roles/matrix-etherpad/tasks/main.yml          |  15 +++
 roles/matrix-etherpad/tasks/setup_install.yml |  36 ++++++
 .../matrix-etherpad/tasks/setup_uninstall.yml |  35 ++++++
 .../matrix-etherpad/tasks/validate_config.yml |   7 ++
 .../templates/settings.json.j2                | 106 ++++++++++++++++++
 .../systemd/matrix-etherpad.service.j2        |  49 ++++++++
 setup.yml                                     |   1 +
 10 files changed, 374 insertions(+)
 create mode 100644 roles/matrix-etherpad/defaults/main.yml
 create mode 100644 roles/matrix-etherpad/tasks/init.yml
 create mode 100644 roles/matrix-etherpad/tasks/main.yml
 create mode 100644 roles/matrix-etherpad/tasks/setup_install.yml
 create mode 100644 roles/matrix-etherpad/tasks/setup_uninstall.yml
 create mode 100644 roles/matrix-etherpad/tasks/validate_config.yml
 create mode 100644 roles/matrix-etherpad/templates/settings.json.j2
 create mode 100644 roles/matrix-etherpad/templates/systemd/matrix-etherpad.service.j2

diff --git a/group_vars/matrix_servers b/group_vars/matrix_servers
index 7c736ba4a..50d34bccd 100755
--- a/group_vars/matrix_servers
+++ b/group_vars/matrix_servers
@@ -757,7 +757,30 @@ matrix_dimension_database_password: "{{ matrix_synapse_macaroon_secret_key | pas
 #
 ######################################################################
 
+######################################################################
+#
+# matrix-etherpad
+#
+######################################################################
 
+matrix_etherpad_enabled: false
+
+matrix_etherpad_systemd_required_services_list: |
+  {{
+    ['docker.service']
+    +
+    (['matrix-postgres.service'] if matrix_postgres_enabled else [])
+  }}
+
+# Postgres is the default, except if not using `matrix_postgres` (internal postgres)
+matrix_etherpad_database_engine: "{{ 'postgres' if matrix_postgres_enabled else 'sqlite' }}"
+matrix_etherpad_database_password: "{{ matrix_synapse_macaroon_secret_key | password_hash('sha512', 'etherpad.db') | to_uuid }}"
+
+######################################################################
+#
+# /matrix-etherpad
+#
+######################################################################
 
 ######################################################################
 #
@@ -1146,6 +1169,12 @@ matrix_postgres_additional_databases: |
       'username': matrix_dimension_database_username,
       'password': matrix_dimension_database_password,
     }] if (matrix_dimension_enabled and matrix_dimension_database_engine == 'postgres' and matrix_dimension_database_hostname == 'matrix-postgres') else [])
+    +
+    ([{
+      'name': matrix_etherpad_database_name,
+      'username': matrix_etherpad_database_username,
+      'password': matrix_etherpad_database_password,
+    }] if (matrix_etherpad_enabled and matrix_etherpad_database_engine == 'postgres' and matrix_etherpad_database_hostname == 'matrix-postgres') else [])
    }}
 
 matrix_postgres_import_roles_to_ignore: |
diff --git a/roles/matrix-etherpad/defaults/main.yml b/roles/matrix-etherpad/defaults/main.yml
new file mode 100644
index 000000000..353adac79
--- /dev/null
+++ b/roles/matrix-etherpad/defaults/main.yml
@@ -0,0 +1,93 @@
+matrix_etherpad_enabled: false
+
+matrix_etherpad_base_path: "{{ matrix_base_data_path }}/etherpad"
+
+matrix_etherpad_docker_image: "docker.io/etherpad/etherpad:latest"
+matrix_etherpad_docker_image_force_pull: "{{ matrix_etherpad_docker_image.endswith(':latest') }}"
+
+# List of systemd services that matrix-etherpad.service depends on.
+matrix_etherpad_systemd_required_services_list: ['docker.service']
+
+# List of systemd services that matrix-etherpad.service wants
+matrix_etherpad_systemd_wanted_services_list: []
+
+# Container user has to be able to write to the source file directories until this bug is fixed:
+# https://github.com/ether/etherpad-lite/issues/2683
+matrix_etherpad_user_uid: '5001'
+matrix_etherpad_user_gid: '5001'
+
+# Controls whether the matrix-etherpad container exposes its HTTP port (tcp/9001 in the container).
+#
+# Takes an "<ip>:<port>" or "<port>" value (e.g. "127.0.0.1:9001"), or empty string to not expose.
+matrix_etherpad_container_http_host_bind_port: '9001'
+
+# A list of extra arguments to pass to the container
+matrix_etherpad_container_extra_arguments: []
+
+matrix_etherpad_public_endpoint: '/etherpad'
+
+# By default, the Etherpad app can be accessed within the Dimension domain
+matrix_etherpad_base_url: "https://{{ matrix_server_fqn_dimension }}{{ matrix_etherpad_public_endpoint }}"
+
+# Database-related configuration fields.
+#
+# Etherpad recommends using a dedicated database, and supports Sqliite only for development
+#
+# To use Postgres:
+# - change the engine (`matrix_etherpad_database_engine: 'postgres'`)
+# - adjust your database credentials via the `matrix_etherpad_postgres_*` variables
+matrix_etherpad_database_engine: 'sqlite'
+
+matrix_etherpad_sqlite_database_path_local: "{{ matrix_etherpad_base_path }}/etherpad.db"
+matrix_etherpad_sqlite_database_path_in_container: "/data/etherpad.db"
+
+matrix_etherpad_database_username: 'matrix_etherpad'
+matrix_etherpad_database_password: 'some-password'
+matrix_etherpad_database_hostname: 'matrix-postgres'
+matrix_etherpad_database_port: 5432
+matrix_etherpad_database_name: 'matrix_etherpad'
+
+matrix_etherpad_database_connection_string: 'postgres://{{ matrix_etherpad_database_username }}:{{ matrix_etherpad_database_password }}@{{ matrix_etherpad_database_hostname }}:{{ matrix_etherpad_database_port }}/{{ matrix_etherpad_database_name }}'
+
+# Variables configuring the etherpad
+matrix_etherpad_title: 'Etherpad'
+matrix_etherpad_default_pad_text: |
+  Welcome to Etherpad!
+  
+  This pad text is synchronized as you type, so that everyone viewing this page sees the same text. This allows you to collaborate seamlessly on documents!
+  
+  Get involved with Etherpad at https://etherpad.org
+
+# Default Etherpad configuration template which covers the generic use case.
+# You can customize it by controlling the various variables inside it.
+#
+# For a more advanced customization, you can extend the default (see `matrix_etherpad_configuration_extension_json`)
+# or completely replace this variable with your own template.
+matrix_etherpad_configuration_default: "{{ lookup('template', 'templates/settings.json.j2') }}"
+
+# Your custom JSON configuration for Etherpad goes here.
+# This configuration extends the default starting configuration (`matrix_etherpad_configuration_json`).
+#
+# You can override individual variables from the default configuration, or introduce new ones.
+#
+# If you need something more special, you can take full control by
+# completely redefining `matrix_etherpad_configuration_json`.
+#
+# Example configuration extension follows:
+#
+# matrix_etherpad_configuration_extension_json: |
+#  {
+#   "loadTest": true,
+#   "commitRateLimiting": {
+#     "duration": 1,
+#     "points": 10
+#   }
+#  }
+#
+matrix_etherpad_configuration_extension_json: '{}'
+
+matrix_etherpad_configuration_extension: "{{ matrix_etherpad_configuration_extension_json|from_json if matrix_etherpad_configuration_extension_json|from_json is mapping else {} }}"
+
+# Holds the final Etherpad configuration (a combination of the default and its extension).
+# You most likely don't need to touch this variable. Instead, see `matrix_etherpad_configuration_json`.
+matrix_etherpad_configuration: "{{ matrix_etherpad_configuration_default|combine(matrix_etherpad_configuration_extension, recursive=True) }}"
diff --git a/roles/matrix-etherpad/tasks/init.yml b/roles/matrix-etherpad/tasks/init.yml
new file mode 100644
index 000000000..7496d4b45
--- /dev/null
+++ b/roles/matrix-etherpad/tasks/init.yml
@@ -0,0 +1,3 @@
+- set_fact:
+    matrix_systemd_services_list: "{{ matrix_systemd_services_list + ['matrix-etherpad.service'] }}"
+  when: matrix_etherpad_enabled|bool
diff --git a/roles/matrix-etherpad/tasks/main.yml b/roles/matrix-etherpad/tasks/main.yml
new file mode 100644
index 000000000..09ead9735
--- /dev/null
+++ b/roles/matrix-etherpad/tasks/main.yml
@@ -0,0 +1,15 @@
+- import_tasks: "{{ role_path }}/tasks/init.yml"
+  tags:
+    - always
+
+- import_tasks: "{{ role_path }}/tasks/setup_install.yml"
+  when: run_setup|bool and matrix_etherpad_enabled|bool
+  tags:
+    - setup-all
+    - setup-etherpad
+
+- import_tasks: "{{ role_path }}/tasks/setup_uninstall.yml"
+  when: run_setup|bool and not matrix_etherpad_enabled|bool
+  tags:
+    - setup-all
+    - setup-etherpad
diff --git a/roles/matrix-etherpad/tasks/setup_install.yml b/roles/matrix-etherpad/tasks/setup_install.yml
new file mode 100644
index 000000000..a93c28de5
--- /dev/null
+++ b/roles/matrix-etherpad/tasks/setup_install.yml
@@ -0,0 +1,36 @@
+---
+
+- name: Ensure Etherpad base path exists
+  file:
+    path: "{{ matrix_etherpad_base_path }}"
+    state: directory
+    mode: 0770
+    owner: "{{ matrix_etherpad_user_uid }}"
+    group: "{{ matrix_etherpad_user_gid }}"
+
+- name: Ensure Etherpad config installed
+  copy:
+    content: "{{ matrix_etherpad_configuration|to_nice_json }}"
+    dest: "{{ matrix_etherpad_base_path }}/settings.json"
+    mode: 0640
+    owner: "{{ matrix_etherpad_user_uid }}"
+    group: "{{ matrix_etherpad_user_gid }}"
+
+- name: Ensure Etherpad image is pulled
+  docker_image:
+    name: "{{ matrix_etherpad_docker_image }}"
+    source: "{{ 'pull' if ansible_version.major > 2 or ansible_version.minor > 7 else omit }}"
+    force_source: "{{ matrix_etherpad_docker_image_force_pull if ansible_version.major > 2 or ansible_version.minor >= 8 else omit }}"
+    force: "{{ omit if ansible_version.major > 2 or ansible_version.minor >= 8 else matrix_etherpad_docker_image_force_pull }}"
+
+- name: Ensure matrix-etherpad.service installed
+  template:
+    src: "{{ role_path }}/templates/systemd/matrix-etherpad.service.j2"
+    dest: "{{ matrix_systemd_path }}/matrix-etherpad.service"
+    mode: 0644
+  register: matrix_etherpad_systemd_service_result
+
+- name: Ensure systemd reloaded after matrix-etherpad.service installation
+  service:
+    daemon_reload: yes
+  when: "matrix_etherpad_systemd_service_result.changed|bool"
diff --git a/roles/matrix-etherpad/tasks/setup_uninstall.yml b/roles/matrix-etherpad/tasks/setup_uninstall.yml
new file mode 100644
index 000000000..865389f2d
--- /dev/null
+++ b/roles/matrix-etherpad/tasks/setup_uninstall.yml
@@ -0,0 +1,35 @@
+---
+
+- name: Check existence of matrix-etherpad service
+  stat:
+    path: "{{ matrix_systemd_path }}/matrix-etherpad.service"
+  register: matrix_etherpad_service_stat
+
+- name: Ensure matrix-etherpad is stopped
+  service:
+    name: matrix-etherpad
+    state: stopped
+    daemon_reload: yes
+  register: stopping_result
+  when: "matrix_etherpad_service_stat.stat.exists|bool"
+
+- name: Ensure matrix-etherpad.service doesn't exist
+  file:
+    path: "{{ matrix_systemd_path }}/matrix-etherpad.service"
+    state: absent
+  when: "matrix_etherpad_service_stat.stat.exists|bool"
+
+- name: Ensure systemd reloaded after matrix-etherpad.service removal
+  service:
+    daemon_reload: yes
+  when: "matrix_etherpad_service_stat.stat.exists|bool"
+
+- name: Ensure Etherpad base directory doesn't exist
+  file:
+    path: "{{ matrix_etherpad_base_path }}"
+    state: absent
+
+- name: Ensure Dimension Docker image doesn't exist
+  docker_image:
+    name: "{{ matrix_etherpad_docker_image }}"
+    state: absent
diff --git a/roles/matrix-etherpad/tasks/validate_config.yml b/roles/matrix-etherpad/tasks/validate_config.yml
new file mode 100644
index 000000000..e5621a073
--- /dev/null
+++ b/roles/matrix-etherpad/tasks/validate_config.yml
@@ -0,0 +1,7 @@
+- name: Fail if required Etherpad settings not defined
+  fail:
+    msg: >-
+      You need to define a required configuration setting (`{{ item }}`) for using Etherpad.
+  with_items:
+    -
+  when: "matrix_etherpad_enabled and vars[item] == ''"
diff --git a/roles/matrix-etherpad/templates/settings.json.j2 b/roles/matrix-etherpad/templates/settings.json.j2
new file mode 100644
index 000000000..6435cf6db
--- /dev/null
+++ b/roles/matrix-etherpad/templates/settings.json.j2
@@ -0,0 +1,106 @@
+{
+  "title": {{ matrix_etherpad_title|to_json }},
+  "favicon": "favicon.ico",
+  "skinName": "colibris",
+  "skinVariants": "super-light-toolbar super-light-editor light-background",
+  "ip": "::",
+  "port": 9001,
+  "showSettingsInAdminPage": true,
+  "dbType": {{ matrix_etherpad_database_engine|to_json }},
+  "dbSettings": {
+    {% if matrix_etherpad_database_engine == 'sqlite' %}
+      "filename": {{ matrix_etherpad_sqlite_database_path_in_container|to_json }}
+    {% elif matrix_etherpad_database_engine == 'postgres' %}
+      "database": {{ matrix_etherpad_database_name|to_json }},
+      "host":     {{ matrix_etherpad_database_hostname|to_json }},
+      "password": {{ matrix_etherpad_database_password|to_json }},
+      "port":     {{ matrix_etherpad_database_port|to_json }},
+      "user":     {{ matrix_etherpad_database_username|to_json }}
+    {% endif %}
+  },
+  "defaultPadText" : {{ matrix_etherpad_default_pad_text|to_json }},
+  "suppressErrorsInPadText": false,
+  "requireSession": false,
+  "editOnly": false,
+  "minify": true,
+  "maxAge": 21600,
+  "abiword": null,
+  "soffice": null,
+  "tidyHtml": null,
+  "allowUnknownFileEnds": true,
+  "requireAuthentication": false,
+  "requireAuthorization": false,
+  "trustProxy": true,
+  "cookie": {
+    "sameSite": "Lax"
+  },
+  "disableIPlogging": true,
+  "automaticReconnectionTimeout": 0,
+  "scrollWhenFocusLineIsOutOfViewport": {
+    "percentage": {
+      "editionAboveViewport": 0,
+      "editionBelowViewport": 0
+    },
+    "duration": 0,
+    "scrollWhenCaretIsInTheLastLineOfViewport": false,
+    "percentageToScrollWhenUserPressesArrowUp": 0
+  },
+  "socketTransportProtocols" : ["xhr-polling", "jsonp-polling", "htmlfile"],
+  "loadTest": false,
+  "importExportRateLimiting": {
+    "windowMs": 90000,
+    "max": 10
+  },
+  "importMaxFileSize": 52428800,
+  "commitRateLimiting": {
+    "duration": 1,
+    "points": 10
+  },
+  "exposeVersion": false,
+  "padOptions": {
+    "noColors": false,
+    "showControls": true,
+    "showChat": false,
+    "showLineNumbers": true,
+    "useMonospaceFont": false,
+    "userName": false,
+    "userColor": false,
+    "rtl": false,
+    "alwaysShowChat": false,
+    "chatAndUsers": false,
+    "lang": "en-gb"
+  },
+  "padShortcutEnabled" : {
+    "altF9": true,
+    "altC": true,
+    "cmdShift2": true,
+    "delete": true,
+    "return": true,
+    "esc": true,
+    "cmdS": true,
+    "tab": true,
+    "cmdZ": true,
+    "cmdY": true,
+    "cmdI": true,
+    "cmdB": true,
+    "cmdU": true,
+    "cmd5": true,
+    "cmdShiftL": true,
+    "cmdShiftN": true,
+    "cmdShift1": true,
+    "cmdShiftC": true,
+    "cmdH": true,
+    "ctrlHome": true,
+    "pageUp": true,
+    "pageDown": true
+  },
+  "loglevel": "INFO",
+  "logconfig" :
+    { "appenders": [
+        { "type": "console",
+          "layout": {"type": "messagePassThrough"}
+        }
+      ]
+    },
+  "customLocaleStrings": {}
+}
diff --git a/roles/matrix-etherpad/templates/systemd/matrix-etherpad.service.j2 b/roles/matrix-etherpad/templates/systemd/matrix-etherpad.service.j2
new file mode 100644
index 000000000..6f662aa79
--- /dev/null
+++ b/roles/matrix-etherpad/templates/systemd/matrix-etherpad.service.j2
@@ -0,0 +1,49 @@
+#jinja2: lstrip_blocks: "True"
+[Unit]
+Description=Matrix Etherpad
+{% for service in matrix_etherpad_systemd_required_services_list %}
+Requires={{ service }}
+After={{ service }}
+{% endfor %}
+{% for service in matrix_etherpad_systemd_wanted_services_list %}
+Wants={{ service }}
+{% endfor %}
+DefaultDependencies=no
+
+[Service]
+Type=simple
+Environment="HOME={{ matrix_systemd_unit_home_path }}"
+ExecStartPre=-{{ matrix_host_command_docker }} kill matrix-etherpad
+ExecStartPre=-{{ matrix_host_command_docker }} rm matrix-etherpad
+
+# Fixup database ownership if it got changed somehow (during a server migration, etc.)
+{% if matrix_etherpad_database_engine == 'sqlite' %}
+ExecStartPre=-{{ matrix_host_command_chown }} {{ matrix_etherpad_user_uid }} {{ matrix_etherpad_sqlite_database_path_local }}
+{% endif %}
+
+ExecStart={{ matrix_host_command_docker }} run --rm --name matrix-etherpad \
+			--log-driver=none \
+			--user={{ matrix_etherpad_user_uid }}:{{ matrix_etherpad_user_gid }} \
+			--cap-drop=ALL \
+			--network={{ matrix_docker_network }} \
+			{% if matrix_etherpad_container_http_host_bind_port %}
+			-p {{ matrix_etherpad_container_http_host_bind_port }}:9001 \
+			{% endif %}
+			--mount type=bind,src={{ matrix_etherpad_base_path }},dst=/data \
+			{% for arg in matrix_etherpad_container_extra_arguments %}
+			{{ arg }} \
+			{% endfor %}
+			{{ matrix_etherpad_docker_image }} \
+			node --experimental-worker /opt/etherpad-lite/node_modules/ep_etherpad-lite/node/server.js \
+				--settings /data/settings.json --credentials /data/credentials.json \
+				--sessionkey /data/sessionkey.json --apikey /data/apijey.json
+				
+
+ExecStop=-{{ matrix_host_command_docker }} kill matrix-etherpad
+ExecStop=-{{ matrix_host_command_docker }} rm matrix-etherpad
+Restart=always
+RestartSec=30
+SyslogIdentifier=matrix-etherpad
+
+[Install]
+WantedBy=multi-user.target
diff --git a/setup.yml b/setup.yml
index d070bcae4..9bb1788f1 100755
--- a/setup.yml
+++ b/setup.yml
@@ -33,6 +33,7 @@
     - matrix-jitsi
     - matrix-ma1sd
     - matrix-dimension
+    - matrix-etherpad
     - matrix-email2matrix
     - matrix-nginx-proxy
     - matrix-coturn

From 38bf1eda7026b75ddf0993910e50f8b0ecb6467b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?B=C3=A9la=20Becker?= <bela@becker.rocks>
Date: Thu, 21 Jan 2021 00:06:59 +0100
Subject: [PATCH 03/66] Etherpad Jitsi integration

---
 group_vars/matrix_servers                            | 7 +++++++
 roles/matrix-jitsi/defaults/main.yml                 | 3 +++
 roles/matrix-jitsi/templates/web/custom-config.js.j2 | 3 +++
 roles/matrix-jitsi/templates/web/env.j2              | 2 ++
 4 files changed, 15 insertions(+)

diff --git a/group_vars/matrix_servers b/group_vars/matrix_servers
index 50d34bccd..5d76a60cc 100755
--- a/group_vars/matrix_servers
+++ b/group_vars/matrix_servers
@@ -843,6 +843,13 @@ matrix_jitsi_web_stun_servers: |
     else [ 'stun:meet-jit-si-turnrelay.jitsi.net:443']
   }}
 
+# If the self-hosted Etherpad instance is available, it will also show up in Jitsi conferences,
+# unless explicitly disabled by setting `matrix_jitsi_etherpad_enabled` to false.
+# Falls back to the scalar.vector.im etherpad in case someone sets `matrix_jitsi_etherpad_enabled` to true,
+# while also setting `matrix_etherpad_enabled` to false.
+matrix_jitsi_etherpad_enabled: "{{ matrix_etherpad_enabled }}"
+matrix_jitsi_etherpad_base: "{{ matrix_etherpad_base_url if matrix_etherpad_enabled else 'https://scalar.vector.im/etherpad' }}"
+
 ######################################################################
 #
 # /matrix-jitsi
diff --git a/roles/matrix-jitsi/defaults/main.yml b/roles/matrix-jitsi/defaults/main.yml
index 924198b4f..028d9c19e 100644
--- a/roles/matrix-jitsi/defaults/main.yml
+++ b/roles/matrix-jitsi/defaults/main.yml
@@ -67,6 +67,9 @@ matrix_jitsi_web_public_url: "https://{{ matrix_server_fqn_jitsi }}"
 # Addresses need to be prefixed with one of `stun:`, `turn:` or `turns:`.
 matrix_jitsi_web_stun_servers: ['stun:meet-jit-si-turnrelay.jitsi.net:443']
 
+# Controls whether Etherpad will be available within Jitsi
+matrix_jitsi_etherpad_enabled: false
+
 # Controls whether the matrix-jitsi-web container exposes its HTTP port (tcp/80 in the container).
 #
 # Takes an "<ip>:<port>" or "<port>" value (e.g. "127.0.0.1:12080"), or empty string to not expose.
diff --git a/roles/matrix-jitsi/templates/web/custom-config.js.j2 b/roles/matrix-jitsi/templates/web/custom-config.js.j2
index 02316ca03..bbe85798a 100644
--- a/roles/matrix-jitsi/templates/web/custom-config.js.j2
+++ b/roles/matrix-jitsi/templates/web/custom-config.js.j2
@@ -11,5 +11,8 @@ config.p2p.stunServers = [
 ];
 {% endif %}
 
+{% if matrix_jitsi_etherpad_enabled %}
+config.etherpad_base = {{ (matrix_jitsi_etherpad_base + '/p/') |to_json }}
+{% endif %}
 
 {{ matrix_jitsi_web_custom_config_extension }}
diff --git a/roles/matrix-jitsi/templates/web/env.j2 b/roles/matrix-jitsi/templates/web/env.j2
index 353a3d145..7b763a3ca 100644
--- a/roles/matrix-jitsi/templates/web/env.j2
+++ b/roles/matrix-jitsi/templates/web/env.j2
@@ -37,4 +37,6 @@ RESOLUTION_WIDTH_MIN={{ matrix_jitsi_web_config_resolution_width_min }}
 START_AUDIO_MUTED={{ matrix_jitsi_web_config_start_audio_muted_after_nth_participant }}
 START_VIDEO_MUTED={{ matrix_jitsi_web_config_start_video_muted_after_nth_participant }}
 
+ETHERPAD_URL_BASE={{ (matrix_jitsi_etherpad_base + '/') if matrix_jitsi_etherpad_enabled else ''}}
+
 {{ matrix_jitsi_web_environment_variables_extension }}

From 7bc9be95cb2225b3ccdd8db2ff6e604e345157ed Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?B=C3=A9la=20Becker?= <bela@becker.rocks>
Date: Thu, 21 Jan 2021 13:32:25 +0100
Subject: [PATCH 04/66] Add map directive to the base of nginx.conf

This needs to be added for WebSocket upgrades to work properly (see doc:
http://nginx.org/en/docs/http/websocket.html)
---
 roles/matrix-nginx-proxy/templates/nginx/nginx.conf.j2 | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/roles/matrix-nginx-proxy/templates/nginx/nginx.conf.j2 b/roles/matrix-nginx-proxy/templates/nginx/nginx.conf.j2
index 975c8b4f9..facb0901f 100644
--- a/roles/matrix-nginx-proxy/templates/nginx/nginx.conf.j2
+++ b/roles/matrix-nginx-proxy/templates/nginx/nginx.conf.j2
@@ -45,6 +45,11 @@ http {
 	keepalive_timeout 65;
 
 	#gzip on;
+	{# Map directive needed for proxied WebSocket upgrades #}
+	map $http_upgrade $connection_upgrade {
+		default upgrade;
+		''      close;
+	}
 
 	include /etc/nginx/conf.d/*.conf;
 }

From 42f338016ba87480a948d89e224901dd8215673e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?B=C3=A9la=20Becker?= <bela@becker.rocks>
Date: Thu, 21 Jan 2021 15:27:29 +0100
Subject: [PATCH 05/66] Etherpad matrix-nginx-proxy configuration

---
 roles/matrix-etherpad/tasks/init.yml | 59 ++++++++++++++++++++++++++++
 1 file changed, 59 insertions(+)

diff --git a/roles/matrix-etherpad/tasks/init.yml b/roles/matrix-etherpad/tasks/init.yml
index 7496d4b45..081d4c233 100644
--- a/roles/matrix-etherpad/tasks/init.yml
+++ b/roles/matrix-etherpad/tasks/init.yml
@@ -1,3 +1,62 @@
 - set_fact:
     matrix_systemd_services_list: "{{ matrix_systemd_services_list + ['matrix-etherpad.service'] }}"
   when: matrix_etherpad_enabled|bool
+
+- block:
+  - name: Fail if matrix-nginx-proxy role already executed
+    fail:
+      msg: >-
+        Trying to append Etherpad's reverse-proxying configuration to matrix-nginx-proxy,
+        but it's pointless since the matrix-nginx-proxy role had already executed.
+        To fix this, please change the order of roles in your plabook,
+        so that the matrix-nginx-proxy role would run after the matrix-etherpad role.
+    when: matrix_nginx_proxy_role_executed|default(False)|bool
+
+  - name: Generate Etherpad proxying configuration for matrix-nginx-proxy
+    set_fact:
+      matrix_etherpad_matrix_nginx_proxy_configuration: |
+        rewrite ^{{ matrix_etherpad_public_endpoint }}$ $scheme://$server_name{{ matrix_etherpad_public_endpoint }}/ permanent;
+
+        location {{ matrix_etherpad_public_endpoint }}/ {
+        {% if matrix_nginx_proxy_enabled|default(False) %}
+          {# Use the embedded DNS resolver in Docker containers to discover the service #}
+          resolver 127.0.0.11 valid=5s;
+          proxy_pass http://matrix-etherpad:9001/;
+          {# These are proxy directives needed specifically by Etherpad #}
+          proxy_buffering off;
+          proxy_http_version 1.1;  # recommended with keepalive connections
+          proxy_pass_header Server;
+          proxy_set_header Host $host;
+          proxy_set_header X-Forwarded-Proto $scheme; # for EP to set secure cookie flag when https is used
+          # WebSocket proxying - from http://nginx.org/en/docs/http/websocket.html
+          proxy_set_header Upgrade $http_upgrade;
+          proxy_set_header Connection $connection_upgrade;
+        {% else %}
+          {# Generic configuration for use outside of our container setup #}
+          # A good guide for setting up your Etherpad behind nginx:
+          # https://docs.gandi.net/en/cloud/tutorials/etherpad_lite.html
+          proxy_pass http://127.0.0.1:9001/;
+        {% endif %}
+        }
+
+  - name: Register Etherpad proxying configuration with matrix-nginx-proxy
+    set_fact:
+      matrix_nginx_proxy_proxy_dimension_additional_server_configuration_blocks: |
+        {{
+          matrix_nginx_proxy_proxy_dimension_additional_server_configuration_blocks|default([])
+          +
+          [matrix_etherpad_matrix_nginx_proxy_configuration]
+        }}
+  tags:
+    - always
+  when: matrix_etherpad_enabled|bool
+
+- name: Warn about reverse-proxying if matrix-nginx-proxy not used
+  debug:
+    msg: >-
+      NOTE: You've enabled the Etherpad tool but are not using the matrix-nginx-proxy
+      reverse proxy.
+      Please make sure that you're proxying the `{{ matrix_etherpad_public_endpoint }}`
+      URL endpoint to the matrix-etherpad container.
+      You can expose the container's port using the `matrix_etherpad_container_http_host_bind_port` variable.
+  when: "matrix_etherpad_enabled|bool and matrix_nginx_proxy_enabled is not defined"

From 346f8b347536575b84e020860d08d255009317d2 Mon Sep 17 00:00:00 2001
From: Slavi Pantaleev <slavi@devture.com>
Date: Tue, 26 Jan 2021 10:13:08 +0200
Subject: [PATCH 06/66] Fix typo

---
 roles/matrix-etherpad/defaults/main.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/roles/matrix-etherpad/defaults/main.yml b/roles/matrix-etherpad/defaults/main.yml
index 353adac79..19a79bd14 100644
--- a/roles/matrix-etherpad/defaults/main.yml
+++ b/roles/matrix-etherpad/defaults/main.yml
@@ -31,7 +31,7 @@ matrix_etherpad_base_url: "https://{{ matrix_server_fqn_dimension }}{{ matrix_et
 
 # Database-related configuration fields.
 #
-# Etherpad recommends using a dedicated database, and supports Sqliite only for development
+# Etherpad recommends using a dedicated database, and supports Sqlite only for development
 #
 # To use Postgres:
 # - change the engine (`matrix_etherpad_database_engine: 'postgres'`)

From 26b287bd17db3e688d89e9b69ab1392587b1fb70 Mon Sep 17 00:00:00 2001
From: Slavi Pantaleev <slavi@devture.com>
Date: Wed, 27 Jan 2021 21:51:46 +0200
Subject: [PATCH 07/66] Upgrade certbot (1.10.1 -> 1.11.0)

---
 roles/matrix-nginx-proxy/defaults/main.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/roles/matrix-nginx-proxy/defaults/main.yml b/roles/matrix-nginx-proxy/defaults/main.yml
index 7c383383c..5eedb4cec 100644
--- a/roles/matrix-nginx-proxy/defaults/main.yml
+++ b/roles/matrix-nginx-proxy/defaults/main.yml
@@ -295,7 +295,7 @@ matrix_ssl_domains_to_obtain_certificates_for: []
 
 # Controls whether to obtain production or staging certificates from Let's Encrypt.
 matrix_ssl_lets_encrypt_staging: false
-matrix_ssl_lets_encrypt_certbot_docker_image: "docker.io/certbot/certbot:{{ matrix_ssl_architecture }}-v1.10.1"
+matrix_ssl_lets_encrypt_certbot_docker_image: "docker.io/certbot/certbot:{{ matrix_ssl_architecture }}-v1.11.0"
 matrix_ssl_lets_encrypt_certbot_docker_image_force_pull: "{{ matrix_ssl_lets_encrypt_certbot_docker_image.endswith(':latest') }}"
 matrix_ssl_lets_encrypt_certbot_standalone_http_port: 2402
 matrix_ssl_lets_encrypt_support_email: ~

From 3ea90ca4369285b0a3fa7ec9419823038d19ee6b Mon Sep 17 00:00:00 2001
From: Slavi Pantaleev <slavi@devture.com>
Date: Thu, 28 Jan 2021 09:23:23 +0200
Subject: [PATCH 08/66] Upgrade Element (1.7.17 -> 1.7.18)

---
 roles/matrix-client-element/defaults/main.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/roles/matrix-client-element/defaults/main.yml b/roles/matrix-client-element/defaults/main.yml
index 09bd24615..e8678b49c 100644
--- a/roles/matrix-client-element/defaults/main.yml
+++ b/roles/matrix-client-element/defaults/main.yml
@@ -3,7 +3,7 @@ matrix_client_element_enabled: true
 matrix_client_element_container_image_self_build: false
 matrix_client_element_container_image_self_build_repo: "https://github.com/vector-im/riot-web.git"
 
-matrix_client_element_docker_image: "{{ matrix_client_element_docker_image_name_prefix }}vectorim/element-web:v1.7.17"
+matrix_client_element_docker_image: "{{ matrix_client_element_docker_image_name_prefix }}vectorim/element-web:v1.7.18"
 matrix_client_element_docker_image_name_prefix: "{{ 'localhost/' if matrix_client_element_container_image_self_build else 'docker.io/' }}"
 matrix_client_element_docker_image_force_pull: "{{ matrix_client_element_docker_image.endswith(':latest') }}"
 

From b7261dc09878de3b14a9a784ea8178a58261db84 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?B=C3=A9la=20Becker?= <bela@becker.rocks>
Date: Thu, 28 Jan 2021 15:11:22 +0100
Subject: [PATCH 09/66] Etherpad role: Etherpad needs Dimension

The default scalar.vector.im integrations manager doesn't support custom
URL's for etherpad, therefore Dimension needs to be enabled.
---
 roles/matrix-etherpad/tasks/main.yml            | 6 ++++++
 roles/matrix-etherpad/tasks/validate_config.yml | 8 +++-----
 2 files changed, 9 insertions(+), 5 deletions(-)

diff --git a/roles/matrix-etherpad/tasks/main.yml b/roles/matrix-etherpad/tasks/main.yml
index 09ead9735..27548aaf9 100644
--- a/roles/matrix-etherpad/tasks/main.yml
+++ b/roles/matrix-etherpad/tasks/main.yml
@@ -13,3 +13,9 @@
   tags:
     - setup-all
     - setup-etherpad
+
+- import_tasks: "{{ role_path }}/tasks/validate_config.yml"
+  when: run_setup|bool and matrix_etherpad_enabled|bool
+  tags:
+    - setup-all
+    - setup-etherpad
diff --git a/roles/matrix-etherpad/tasks/validate_config.yml b/roles/matrix-etherpad/tasks/validate_config.yml
index e5621a073..776235587 100644
--- a/roles/matrix-etherpad/tasks/validate_config.yml
+++ b/roles/matrix-etherpad/tasks/validate_config.yml
@@ -1,7 +1,5 @@
-- name: Fail if required Etherpad settings not defined
+- name: Fail if Etherpad is enabled without the Dimension integrations manager
   fail:
     msg: >-
-      You need to define a required configuration setting (`{{ item }}`) for using Etherpad.
-  with_items:
-    -
-  when: "matrix_etherpad_enabled and vars[item] == ''"
+      To integrate Etherpad notes with Matrix rooms you need to set "matrix_dimension_enabled" to true
+  when: "not matrix_dimension_enabled|bool"

From 2edc9cb83c2dcb4882e2406838679bc7fcede3af Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?B=C3=A9la=20Becker?= <bela@becker.rocks>
Date: Thu, 28 Jan 2021 17:54:02 +0100
Subject: [PATCH 10/66] Name the Synapse database on state compression import

Fixes:
https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/833
---
 .../tasks/rust-synapse-compress-state/compress_room.yml         | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/roles/matrix-synapse/tasks/rust-synapse-compress-state/compress_room.yml b/roles/matrix-synapse/tasks/rust-synapse-compress-state/compress_room.yml
index 8570411f9..46cad8083 100644
--- a/roles/matrix-synapse/tasks/rust-synapse-compress-state/compress_room.yml
+++ b/roles/matrix-synapse/tasks/rust-synapse-compress-state/compress_room.yml
@@ -34,7 +34,7 @@
       --entrypoint=/bin/sh
       {{ matrix_postgres_docker_image_latest }}
       -c "cat /work/state-compressor.sql |
-      psql -v ON_ERROR_STOP=1 -h matrix-postgres"
+      psql -v ON_ERROR_STOP=1 -h matrix-postgres -d {{ matrix_synapse_database_database }}"
 
 - name: Import compression SQL into Postgres
   command: "{{ matrix_synapse_rust_synapse_compress_state_psql_import_command }}"

From 1a0f64f23b925273d54b97cfdc979eef0970b30b Mon Sep 17 00:00:00 2001
From: Slavi Pantaleev <slavi@devture.com>
Date: Thu, 28 Jan 2021 19:18:26 +0200
Subject: [PATCH 11/66] Mention specs on the Prerequisites page

Fixes https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/682
---
 docs/prerequisites.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/prerequisites.md b/docs/prerequisites.md
index f7db27f5f..e678a0bd2 100644
--- a/docs/prerequisites.md
+++ b/docs/prerequisites.md
@@ -2,7 +2,7 @@
 
 To install Matrix services using this Ansible playbook, you need:
 
-- (Recommended) An **x86** server running one of these operating systems:
+- (Recommended) An **x86** server ([What kind of server specs do I need?](faq.md#what-kind-of-server-specs-do-i-need)) running one of these operating systems:
   - **CentOS** (7 only for now; [8 is not yet supported](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/300))
   - **Debian** (9/Stretch or newer)
   - **Ubuntu** (16.04 or newer, although [20.04 may be problematic](ansible.md#supported-ansible-versions))

From bcdc42624feda65647b1e6fe2d37512bc97ddf82 Mon Sep 17 00:00:00 2001
From: Aaron Raimist <aaron@raim.ist>
Date: Fri, 29 Jan 2021 17:31:27 -0600
Subject: [PATCH 12/66] Add mx-puppet-skype and mx-puppet-slack to README

I also moved matrix-sms-bridge up to match the order from container-images.md
---
 README.md | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 93c022d97..872c92865 100644
--- a/README.md
+++ b/README.md
@@ -63,6 +63,12 @@ Using this playbook, you can get the following services configured on your serve
 
 - (optional) the [matrix-appservice-webhooks](https://github.com/turt2live/matrix-appservice-webhooks) bridge for slack compatible webhooks ([ConcourseCI](https://concourse-ci.org/), [Slack](https://slack.com/) etc. pp.)
 
+- (optional) the [matrix-sms-bridge](https://github.com/benkuly/matrix-sms-bridge) for bridging your Matrix server to SMS - see [docs/configuring-playbook-bridge-matrix-bridge-sms.md](docs/configuring-playbook-bridge-matrix-bridge-sms.md) for setup documentation
+
+- (optional) the [mx-puppet-skype](https://hub.docker.com/r/sorunome/mx-puppet-skype) for bridging your Matrix server to [Skype](https://www.skype.com) - see [docs/configuring-playbook-bridge-mx-puppet-skype.md](docs/configuring-playbook-bridge-mx-puppet-skype.md) for setup documentation
+
+- (optional) the [mx-puppet-slack](https://hub.docker.com/r/sorunome/mx-puppet-skype) for bridging your Matrix server to [Slack](https://slack.com) - see [docs/configuring-playbook-bridge-mx-puppet-slack.md](docs/configuring-playbook-bridge-mx-puppet-slack.md) for setup documentation
+
 - (optional) the [mx-puppet-instagram](https://github.com/Sorunome/mx-puppet-instagram) bridge for Instagram-DMs ([Instagram](https://www.instagram.com/)) - see [docs/configuring-playbook-bridge-mx-puppet-instagram.md](docs/configuring-playbook-bridge-mx-puppet-instagram.md) for setup documentation
 
 - (optional) the [mx-puppet-twitter](https://github.com/Sorunome/mx-puppet-twitter) bridge for Twitter-DMs ([Twitter](https://twitter.com/) - see [docs/configuring-playbook-bridge-mx-puppet-twitter.md](docs/configuring-playbook-bridge-mx-puppet-twitter.md) for setup documentation
@@ -71,8 +77,6 @@ Using this playbook, you can get the following services configured on your serve
 
 - (optional) the [mx-puppet-steam](https://github.com/icewind1991/mx-puppet-steam) bridge for [Steam](https://steamapp.com/)) - see [docs/configuring-playbook-bridge-mx-puppet-steam.md](docs/configuring-playbook-bridge-mx-puppet-steam.md) for setup documentation
 
-- (optional) the [matrix-sms-bridge](https://github.com/benkuly/matrix-sms-bridge) for bridging your Matrix server to SMS - see [docs/configuring-playbook-bridge-matrix-bridge-sms.md](docs/configuring-playbook-bridge-matrix-bridge-sms.md) for setup documentation
-
 - (optional) [Email2Matrix](https://github.com/devture/email2matrix) for relaying email messages to Matrix rooms - see [docs/configuring-playbook-email2matrix.md](docs/configuring-playbook-email2matrix.md) for setup documentation
 
 - (optional) [Dimension](https://github.com/turt2live/matrix-dimension), an open source integrations manager for matrix clients - see [docs/configuring-playbook-dimension.md](docs/configuring-playbook-dimension.md) for setup documentation

From 473936065d17e8496408028954982a175b98eac1 Mon Sep 17 00:00:00 2001
From: Peetz0r <github@haas-en-berg.nl>
Date: Sat, 30 Jan 2021 08:21:46 +0100
Subject: [PATCH 13/66] Use Debian Buster Docker repo on Debian Bullseye

Future maintainer: check on https://docs.docker.com/engine/install/debian/ if Docker for
Debian 11 is released, then undo this commit
---
 roles/matrix-base/tasks/server_base/setup_debian.yml | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/roles/matrix-base/tasks/server_base/setup_debian.yml b/roles/matrix-base/tasks/server_base/setup_debian.yml
index 37706d1f9..42b6f30c3 100644
--- a/roles/matrix-base/tasks/server_base/setup_debian.yml
+++ b/roles/matrix-base/tasks/server_base/setup_debian.yml
@@ -23,7 +23,14 @@
     repo: "deb [arch={{ matrix_debian_arch }}] https://download.docker.com/linux/{{ ansible_distribution|lower }} {{ ansible_distribution_release }} stable"
     state: present
     update_cache: yes
-  when: matrix_docker_installation_enabled|bool and matrix_docker_package_name == 'docker-ce'
+  when: matrix_docker_installation_enabled|bool and matrix_docker_package_name == 'docker-ce and not ansible_distribution_release == 'bullseye'
+
+- name: Ensure Docker repository is enabled (using Debian Buster on Debian Bullseye, for which there is no Docker yet)
+  apt_repository:
+    repo: "deb [arch={{ matrix_debian_arch }}] https://download.docker.com/linux/{{ ansible_distribution|lower }} buster stable"
+    state: present
+    update_cache: yes
+  when: matrix_docker_installation_enabled|bool and matrix_docker_package_name == 'docker-ce and ansible_distribution_release == 'bullseye'
 
 - name: Ensure APT packages are installed
   apt:

From efbffa26bf79139043f6c0c0e1ca69fb03c93616 Mon Sep 17 00:00:00 2001
From: Slavi Pantaleev <slavi@devture.com>
Date: Sat, 30 Jan 2021 11:37:08 +0200
Subject: [PATCH 14/66] Fix typo

---
 roles/matrix-etherpad/tasks/setup_uninstall.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/roles/matrix-etherpad/tasks/setup_uninstall.yml b/roles/matrix-etherpad/tasks/setup_uninstall.yml
index 865389f2d..8f40f420e 100644
--- a/roles/matrix-etherpad/tasks/setup_uninstall.yml
+++ b/roles/matrix-etherpad/tasks/setup_uninstall.yml
@@ -29,7 +29,7 @@
     path: "{{ matrix_etherpad_base_path }}"
     state: absent
 
-- name: Ensure Dimension Docker image doesn't exist
+- name: Ensure Etherpad Docker image doesn't exist
   docker_image:
     name: "{{ matrix_etherpad_docker_image }}"
     state: absent

From e0e459ac0c09d9618ab73c194dec0a996443cc15 Mon Sep 17 00:00:00 2001
From: Peetz0r <github@haas-en-berg.nl>
Date: Sat, 30 Jan 2021 11:53:02 +0100
Subject: [PATCH 15/66] Fixed missing quotes

---
 roles/matrix-base/tasks/server_base/setup_debian.yml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/roles/matrix-base/tasks/server_base/setup_debian.yml b/roles/matrix-base/tasks/server_base/setup_debian.yml
index 42b6f30c3..54e52c1b8 100644
--- a/roles/matrix-base/tasks/server_base/setup_debian.yml
+++ b/roles/matrix-base/tasks/server_base/setup_debian.yml
@@ -23,14 +23,14 @@
     repo: "deb [arch={{ matrix_debian_arch }}] https://download.docker.com/linux/{{ ansible_distribution|lower }} {{ ansible_distribution_release }} stable"
     state: present
     update_cache: yes
-  when: matrix_docker_installation_enabled|bool and matrix_docker_package_name == 'docker-ce and not ansible_distribution_release == 'bullseye'
+  when: matrix_docker_installation_enabled|bool and matrix_docker_package_name == 'docker-ce' and not ansible_distribution_release == 'bullseye'
 
 - name: Ensure Docker repository is enabled (using Debian Buster on Debian Bullseye, for which there is no Docker yet)
   apt_repository:
     repo: "deb [arch={{ matrix_debian_arch }}] https://download.docker.com/linux/{{ ansible_distribution|lower }} buster stable"
     state: present
     update_cache: yes
-  when: matrix_docker_installation_enabled|bool and matrix_docker_package_name == 'docker-ce and ansible_distribution_release == 'bullseye'
+  when: matrix_docker_installation_enabled|bool and matrix_docker_package_name == 'docker-ce' and ansible_distribution_release == 'bullseye'
 
 - name: Ensure APT packages are installed
   apt:

From 8de739132a9e52170380d3d5f1a01034abacd82c Mon Sep 17 00:00:00 2001
From: Thom Wiggers <thom@thomwiggers.nl>
Date: Sat, 30 Jan 2021 12:47:56 +0100
Subject: [PATCH 16/66] Update IRC bridge to 0.23.0

---
 roles/matrix-bridge-appservice-irc/defaults/main.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/roles/matrix-bridge-appservice-irc/defaults/main.yml b/roles/matrix-bridge-appservice-irc/defaults/main.yml
index ba4e1e1b2..a6a45f5d9 100644
--- a/roles/matrix-bridge-appservice-irc/defaults/main.yml
+++ b/roles/matrix-bridge-appservice-irc/defaults/main.yml
@@ -7,7 +7,7 @@ matrix_appservice_irc_container_self_build: false
 matrix_appservice_irc_docker_repo: "https://github.com/matrix-org/matrix-appservice-irc.git"
 matrix_appservice_irc_docker_src_files_path: "{{ matrix_base_data_path }}/appservice-irc/docker-src"
 
-matrix_appservice_irc_docker_image: "docker.io/matrixdotorg/matrix-appservice-irc:release-0.17.1"
+matrix_appservice_irc_docker_image: "docker.io/matrixdotorg/matrix-appservice-irc:release-0.23.0"
 matrix_appservice_irc_docker_image_force_pull: "{{ matrix_appservice_irc_docker_image.endswith(':latest') }}"
 
 matrix_appservice_irc_base_path: "{{ matrix_base_data_path }}/appservice-irc"

From 0a0c9a4efc85c7382f92a31067dc299f1d18419e Mon Sep 17 00:00:00 2001
From: o8F0LY <61626020+o8F0LY@users.noreply.github.com>
Date: Sat, 30 Jan 2021 22:54:51 +0100
Subject: [PATCH 17/66] Add double quotes to avoid synatx errors

---
 .../sql/init-additional-db-user-and-role.sql.j2        | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/roles/matrix-postgres/templates/sql/init-additional-db-user-and-role.sql.j2 b/roles/matrix-postgres/templates/sql/init-additional-db-user-and-role.sql.j2
index 609a13448..a5a3385b6 100644
--- a/roles/matrix-postgres/templates/sql/init-additional-db-user-and-role.sql.j2
+++ b/roles/matrix-postgres/templates/sql/init-additional-db-user-and-role.sql.j2
@@ -2,18 +2,18 @@
 -- Seen here: https://stackoverflow.com/a/49858797
 DO $$
 BEGIN
-  CREATE USER {{ additional_db.username }};
+  CREATE USER "{{ additional_db.username }}";
   EXCEPTION WHEN DUPLICATE_OBJECT THEN
-  RAISE NOTICE 'not creating user {{ additional_db.username }}, since it already exists';
+  RAISE NOTICE 'not creating user "{{ additional_db.username }}", since it already exists';
 END
 $$;
 
 -- This is useful for initial user creation (since we don't assign a password above) and for handling subsequent password changes
 -- TODO - we should escape quotes in the password.
-ALTER ROLE {{ additional_db.username }} PASSWORD '{{ additional_db.password }}';
+ALTER ROLE "{{ additional_db.username }}" PASSWORD '{{ additional_db.password }}';
 
 -- This will generate an error on subsequent execution
-CREATE DATABASE {{ additional_db.name }} WITH LC_CTYPE 'C' LC_COLLATE 'C' OWNER {{ additional_db.username }};
+CREATE DATABASE "{{ additional_db.name }}" WITH LC_CTYPE 'C' LC_COLLATE 'C' OWNER "{{ additional_db.username }}";
 
 -- This is useful for changing the database owner subsequently
-ALTER DATABASE {{ additional_db.name }} OWNER TO {{ additional_db.username }};
+ALTER DATABASE "{{ additional_db.name }}" OWNER TO "{{ additional_db.username }}";

From 7804060eee3a7b6437c767980d2edd605799ced7 Mon Sep 17 00:00:00 2001
From: Slavi Pantaleev <slavi@devture.com>
Date: Sun, 31 Jan 2021 09:47:47 +0200
Subject: [PATCH 18/66] Use Etherpad 1.8.7, not :latest

---
 roles/matrix-etherpad/defaults/main.yml | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/roles/matrix-etherpad/defaults/main.yml b/roles/matrix-etherpad/defaults/main.yml
index 19a79bd14..28bb0c8d3 100644
--- a/roles/matrix-etherpad/defaults/main.yml
+++ b/roles/matrix-etherpad/defaults/main.yml
@@ -2,7 +2,7 @@ matrix_etherpad_enabled: false
 
 matrix_etherpad_base_path: "{{ matrix_base_data_path }}/etherpad"
 
-matrix_etherpad_docker_image: "docker.io/etherpad/etherpad:latest"
+matrix_etherpad_docker_image: "docker.io/etherpad/etherpad:1.8.7"
 matrix_etherpad_docker_image_force_pull: "{{ matrix_etherpad_docker_image.endswith(':latest') }}"
 
 # List of systemd services that matrix-etherpad.service depends on.
@@ -53,9 +53,9 @@ matrix_etherpad_database_connection_string: 'postgres://{{ matrix_etherpad_datab
 matrix_etherpad_title: 'Etherpad'
 matrix_etherpad_default_pad_text: |
   Welcome to Etherpad!
-  
+
   This pad text is synchronized as you type, so that everyone viewing this page sees the same text. This allows you to collaborate seamlessly on documents!
-  
+
   Get involved with Etherpad at https://etherpad.org
 
 # Default Etherpad configuration template which covers the generic use case.

From 5df2f6cdd1ff9a79d9998ca57cf320ea2f43d30b Mon Sep 17 00:00:00 2001
From: Slavi Pantaleev <slavi@devture.com>
Date: Sun, 31 Jan 2021 09:54:12 +0200
Subject: [PATCH 19/66] Update docs and changelog

---
 CHANGELOG.md                          | 9 +++++++++
 docs/configuring-playbook-etherpad.md | 4 ++--
 docs/container-images.md              | 2 ++
 3 files changed, 13 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5ce03e797..1e23e58d2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,3 +1,12 @@
+# 2021-01-31
+
+## Etherpad support
+
+Thanks to [@pushytoxin](https://github.com/pushytoxin), the playbook can now install the [Etherpad](https://etherpad.org) realtime collaborative text editor. It can be used in a [Jitsi](https://jitsi.org/) audio/video call or integrated as a widget into Matrix chat rooms via the [Dimension](https://dimension.t2bot.io) integration manager.
+
+To get it installed, follow [our Etherpad docs page](docs/configuring-playbook-etherpad.md).
+
+
 # 2021-01-22
 
 ## (Breaking Change) Postgres changes that require manual intervention
diff --git a/docs/configuring-playbook-etherpad.md b/docs/configuring-playbook-etherpad.md
index 9ec24d33a..af1a9c7d7 100644
--- a/docs/configuring-playbook-etherpad.md
+++ b/docs/configuring-playbook-etherpad.md
@@ -2,13 +2,13 @@
 
 [Etherpad](https://etherpad.org) is is an open source collaborative text editor that can be embedded in a Matrix chat room using the [Dimension integrations manager](https://dimension.t2bot.io)
 
-When enabled together with Jitsi, it will be made available as an option during the conferences.
+When enabled together with the Jitsi audio/video conferencing system (see [our docs on Jitsi](configuring-playbook-jitsi.md)), it will be made available as an option during the conferences.
 
 ## Prerequisites
 
 For the self-hosted Etherpad instance to be available to your users, you must first enable and configure the **Dimension integrations manager** as described in [the playbook documentation](configuring-playbook-dimension.md)
 
-## Enable
+## Installing
 
 [Etherpad](https://etherpad.org) installation is disabled by default. You can enable it in your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
 
diff --git a/docs/container-images.md b/docs/container-images.md
index 33cfa7273..aee24b045 100644
--- a/docs/container-images.md
+++ b/docs/container-images.md
@@ -32,6 +32,8 @@ These services are not part of our default installation, but can be enabled by [
 
 - [ewoutp/goofys](https://hub.docker.com/r/ewoutp/goofys/) - the [Goofys](https://github.com/kahing/goofys) Amazon [S3](https://aws.amazon.com/s3/) file-system-mounting program (optional)
 
+- [etherpad/etherpad](https://hub.docker.com/r/etherpad/etherpad/) - the [Etherpad](https://etherpad.org) realtime collaborative text editor that can be used in a Jitsi audio/video call or integrated as a widget into Matrix chat rooms via the Dimension integration manager (optional)
+
 - [devture/email2matrix](https://hub.docker.com/r/devture/email2matrix/) - the [Email2Matrix](https://github.com/devture/email2matrix) email server, which can relay email messages to Matrix rooms (optional)
 
 - [devture/matrix-corporal](https://hub.docker.com/r/devture/matrix-corporal/) - [Matrix Corporal](https://github.com/devture/matrix-corporal): reconciliator and gateway for a managed Matrix server (optional)

From a8b61adb8dab3cbfa52a87b629cb8fadd54fa285 Mon Sep 17 00:00:00 2001
From: Aaron Raimist <aaron@raim.ist>
Date: Mon, 1 Feb 2021 03:22:04 -0600
Subject: [PATCH 20/66] Clarify hosts file wording

---
 examples/hosts | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/examples/hosts b/examples/hosts
index daf2cfc5b..ba08107b9 100644
--- a/examples/hosts
+++ b/examples/hosts
@@ -9,10 +9,11 @@
 # to the host line below or by adding `ansible_ssh_pipelining: False` to your variables file.
 #
 # If you're running this Ansible playbook on the same server as the one you're installing to,
-# consider adding an additional `ansible_connection=local` argument below.
+# consider adding an additional `ansible_connection=local` argument to the host line below.
 #
 # Ansible may fail to discover which Python interpreter to use on the host for some distros (like Ubuntu 20.04).
-# You may sometimes need to explicitly add `ansible_python_interpreter=/usr/bin/python3` to lines below.
+# You may sometimes need to explicitly add the argument `ansible_python_interpreter=/usr/bin/python3`
+# to the host line below.
 
 [matrix_servers]
 matrix.<your-domain> ansible_host=<your-server's external IP address> ansible_ssh_user=root

From c4a05b760ad6d4ab33aab36d64252a03b754dc6c Mon Sep 17 00:00:00 2001
From: Slavi Pantaleev <slavi@devture.com>
Date: Wed, 3 Feb 2021 13:22:05 +0200
Subject: [PATCH 21/66] Make mautrix bridges not overwrite their config

If they do, our next playbook runs would simply revert it
and report "changed" for that task.

There's no benefit to letting the bridge spew a new config file.

This does not apply to the mautrix whatsapp bridge, because that one
is written in Go (not Python) and takes different flags. There's no
equivalent flag there.
---
 .../templates/systemd/matrix-mautrix-facebook.service.j2        | 2 +-
 .../templates/systemd/matrix-mautrix-hangouts.service.j2        | 2 +-
 .../templates/systemd/matrix-mautrix-signal.service.j2          | 2 +-
 .../templates/systemd/matrix-mautrix-telegram.service.j2        | 2 +-
 4 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/roles/matrix-bridge-mautrix-facebook/templates/systemd/matrix-mautrix-facebook.service.j2 b/roles/matrix-bridge-mautrix-facebook/templates/systemd/matrix-mautrix-facebook.service.j2
index 95f0e3da7..acd2c885f 100644
--- a/roles/matrix-bridge-mautrix-facebook/templates/systemd/matrix-mautrix-facebook.service.j2
+++ b/roles/matrix-bridge-mautrix-facebook/templates/systemd/matrix-mautrix-facebook.service.j2
@@ -44,7 +44,7 @@ ExecStart={{ matrix_host_command_docker }} run --rm --name matrix-mautrix-facebo
 			{{ arg }} \
 			{% endfor %}
 			{{ matrix_mautrix_facebook_docker_image }} \
-			python3 -m mautrix_facebook -c /config/config.yaml
+			python3 -m mautrix_facebook -c /config/config.yaml --no-update
 
 ExecStop=-{{ matrix_host_command_sh }} -c '{{ matrix_host_command_docker }} kill matrix-mautrix-facebook 2>/dev/null'
 ExecStop=-{{ matrix_host_command_sh }} -c '{{ matrix_host_command_docker }} rm matrix-mautrix-facebook 2>/dev/null'
diff --git a/roles/matrix-bridge-mautrix-hangouts/templates/systemd/matrix-mautrix-hangouts.service.j2 b/roles/matrix-bridge-mautrix-hangouts/templates/systemd/matrix-mautrix-hangouts.service.j2
index 9d69bd84b..60f0e055f 100644
--- a/roles/matrix-bridge-mautrix-hangouts/templates/systemd/matrix-mautrix-hangouts.service.j2
+++ b/roles/matrix-bridge-mautrix-hangouts/templates/systemd/matrix-mautrix-hangouts.service.j2
@@ -42,7 +42,7 @@ ExecStart={{ matrix_host_command_docker }} run --rm --name matrix-mautrix-hangou
 			{{ arg }} \
 			{% endfor %}
 			{{ matrix_mautrix_hangouts_docker_image }} \
-			python3 -m mautrix_hangouts -c /config/config.yaml
+			python3 -m mautrix_hangouts -c /config/config.yaml --no-update
 
 ExecStop=-{{ matrix_host_command_sh }} -c '{{ matrix_host_command_docker }} kill matrix-mautrix-hangouts 2>/dev/null'
 ExecStop=-{{ matrix_host_command_sh }} -c '{{ matrix_host_command_docker }} rm matrix-mautrix-hangouts 2>/dev/null'
diff --git a/roles/matrix-bridge-mautrix-signal/templates/systemd/matrix-mautrix-signal.service.j2 b/roles/matrix-bridge-mautrix-signal/templates/systemd/matrix-mautrix-signal.service.j2
index 0c513a222..e3e024247 100644
--- a/roles/matrix-bridge-mautrix-signal/templates/systemd/matrix-mautrix-signal.service.j2
+++ b/roles/matrix-bridge-mautrix-signal/templates/systemd/matrix-mautrix-signal.service.j2
@@ -35,7 +35,7 @@ ExecStart={{ matrix_host_command_docker }} run --rm --name matrix-mautrix-signal
 			{{ arg }} \
 			{% endfor %}
 			{{ matrix_mautrix_signal_docker_image }} \
-			python3 -m mautrix_signal -c /config/config.yaml
+			python3 -m mautrix_signal -c /config/config.yaml --no-update
 
 ExecStop=-{{ matrix_host_command_sh }} -c '{{ matrix_host_command_docker }} kill matrix-mautrix-signal 2>/dev/null'
 ExecStop=-{{ matrix_host_command_sh }} -c '{{ matrix_host_command_docker }} rm matrix-mautrix-signal 2>/dev/null'
diff --git a/roles/matrix-bridge-mautrix-telegram/templates/systemd/matrix-mautrix-telegram.service.j2 b/roles/matrix-bridge-mautrix-telegram/templates/systemd/matrix-mautrix-telegram.service.j2
index 18bd15bad..ae1ac675b 100644
--- a/roles/matrix-bridge-mautrix-telegram/templates/systemd/matrix-mautrix-telegram.service.j2
+++ b/roles/matrix-bridge-mautrix-telegram/templates/systemd/matrix-mautrix-telegram.service.j2
@@ -42,7 +42,7 @@ ExecStart={{ matrix_host_command_docker }} run --rm --name matrix-mautrix-telegr
 			{{ arg }} \
 			{% endfor %}
 			{{ matrix_mautrix_telegram_docker_image }} \
-			python3 -m mautrix_telegram -c /config/config.yaml
+			python3 -m mautrix_telegram -c /config/config.yaml --no-update
 
 ExecStop=-{{ matrix_host_command_sh }} -c '{{ matrix_host_command_docker }} kill matrix-mautrix-telegram 2>/dev/null'
 ExecStop=-{{ matrix_host_command_sh }} -c '{{ matrix_host_command_docker }} rm matrix-mautrix-telegram 2>/dev/null'

From d1f28d17bb0da8c5fe3a28c39ba618e1b9316897 Mon Sep 17 00:00:00 2001
From: Julian Foad <julian@foad.me.uk>
Date: Wed, 3 Feb 2021 12:52:15 +0000
Subject: [PATCH 22/66] Allow psql args to be given to matrix-postgres-cli

This passes any arguments given to 'matrix-postgres-cli' to the 'psql' command.

Examples:
  $ # start an interactive shell connected to a given db
  $ sudo matrix-postgres-cli -d synapse
  $ # run a query, non-interactively
  $ sudo matrix-postgres-cli -d synapse -c 'SELECT group_id FROM groups;'
---
 .../templates/usr-local-bin/matrix-postgres-cli.j2             | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/roles/matrix-postgres/templates/usr-local-bin/matrix-postgres-cli.j2 b/roles/matrix-postgres/templates/usr-local-bin/matrix-postgres-cli.j2
index 61f4cf80a..de09a4eb2 100644
--- a/roles/matrix-postgres/templates/usr-local-bin/matrix-postgres-cli.j2
+++ b/roles/matrix-postgres/templates/usr-local-bin/matrix-postgres-cli.j2
@@ -9,4 +9,5 @@ docker run \
 	--env-file={{ matrix_postgres_base_path }}/env-postgres-psql \
 	--network {{ matrix_docker_network }} \
 	{{ matrix_postgres_docker_image_to_use }} \
-	psql -h {{ matrix_postgres_connection_hostname }}
+	psql -h {{ matrix_postgres_connection_hostname }} \
+	"$@"

From b8ac0895621de89e76c6f8d4821493f62ab11716 Mon Sep 17 00:00:00 2001
From: Julian Foad <julian@foad.me.uk>
Date: Wed, 3 Feb 2021 13:11:27 +0000
Subject: [PATCH 23/66] Fix wrong links in mautrix-signal docs

---
 docs/configuring-playbook-bridge-mautrix-signal.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/configuring-playbook-bridge-mautrix-signal.md b/docs/configuring-playbook-bridge-mautrix-signal.md
index 164b06de8..6d3c4dfbd 100644
--- a/docs/configuring-playbook-bridge-mautrix-signal.md
+++ b/docs/configuring-playbook-bridge-mautrix-signal.md
@@ -14,7 +14,7 @@ matrix_mautrix_signal_enabled: true
 
 ## Set up Double Puppeting
 
-If you'd like to use [Double Puppeting](https://github.com/tulir/mautrix-whatsapp/wiki/Authentication#replacing-whatsapp-accounts-matrix-puppet-with-matrix-account) (hint: you most likely do), you have 2 ways of going about it.
+If you'd like to use [Double Puppeting](https://github.com/tulir/mautrix-signal/wiki/Authentication#double-puppeting) (hint: you most likely do), you have 2 ways of going about it.
 
 ### Method 1: automatically, by enabling Shared Secret Auth
 

From 47784d465a0771e4c7ba6be2461e269133a959e2 Mon Sep 17 00:00:00 2001
From: Aaron Raimist <aaron@raim.ist>
Date: Wed, 3 Feb 2021 09:50:58 -0600
Subject: [PATCH 24/66] Remove note about federation tester not working with
 TLS 1.3

---
 docs/configuring-playbook-nginx.md | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/docs/configuring-playbook-nginx.md b/docs/configuring-playbook-nginx.md
index ba6c5c125..3c0bad5bd 100644
--- a/docs/configuring-playbook-nginx.md
+++ b/docs/configuring-playbook-nginx.md
@@ -34,8 +34,7 @@ Possible values are:
 - `"intermediate"` (**default**) - Recommended configuration for a general-purpose server
 - `"old"` - Services accessed by very old clients or libraries, such as Internet Explorer 8 (Windows XP), Java 6, or OpenSSL 0.9.8
 
-**Be really carefull when setting it to `"modern"`**. This could break comunication with other Matrix servers, limiting your federation posibilities. The
-[Federarion tester](https://federationtester.matrix.org/) also won't work.
+**Be really carefull when setting it to `"modern"`**. This could break comunication with other Matrix servers, limiting your federation posibilities.
 
 Besides changing the preset (`matrix_nginx_proxy_ssl_preset`), you can also directly override these 3 variables:
 

From 5cb976c321fd1a9d6c7d8538892001dc8d5ebfff Mon Sep 17 00:00:00 2001
From: Aaron Raimist <aaron@raim.ist>
Date: Wed, 3 Feb 2021 10:07:43 -0600
Subject: [PATCH 25/66] Upgrade Element (1.7.18 -> 1.7.19)

---
 roles/matrix-client-element/defaults/main.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/roles/matrix-client-element/defaults/main.yml b/roles/matrix-client-element/defaults/main.yml
index e8678b49c..5e1300a41 100644
--- a/roles/matrix-client-element/defaults/main.yml
+++ b/roles/matrix-client-element/defaults/main.yml
@@ -3,7 +3,7 @@ matrix_client_element_enabled: true
 matrix_client_element_container_image_self_build: false
 matrix_client_element_container_image_self_build_repo: "https://github.com/vector-im/riot-web.git"
 
-matrix_client_element_docker_image: "{{ matrix_client_element_docker_image_name_prefix }}vectorim/element-web:v1.7.18"
+matrix_client_element_docker_image: "{{ matrix_client_element_docker_image_name_prefix }}vectorim/element-web:v1.7.19"
 matrix_client_element_docker_image_name_prefix: "{{ 'localhost/' if matrix_client_element_container_image_self_build else 'docker.io/' }}"
 matrix_client_element_docker_image_force_pull: "{{ matrix_client_element_docker_image.endswith(':latest') }}"
 

From 9ad67d7cdf057acdadd16c088f71a8489cde5f37 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Paul=20T=C3=B6tterman?= <ptman@users.noreply.github.com>
Date: Thu, 4 Feb 2021 16:26:56 +0200
Subject: [PATCH 26/66]  Upgrade Element (1.7.19 -> 1.7.20)

https://github.com/vector-im/element-web/releases/tag/v1.7.20
https://hub.docker.com/layers/vectorim/element-web/v1.7.20/images/sha256-44cae3a532d86c16940deb70866b522ba6acc8c5d7adf3c661cfc8b06f1de681?context=explore
---
 roles/matrix-client-element/defaults/main.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/roles/matrix-client-element/defaults/main.yml b/roles/matrix-client-element/defaults/main.yml
index 5e1300a41..f2c464437 100644
--- a/roles/matrix-client-element/defaults/main.yml
+++ b/roles/matrix-client-element/defaults/main.yml
@@ -3,7 +3,7 @@ matrix_client_element_enabled: true
 matrix_client_element_container_image_self_build: false
 matrix_client_element_container_image_self_build_repo: "https://github.com/vector-im/riot-web.git"
 
-matrix_client_element_docker_image: "{{ matrix_client_element_docker_image_name_prefix }}vectorim/element-web:v1.7.19"
+matrix_client_element_docker_image: "{{ matrix_client_element_docker_image_name_prefix }}vectorim/element-web:v1.7.20"
 matrix_client_element_docker_image_name_prefix: "{{ 'localhost/' if matrix_client_element_container_image_self_build else 'docker.io/' }}"
 matrix_client_element_docker_image_force_pull: "{{ matrix_client_element_docker_image.endswith(':latest') }}"
 

From 064b2e533ccb1e3db9b9d1a0df075c6978ba8033 Mon Sep 17 00:00:00 2001
From: Stuart Thomson <me@sthom.kiwi>
Date: Sat, 6 Feb 2021 20:02:39 +1300
Subject: [PATCH 27/66] Add variable for extra domains to get LE certs for

I felt that adding another variable was probably going to be the easiest way to do this. I may end up adding another variable to enable this feature, for consistency with some of the other things.
---
 group_vars/matrix_servers                  | 2 ++
 roles/matrix-nginx-proxy/defaults/main.yml | 1 +
 2 files changed, 3 insertions(+)

diff --git a/group_vars/matrix_servers b/group_vars/matrix_servers
index 5d76a60cc..17181531f 100755
--- a/group_vars/matrix_servers
+++ b/group_vars/matrix_servers
@@ -1025,6 +1025,8 @@ matrix_ssl_domains_to_obtain_certificates_for: |
     ([matrix_server_fqn_jitsi] if matrix_jitsi_enabled else [])
     +
     ([matrix_domain] if matrix_nginx_proxy_base_domain_serving_enabled else [])
+    +
+    matrix_ssl_additional_domains_to_obtain_certificates_for
   }}
 
 matrix_ssl_architecture: "{{
diff --git a/roles/matrix-nginx-proxy/defaults/main.yml b/roles/matrix-nginx-proxy/defaults/main.yml
index 5eedb4cec..cb066277f 100644
--- a/roles/matrix-nginx-proxy/defaults/main.yml
+++ b/roles/matrix-nginx-proxy/defaults/main.yml
@@ -292,6 +292,7 @@ matrix_ssl_architecture: "amd64"
 
 # The list of domains that this role will obtain certificates for.
 matrix_ssl_domains_to_obtain_certificates_for: []
+matrix_ssl_additional_domains_to_obtain_certificates_for: []
 
 # Controls whether to obtain production or staging certificates from Let's Encrypt.
 matrix_ssl_lets_encrypt_staging: false

From f7bea5bb05ecf97e087bb4e164ed636717f81d1a Mon Sep 17 00:00:00 2001
From: Stuart Thomson <me@sthom.kiwi>
Date: Sat, 6 Feb 2021 20:31:24 +1300
Subject: [PATCH 28/66] Add documentation for new variable

---
 docs/configuring-playbook-nginx.md | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/docs/configuring-playbook-nginx.md b/docs/configuring-playbook-nginx.md
index 3c0bad5bd..c47887101 100644
--- a/docs/configuring-playbook-nginx.md
+++ b/docs/configuring-playbook-nginx.md
@@ -59,3 +59,17 @@ This will disable the access logging for nginx.
 ```yaml
 matrix_nginx_proxy_access_log_enabled: false
 ```
+
+## Additional configuration
+
+<!-- TODO: Introductory blurb -->
+
+<!-- TODO: Add section for including config files, however that's done -->
+
+Make sure that you have set the DNS configuration for the domains you want to include to point at your server.
+
+```yaml
+matrix_ssl_additional_domains_to_obtain_certificates_for:
+  - domain.one.example
+  - domain.two.example
+```

From d416b0cebee888d74290c4526731303df8b5cb0d Mon Sep 17 00:00:00 2001
From: pushytoxin <github@becker.rocks>
Date: Sat, 6 Feb 2021 12:45:54 +0100
Subject: [PATCH 29/66] Etherpad docs: Padname length bug

Warn users of the known bug https://github.com/turt2live/matrix-dimension/issues/395
---
 docs/configuring-playbook-etherpad.md | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/docs/configuring-playbook-etherpad.md b/docs/configuring-playbook-etherpad.md
index af1a9c7d7..e5533e717 100644
--- a/docs/configuring-playbook-etherpad.md
+++ b/docs/configuring-playbook-etherpad.md
@@ -24,3 +24,8 @@ The Dimension administrator users can configure the default URL template. The Di
 
 If you wish to disable the Etherpad chat button, you can do it by appending `?showChat=false` to the end of the pad URL, or the template.
 Example: `https://dimension.<your-domain>/etherpad/p/$roomId_$padName?showChat=false`
+
+## Known issues
+
+If your Etherpad widget fails to load, this might be due to Dimension generating a Pad name so long, the Etherpad app rejects it.
+`$roomId_$padName` can end up being longer than 50 characters. You can avoid having this problem by altering the template so it only contains the three word random identifier `$padName`.

From 093ecba40503a91b2d116c1c8140398da121e1a6 Mon Sep 17 00:00:00 2001
From: Stuart Thomson <me@sthom.kiwi>
Date: Sun, 7 Feb 2021 16:09:20 +1300
Subject: [PATCH 30/66] Add more documentation

---
 docs/configuring-playbook-nginx.md | 17 +++++++++++++----
 1 file changed, 13 insertions(+), 4 deletions(-)

diff --git a/docs/configuring-playbook-nginx.md b/docs/configuring-playbook-nginx.md
index c47887101..91bed77cb 100644
--- a/docs/configuring-playbook-nginx.md
+++ b/docs/configuring-playbook-nginx.md
@@ -62,14 +62,23 @@ matrix_nginx_proxy_access_log_enabled: false
 
 ## Additional configuration
 
-<!-- TODO: Introductory blurb -->
+This playbook also allows for additional configuration to be applied to the nginx server.
 
-<!-- TODO: Add section for including config files, however that's done -->
-
-Make sure that you have set the DNS configuration for the domains you want to include to point at your server.
+If you want this playbook to obtain and renew certificates for other domains, then you can set the `matrix_ssl_additional_domains_to_obtain_certificates_for` variable. Make sure that you have set the DNS configuration for the domains you want to include to point at your server.
 
 ```yaml
 matrix_ssl_additional_domains_to_obtain_certificates_for:
   - domain.one.example
   - domain.two.example
 ```
+
+You can include additional nginx configuration by setting the `matrix_nginx_proxy_proxy_http_additional_server_configuration_blocks` variable. 
+
+```yaml
+matrix_nginx_proxy_proxy_http_additional_server_configuration_blocks:
+  - |
+    # These lines will be included in the nginx configuration.
+    # This is at the top level of the file, so you will need to define all of the `server { ... }` blocks.
+  - |
+    # For advanced use, have a look at the template files in `roles/matrix-nginx-proxy/templates/nginx/conf.d`
+```

From 479d8b3e44394f1fa6fe9b6543c1756d05e086c5 Mon Sep 17 00:00:00 2001
From: buxel <buxel.dev@gmail.com>
Date: Mon, 8 Feb 2021 11:35:31 +0100
Subject: [PATCH 31/66] Update configuring-dns.md

Added note about cloudflare, related to #821
---
 docs/configuring-dns.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/docs/configuring-dns.md b/docs/configuring-dns.md
index 9d7384772..cef4cd501 100644
--- a/docs/configuring-dns.md
+++ b/docs/configuring-dns.md
@@ -29,6 +29,7 @@ If you decide to go with the alternative method ([Server Delegation via a DNS SR
 
 DNS records marked with `(*)` above are optional. They refer to services that will not be installed by default (see the section below). If you won't be installing these services, feel free to skip creating these DNS records. Also be mindful as to how long it will take for the DNS records to propagate.
 
+>  If you are using Cloudflare DNS, make sure to disable the proxy and set all records to `DNS only`. Otherwise, fetching certificates will fail.
 
 ## Subdomains setup
 

From 599ff34be98a42bdc43321b078cf27bb68d9c56c Mon Sep 17 00:00:00 2001
From: Yan <t@c-base.org>
Date: Mon, 8 Feb 2021 18:22:59 +0100
Subject: [PATCH 32/66] fix typo from skype to slack

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index bffe92662..91f9314dc 100644
--- a/README.md
+++ b/README.md
@@ -67,7 +67,7 @@ Using this playbook, you can get the following services configured on your serve
 
 - (optional) the [mx-puppet-skype](https://hub.docker.com/r/sorunome/mx-puppet-skype) for bridging your Matrix server to [Skype](https://www.skype.com) - see [docs/configuring-playbook-bridge-mx-puppet-skype.md](docs/configuring-playbook-bridge-mx-puppet-skype.md) for setup documentation
 
-- (optional) the [mx-puppet-slack](https://hub.docker.com/r/sorunome/mx-puppet-skype) for bridging your Matrix server to [Slack](https://slack.com) - see [docs/configuring-playbook-bridge-mx-puppet-slack.md](docs/configuring-playbook-bridge-mx-puppet-slack.md) for setup documentation
+- (optional) the [mx-puppet-slack](https://hub.docker.com/r/sorunome/mx-puppet-slack) for bridging your Matrix server to [Slack](https://slack.com) - see [docs/configuring-playbook-bridge-mx-puppet-slack.md](docs/configuring-playbook-bridge-mx-puppet-slack.md) for setup documentation
 
 - (optional) the [mx-puppet-instagram](https://github.com/Sorunome/mx-puppet-instagram) bridge for Instagram-DMs ([Instagram](https://www.instagram.com/)) - see [docs/configuring-playbook-bridge-mx-puppet-instagram.md](docs/configuring-playbook-bridge-mx-puppet-instagram.md) for setup documentation
 

From 385b6c623e6c4144d99760b851bb3fcf9ecbc148 Mon Sep 17 00:00:00 2001
From: Yan <t@c-base.org>
Date: Tue, 9 Feb 2021 00:02:48 +0100
Subject: [PATCH 33/66] Fixes: a66a604e ("Selfbuild appservice-slack bridge")

---
 roles/matrix-bridge-appservice-slack/tasks/setup_install.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/roles/matrix-bridge-appservice-slack/tasks/setup_install.yml b/roles/matrix-bridge-appservice-slack/tasks/setup_install.yml
index 721a5d6bd..703d3fabf 100644
--- a/roles/matrix-bridge-appservice-slack/tasks/setup_install.yml
+++ b/roles/matrix-bridge-appservice-slack/tasks/setup_install.yml
@@ -2,7 +2,7 @@
 
 - name: Ensure AppService Slack paths exist
   file:
-    path: "{{ item }}"
+    path: "{{ item.path }}"
     state: directory
     mode: 0750
     owner: "{{ matrix_user_username }}"

From 7e8e95a09a994dba9e02be0f8348862f85b9042c Mon Sep 17 00:00:00 2001
From: Slavi Pantaleev <slavi@devture.com>
Date: Tue, 9 Feb 2021 22:04:35 +0200
Subject: [PATCH 34/66] Make S3-mounting path configurable

This will make data migration easier.
---
 roles/matrix-synapse/defaults/main.yml                    | 1 +
 roles/matrix-synapse/tasks/goofys/setup_install.yml       | 8 ++++----
 .../templates/goofys/systemd/matrix-goofys.service.j2     | 4 ++--
 3 files changed, 7 insertions(+), 6 deletions(-)

diff --git a/roles/matrix-synapse/defaults/main.yml b/roles/matrix-synapse/defaults/main.yml
index 1b19bd7cf..62a8c3479 100644
--- a/roles/matrix-synapse/defaults/main.yml
+++ b/roles/matrix-synapse/defaults/main.yml
@@ -354,6 +354,7 @@ matrix_s3_media_store_bucket_name: "your-bucket-name"
 matrix_s3_media_store_aws_access_key: "your-aws-access-key"
 matrix_s3_media_store_aws_secret_key: "your-aws-secret-key"
 matrix_s3_media_store_region: "eu-central-1"
+matrix_s3_media_store_path: "{{ matrix_synapse_media_store_path }}"
 
 # Controls whether the self-check feature should validate SSL certificates.
 matrix_synapse_self_check_validate_certificates: true
diff --git a/roles/matrix-synapse/tasks/goofys/setup_install.yml b/roles/matrix-synapse/tasks/goofys/setup_install.yml
index 932379861..b5e956148 100644
--- a/roles/matrix-synapse/tasks/goofys/setup_install.yml
+++ b/roles/matrix-synapse/tasks/goofys/setup_install.yml
@@ -8,18 +8,18 @@
 # This will throw a Permission Denied error if already mounted
 - name: Check Matrix Goofys external storage mountpoint path
   stat:
-    path: "{{ matrix_synapse_media_store_path }}"
-  register: local_path_matrix_synapse_media_store_path_stat
+    path: "{{ matrix_s3_media_store_path }}"
+  register: local_path_matrix_s3_media_store_path_stat
   ignore_errors: yes
 
 - name: Ensure Matrix Goofys external storage mountpoint exists
   file:
-    path: "{{ matrix_synapse_media_store_path }}"
+    path: "{{ matrix_s3_media_store_path }}"
     state: directory
     mode: 0750
     owner: "{{ matrix_user_username }}"
     group: "{{ matrix_user_groupname }}"
-  when: "not local_path_matrix_synapse_media_store_path_stat.failed and not local_path_matrix_synapse_media_store_path_stat.stat.exists"
+  when: "not local_path_matrix_s3_media_store_path_stat.failed and not local_path_matrix_s3_media_store_path_stat.stat.exists"
 
 - name: Ensure goofys environment variables file created
   template:
diff --git a/roles/matrix-synapse/templates/goofys/systemd/matrix-goofys.service.j2 b/roles/matrix-synapse/templates/goofys/systemd/matrix-goofys.service.j2
index d96ab4a68..df4a4f23a 100644
--- a/roles/matrix-synapse/templates/goofys/systemd/matrix-goofys.service.j2
+++ b/roles/matrix-synapse/templates/goofys/systemd/matrix-goofys.service.j2
@@ -16,7 +16,7 @@ ExecStart={{ matrix_host_command_docker }} run --rm --name %n \
 			--user={{ matrix_user_uid }}:{{ matrix_user_gid }} \
 			--mount type=bind,src=/etc/passwd,dst=/etc/passwd,ro \
 			--mount type=bind,src=/etc/group,dst=/etc/group,ro \
-			--mount type=bind,src={{ matrix_synapse_media_store_path }},dst=/s3,bind-propagation=shared \
+			--mount type=bind,src={{ matrix_s3_media_store_path }},dst=/s3,bind-propagation=shared \
 			--security-opt apparmor:unconfined \
 			--cap-add mknod \
 			--cap-add sys_admin \
@@ -30,7 +30,7 @@ TimeoutStartSec=5min
 ExecStop=-{{ matrix_host_command_docker }} stop %n
 ExecStop=-{{ matrix_host_command_docker }} kill %n
 ExecStop=-{{ matrix_host_command_docker }} rm %n
-ExecStop=-{{ matrix_host_command_fusermount }} -u {{ matrix_synapse_media_store_path }}
+ExecStop=-{{ matrix_host_command_fusermount }} -u {{ matrix_s3_media_store_path }}
 Restart=always
 RestartSec=5
 SyslogIdentifier=matrix-goofys

From 96e6111aa62fe29b251c8fe9c1dd2d4c473375da Mon Sep 17 00:00:00 2001
From: Slavi Pantaleev <slavi@devture.com>
Date: Tue, 9 Feb 2021 22:09:08 +0200
Subject: [PATCH 35/66] Improve S3 docs around data migration

---
 docs/configuring-playbook-s3.md | 135 ++++++++++++++++++++++++++++++++
 1 file changed, 135 insertions(+)

diff --git a/docs/configuring-playbook-s3.md b/docs/configuring-playbook-s3.md
index 643edb5b2..9132ff718 100644
--- a/docs/configuring-playbook-s3.md
+++ b/docs/configuring-playbook-s3.md
@@ -6,6 +6,11 @@ If that's alright, you can skip this.
 If you'd like to store Synapse's content repository (`media_store`) files on Amazon S3 (or other S3-compatible service),
 you can let this playbook configure [Goofys](https://github.com/kahing/goofys) for you.
 
+Using a Goofys-backed media store works, but performance may not be ideal. If possible, try to use a region which is close to your Matrix server.
+
+If you'd like to move your locally-stored media store data to Amazon S3 (or another S3-compatible object store), we also provide some migration instructions below.
+
+
 ## Amazon S3
 
 You'll need an Amazon S3 bucket and some IAM user credentials (access key + secret key) with full write access to the bucket. Example security policy:
@@ -50,3 +55,133 @@ matrix_s3_media_store_custom_endpoint_enabled: true
 # Example: "https://storage.googleapis.com"
 matrix_s3_media_store_custom_endpoint: "your-custom-endpoint"
 ```
+
+### Backblaze B2
+
+To use [Backblaze B2](https://www.backblaze.com/b2/cloud-storage.html):
+
+- create a new **private** bucket through its user interface (you can call it something like `matrix-DOMAIN-media-store`)
+- note the **Endpoint** for your bucket (something like `s3.us-west-002.backblazeb2.com`)
+- adjust its lifecycle rules to use the following **custom** rules:
+  - File Path: *empty value*
+  - Days Till Hide: *empty value*
+  - Days Till Delete: `1`
+- go to [App Keys](https://secure.backblaze.com/app_keys.htm) and use the **Add a New Application Key** to create a new one
+  - restrict it to the previously created bucket (e.g. `matrix-DOMAIN-media-store`)
+  - give it *Read & Write* access
+
+Copy the `keyID` and `applicationKey`.
+
+You need the following *additional* playbook configuration (on top of what you see above):
+
+```yaml
+matrix_s3_media_store_bucket_name: "YOUR_BUCKET_NAME_GOES_HERE"
+matrix_s3_media_store_aws_access_key: "YOUR_keyID_GOES_HERE"
+matrix_s3_media_store_aws_secret_key: "YOUR_applicationKey_GOES_HERE"
+matrix_s3_media_store_custom_endpoint_enabled: true
+matrix_s3_media_store_custom_endpoint: "https://s3.us-west-002.backblazeb2.com" # this may be different for your bucket
+```
+
+If you have local media store files and wish to migrate to Backblaze B2 subsequently, follow our [migration guide to Backblaze B2](#migrating-to-backblaze-b2) below instead of applying this configuration as-is.
+
+
+## Migrating from local filesystem storage to S3
+
+It's a good idea to [make a complete server backup](faq.md#how-do-i-backup-the-data-on-my-server) before migrating your local media store to an S3-backed one.
+
+Follow one of the guides below for a migration path from a locally-stored media store to one stored on S3-compatible storage:
+
+- [Migrating to any S3-compatible storage (universal, but likely slow)](#migrating-to-any-s3-compatible-storage-universal-but-likely-slow)
+- [Migrating to Backblaze B2](#migrating-to-backblaze-b2)
+
+### Migrating to any S3-compatible storage (universal, but likely slow)
+
+It's a good idea to [make a complete server backup](faq.md#how-do-i-backup-the-data-on-my-server) before doing this.
+
+1. Proceed with the steps below without stopping Matrix services
+
+2. Start by adding the base S3 configuration in your `vars.yml` file (seen above, may be different depending on the S3 provider of your choice)
+
+3. In addition to the base configuration you see above, add this to your `vars.yml` file:
+
+```yaml
+matrix_s3_media_store_path: /matrix/s3-media-store
+```
+
+This enables S3 support, but mounts the S3 storage bucket to `/matrix/s3-media-store` without hooking it to your homeserver yet. Your homeserver will still continue using your local filesystem for its media store.
+
+5. Run the playbook to apply the changes: `ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start`
+
+6. Do an **initial sync of your files** by running this **on the server** (it may take a very long time):
+
+```sh
+sudo -u matrix -- rsync --size-only --ignore-existing -avr /matrix/synapse/storage/media-store/. /matrix/s3-media-store/.
+```
+
+You may need to install `rsync` manually.
+
+7. Stop all Matrix services (`ansible-playbook -i inventory/hosts setup.yml --tags=stop`)
+
+8. Start the S3 service by running this **on the server**: `systemctl start matrix-goofys`
+
+9. Sync the files again by re-running the `rsync` command you see in step #6
+
+10. Stop the S3 service by running this **on the server**: `systemctl stop matrix-goofys`
+
+11. Get the old media store out of the way by running this command on the server:
+
+```sh
+mv /matrix/synapse/storage/media-store /matrix/synapse/storage/media-store-local-backup
+```
+
+12. Remove the `matrix_s3_media_store_path` configuration from your `vars.yml` file (undoing step #3 above)
+
+13. Run the playbook: `ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start`
+
+14. You're done! Verify that loading existing (old) media files works and that you can upload new ones.
+
+15. When confident that it all works, get rid of the local media store directory: `rm -rf /matrix/synapse/storage/media-store-local-backup`
+
+
+### Migrating to Backblaze B2
+
+It's a good idea to [make a complete server backup](faq.md#how-do-i-backup-the-data-on-my-server) before doing this.
+
+1. While all Matrix services are running, run the following command on the server:
+
+(you need to adjust the 3 `--env` line below with your own data)
+
+```sh
+docker run -it --rm -w /work \
+--env='B2_KEY_ID=YOUR_KEY_GOES_HERE' \
+--env='B2_KEY_SECRET=YOUR_SECRET_GOES_HERE' \
+--env='B2_BUCKET_NAME=YOUR_BUCKET_NAME_GOES_HERE' \
+-v /matrix/synapse/storage/media-store/:/work \
+--entrypoint=/bin/sh \
+docker.io/tianon/backblaze-b2:2.1.0 \
+-c 'b2 authorize-account $B2_KEY_ID $B2_KEY_SECRET > /dev/null && b2 sync /work/ b2://$B2_BUCKET_NAME'
+```
+
+This is some initial file sync, which may take a very long time.
+
+2. Stop all Matrix services (`ansible-playbook -i inventory/hosts setup.yml --tags=stop`)
+
+3. Run the command from step #1 again.
+
+Doing this will sync any new files that may have been created locally in the meantime.
+
+Now that Matrix services aren't running, we're sure to get Backblaze B2 and your local media store fully in sync.
+
+4. Get the old media store out of the way by running this command on the server:
+
+```sh
+mv /matrix/synapse/storage/media-store /matrix/synapse/storage/media-store-local-backup
+```
+
+5. Put the [Backblaze B2 settings seen above](#backblaze-b2) in your `vars.yml` file
+
+6. Run the playbook: `ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start`
+
+7. You're done! Verify that loading existing (old) media files works and that you can upload new ones.
+
+8. When confident that it all works, get rid of the local media store directory: `rm -rf /matrix/synapse/storage/media-store-local-backup`

From 13ef9e85cf664a03942e3d38280238988a247a2f Mon Sep 17 00:00:00 2001
From: Peetz0r <github@haas-en-berg.nl>
Date: Fri, 29 Jan 2021 05:29:25 +0100
Subject: [PATCH 36/66] Prometheus

Initial attempt. Seems to work fine.

Only tested on debian amd64 so far
---
 group_vars/matrix_servers                     | 21 +++++
 roles/matrix-prometheus/defaults/main.yml     | 51 ++++++++++
 roles/matrix-prometheus/tasks/init.yml        |  5 +
 roles/matrix-prometheus/tasks/main.yml        | 14 +++
 roles/matrix-prometheus/tasks/setup.yml       | 93 +++++++++++++++++++
 .../tasks/validate_config.yml                 |  7 ++
 .../templates/prometheus.yml.j2               | 35 +++++++
 .../systemd/matrix-prometheus.service.j2      | 42 +++++++++
 setup.yml                                     |  1 +
 9 files changed, 269 insertions(+)
 create mode 100644 roles/matrix-prometheus/defaults/main.yml
 create mode 100644 roles/matrix-prometheus/tasks/init.yml
 create mode 100644 roles/matrix-prometheus/tasks/main.yml
 create mode 100644 roles/matrix-prometheus/tasks/setup.yml
 create mode 100644 roles/matrix-prometheus/tasks/validate_config.yml
 create mode 100644 roles/matrix-prometheus/templates/prometheus.yml.j2
 create mode 100644 roles/matrix-prometheus/templates/systemd/matrix-prometheus.service.j2

diff --git a/group_vars/matrix_servers b/group_vars/matrix_servers
index 5d76a60cc..833089a2f 100755
--- a/group_vars/matrix_servers
+++ b/group_vars/matrix_servers
@@ -1368,6 +1368,27 @@ matrix_synapse_admin_container_self_build: "{{ matrix_architecture != 'amd64' }}
 
 
 
+######################################################################
+#
+# matrix-prometheus
+#
+######################################################################
+
+matrix_prometheus_enabled: false
+
+# Normally, matrix-nginx-proxy is enabled and nginx can reach Prometheus over the container network.
+# If matrix-nginx-proxy is not enabled, or you otherwise have a need for it, you can expose
+# Prometheus' HTTP port to the local host.
+matrix_prometheus_container_http_host_bind_port: "{{ '' if matrix_nginx_proxy_enabled else '127.0.0.1:9090' }}"
+
+######################################################################
+#
+# /matrix-prometheus
+#
+######################################################################
+
+
+
 ######################################################################
 #
 # matrix-registration
diff --git a/roles/matrix-prometheus/defaults/main.yml b/roles/matrix-prometheus/defaults/main.yml
new file mode 100644
index 000000000..104244241
--- /dev/null
+++ b/roles/matrix-prometheus/defaults/main.yml
@@ -0,0 +1,51 @@
+# matrix-prometheus is an open-source systems monitoring and alerting toolkit
+# See: https://github.com/matrix-org/synapse/blob/master/docs/metrics-howto.md
+
+matrix_prometheus_enabled: false
+
+matrix_prometheus_docker_image: "docker.io/prom/prometheus:v2.24.1"
+matrix_prometheus_docker_image_force_pull: "{{ matrix_prometheus_docker_image.endswith(':latest') }}"
+
+matrix_synapse_prometheus_rules_download_url: "https://raw.githubusercontent.com/matrix-org/synapse/{{ matrix_synapse_docker_image_tag }}/contrib/prometheus/synapse-v2.rules"
+
+matrix_prometheus_base_path: "{{ matrix_base_data_path }}/prometheus"
+matrix_prometheus_config_path: "{{ matrix_prometheus_base_path }}/config"
+matrix_prometheus_data_path: "{{ matrix_prometheus_base_path }}/data"
+
+# A list of extra arguments to pass to the container
+matrix_prometheus_container_extra_arguments: []
+
+# List of systemd services that matrix-prometheus.service depends on
+matrix_prometheus_systemd_required_services_list: ['docker.service']
+
+# List of systemd services that matrix-prometheus.service wants
+matrix_prometheus_systemd_wanted_services_list: []
+
+# Controls whether the matrix-prometheus container exposes its HTTP port (tcp/9090 in the container).
+#
+# Takes an "<ip>:<port>" or "<port>" value (e.g. "127.0.0.1:9090"), or empty string to not expose.
+matrix_prometheus_container_http_host_bind_port: ''
+
+
+# Default prometheus configuration template which covers the generic use case.
+# You can customize it by controlling the various variables inside it.
+#
+# For a more advanced customization, you can extend the default (see `matrix_prometheus_configuration_extension_yaml`)
+# or completely replace this variable with your own template.
+matrix_prometheus_configuration_yaml: "{{ lookup('template', 'templates/prometheus.yml.j2') }}"
+
+matrix_prometheus_configuration_extension_yaml: |
+  # Your custom YAML configuration goes here.
+  # This configuration extends the default starting configuration (`matrix_prometheus_configuration_yaml`).
+  #
+  # You can override individual variables from the default configuration, or introduce new ones.
+  #
+  # If you need something more special, you can take full control by
+  # completely redefining `matrix_prometheus_configuration_yaml`.
+
+matrix_prometheus_configuration_extension: "{{ matrix_prometheus_configuration_extension_yaml|from_yaml if matrix_prometheus_configuration_extension_yaml|from_yaml is mapping else {} }}"
+
+# Holds the final configuration (a combination of the default and its extension).
+# You most likely don't need to touch this variable. Instead, see `matrix_prometheus_configuration_yaml`.
+matrix_prometheus_configuration: "{{ matrix_prometheus_configuration_yaml|from_yaml|combine(matrix_prometheus_configuration_extension, recursive=True) }}"
+
diff --git a/roles/matrix-prometheus/tasks/init.yml b/roles/matrix-prometheus/tasks/init.yml
new file mode 100644
index 000000000..12fae831a
--- /dev/null
+++ b/roles/matrix-prometheus/tasks/init.yml
@@ -0,0 +1,5 @@
+- set_fact:
+    matrix_systemd_services_list: "{{ matrix_systemd_services_list + ['matrix-prometheus.service'] }}"
+  when: matrix_prometheus_enabled|bool
+
+
diff --git a/roles/matrix-prometheus/tasks/main.yml b/roles/matrix-prometheus/tasks/main.yml
new file mode 100644
index 000000000..2290048f3
--- /dev/null
+++ b/roles/matrix-prometheus/tasks/main.yml
@@ -0,0 +1,14 @@
+- import_tasks: "{{ role_path }}/tasks/init.yml"
+  tags:
+    - always
+
+- import_tasks: "{{ role_path }}/tasks/validate_config.yml"
+  when: run_setup|bool
+  tags:
+    - setup-all
+    - setup-prometheus
+
+- import_tasks: "{{ role_path }}/tasks/setup.yml"
+  tags:
+    - setup-all
+    - setup-prometheus
diff --git a/roles/matrix-prometheus/tasks/setup.yml b/roles/matrix-prometheus/tasks/setup.yml
new file mode 100644
index 000000000..1746b9617
--- /dev/null
+++ b/roles/matrix-prometheus/tasks/setup.yml
@@ -0,0 +1,93 @@
+---
+
+#
+# Tasks related to setting up matrix-prometheus
+#
+
+- name: Ensure matrix-prometheus image is pulled
+  docker_image:
+    name: "{{ matrix_prometheus_docker_image }}"
+    source: "{{ 'pull' if ansible_version.major > 2 or ansible_version.minor > 7 else omit }}"
+    force_source: "{{ matrix_prometheus_docker_image_force_pull if ansible_version.major > 2 or ansible_version.minor >= 8 else omit }}"
+    force: "{{ omit if ansible_version.major > 2 or ansible_version.minor >= 8 else matrix_prometheus_docker_image_force_pull }}"
+  when: "matrix_prometheus_enabled|bool"
+
+- name: Ensure Prometheus paths exists
+  file:
+    path: "{{ item }}"
+    state: directory
+    mode: 0750
+    owner: "{{ matrix_user_username }}"
+    group: "{{ matrix_user_groupname }}"
+  with_items:
+    - "{{ matrix_prometheus_base_path }}"
+    - "{{ matrix_prometheus_config_path }}"
+    - "{{ matrix_prometheus_data_path }}"
+  when: matrix_prometheus_enabled|bool
+  
+- name: Ensure prometheus.yml installed
+  copy:
+    content: "{{ matrix_prometheus_configuration|to_nice_yaml }}"
+    dest: "{{ matrix_prometheus_config_path }}/prometheus.yml"
+    mode: 0644
+    owner: "{{ matrix_user_username }}"
+    group: "{{ matrix_user_groupname }}"
+  when: matrix_prometheus_enabled|bool
+
+- name: Download synapse-v2.rules
+  get_url:
+    url: "{{ matrix_synapse_prometheus_rules_download_url }}"
+    dest: "{{ matrix_prometheus_config_path }}/synapse-v2.rules"
+    force: true
+    mode: 0440
+    owner: "{{ matrix_user_username }}"
+    group: "{{ matrix_user_groupname }}"
+  when: matrix_prometheus_enabled|bool
+
+
+- name: Ensure matrix-prometheus.service installed
+  template:
+    src: "{{ role_path }}/templates/systemd/matrix-prometheus.service.j2"
+    dest: "{{ matrix_systemd_path }}/matrix-prometheus.service"
+    mode: 0644
+  register: matrix_prometheus_systemd_service_result
+  when: matrix_prometheus_enabled|bool
+
+- name: Ensure systemd reloaded after matrix-prometheus.service installation
+  service:
+    daemon_reload: yes
+  when: "matrix_prometheus_enabled|bool and matrix_prometheus_systemd_service_result.changed"
+
+#
+# Tasks related to getting rid of matrix-prometheus (if it was previously enabled)
+#
+
+- name: Check existence of matrix-prometheus service
+  stat:
+    path: "{{ matrix_systemd_path }}/matrix-prometheus.service"
+  register: matrix_prometheus_service_stat
+
+- name: Ensure matrix-prometheus is stopped
+  service:
+    name: matrix-prometheus
+    state: stopped
+    daemon_reload: yes
+  register: stopping_result
+  when: "not matrix_prometheus_enabled|bool and matrix_prometheus_service_stat.stat.exists"
+
+- name: Ensure matrix-prometheus.service doesn't exist
+  file:
+    path: "{{ matrix_systemd_path }}/matrix-prometheus.service"
+    state: absent
+  when: "not matrix_prometheus_enabled|bool and matrix_prometheus_service_stat.stat.exists"
+
+- name: Ensure systemd reloaded after matrix-prometheus.service removal
+  service:
+    daemon_reload: yes
+  when: "not matrix_prometheus_enabled|bool and matrix_prometheus_service_stat.stat.exists"
+
+- name: Ensure matrix-prometheus Docker image doesn't exist
+  docker_image:
+    name: "{{ matrix_prometheus_docker_image }}"
+    state: absent
+  when: "not matrix_prometheus_enabled|bool"
diff --git a/roles/matrix-prometheus/tasks/validate_config.yml b/roles/matrix-prometheus/tasks/validate_config.yml
new file mode 100644
index 000000000..b614b4385
--- /dev/null
+++ b/roles/matrix-prometheus/tasks/validate_config.yml
@@ -0,0 +1,7 @@
+---
+
+- name: Fail if Synapse metrics not enabled
+  fail:
+    msg: >
+      You need to enable `matrix_synapse_metrics_enabled` for Prometheus grab metrics.
+  when: "not matrix_synapse_metrics_enabled"
diff --git a/roles/matrix-prometheus/templates/prometheus.yml.j2 b/roles/matrix-prometheus/templates/prometheus.yml.j2
new file mode 100644
index 000000000..7b90baeb3
--- /dev/null
+++ b/roles/matrix-prometheus/templates/prometheus.yml.j2
@@ -0,0 +1,35 @@
+#jinja2: lstrip_blocks: "True"
+global:
+  scrape_interval:     15s # Set the scrape interval to every 15 seconds. Default is every 1 minute.
+  evaluation_interval: 15s # Evaluate rules every 15 seconds. The default is every 1 minute.
+  # scrape_timeout is set to the global default (10s).
+
+# Load rules once and periodically evaluate them according to the global 'evaluation_interval'.
+rule_files:
+    {% if matrix_synapse_metrics_enabled %}
+    - 'synapse-v2.rules'
+    {% endif %}
+
+# A scrape configuration containing exactly one endpoint to scrape:
+# Here it's Prometheus itself.
+scrape_configs:
+  # The job name is added as a label `job=<job_name>` to any timeseries scraped from this config.
+  - job_name: 'prometheus'
+
+    # Override the global default and scrape targets from this job every 5 seconds.
+    scrape_interval: 5s
+    scrape_timeout: 5s
+
+    # metrics_path defaults to '/metrics'
+    # scheme defaults to 'http'.
+
+    static_configs:
+      - targets: ['localhost:9090']
+
+  {% if matrix_synapse_metrics_enabled %}
+  - job_name: 'synapse'
+    metrics_path: '/_synapse/metrics'
+    static_configs:
+    - targets: ['matrix-synapse:{{ matrix_synapse_metrics_port }}']
+  {% endif %}
+
diff --git a/roles/matrix-prometheus/templates/systemd/matrix-prometheus.service.j2 b/roles/matrix-prometheus/templates/systemd/matrix-prometheus.service.j2
new file mode 100644
index 000000000..dd3ac72cb
--- /dev/null
+++ b/roles/matrix-prometheus/templates/systemd/matrix-prometheus.service.j2
@@ -0,0 +1,42 @@
+#jinja2: lstrip_blocks: "True"
+[Unit]
+Description=matrix-prometheus
+{% for service in matrix_prometheus_systemd_required_services_list %}
+Requires={{ service }}
+After={{ service }}
+{% endfor %}
+{% for service in matrix_prometheus_systemd_wanted_services_list %}
+Wants={{ service }}
+{% endfor %}
+DefaultDependencies=no
+
+[Service]
+Type=simple
+Environment="HOME={{ matrix_systemd_unit_home_path }}"
+ExecStartPre=-{{ matrix_host_command_sh }} -c '{{ matrix_host_command_docker }} kill matrix-prometheus 2>/dev/null'
+ExecStartPre=-{{ matrix_host_command_sh }} -c '{{ matrix_host_command_docker }} rm matrix-prometheus 2>/dev/null'
+
+
+ExecStart={{ matrix_host_command_docker }} run --rm --name matrix-prometheus \
+			--log-driver=none \
+			--user={{ matrix_user_uid }}:{{ matrix_user_gid }} \
+			--cap-drop=ALL \
+			--network={{ matrix_docker_network }} \
+			{% if matrix_prometheus_container_http_host_bind_port %}
+			-p {{ matrix_prometheus_container_http_host_bind_port }}:9090 \
+			{% endif %}
+			-v {{ matrix_prometheus_config_path }}:/etc/prometheus:z \
+			-v {{ matrix_prometheus_data_path }}:/prometheus:z \
+			{% for arg in matrix_prometheus_container_extra_arguments %}
+			{{ arg }} \
+			{% endfor %}
+			{{ matrix_prometheus_docker_image }}
+
+ExecStop=-{{ matrix_host_command_sh }} -c '{{ matrix_host_command_docker }} kill matrix-prometheus 2>/dev/null'
+ExecStop=-{{ matrix_host_command_sh }} -c '{{ matrix_host_command_docker }} rm matrix-prometheus 2>/dev/null'
+Restart=always
+RestartSec=30
+SyslogIdentifier=matrix-prometheus
+
+[Install]
+WantedBy=multi-user.target
diff --git a/setup.yml b/setup.yml
index 9bb1788f1..7965185c5 100755
--- a/setup.yml
+++ b/setup.yml
@@ -28,6 +28,7 @@
     - matrix-bot-matrix-reminder-bot
     - matrix-synapse
     - matrix-synapse-admin
+    - matrix-prometheus
     - matrix-registration
     - matrix-client-element
     - matrix-jitsi

From e525970b393350f9280bdf8ddcb78f9d55c1da24 Mon Sep 17 00:00:00 2001
From: Peetz0r <github@haas-en-berg.nl>
Date: Fri, 29 Jan 2021 06:17:45 +0100
Subject: [PATCH 37/66] Prometheus Node Exporter

Basic system stats, to show stuff the synapse metrics
can't show such as resource usage by bridges, etc

Seems to work fine as well.

This too has only been tested on debian amd64 so far
---
 group_vars/matrix_servers                     | 21 +++++++
 .../defaults/main.yml                         | 21 +++++++
 .../tasks/init.yml                            |  5 ++
 .../tasks/main.yml                            |  8 +++
 .../tasks/setup.yml                           | 60 +++++++++++++++++++
 .../tasks/validate_config.yml                 |  7 +++
 ...matrix-prometheus-node-exporter.service.j2 | 40 +++++++++++++
 .../tasks/validate_config.yml                 |  6 +-
 .../templates/prometheus.yml.j2               |  5 ++
 setup.yml                                     |  1 +
 10 files changed, 171 insertions(+), 3 deletions(-)
 create mode 100644 roles/matrix-prometheus-node-exporter/defaults/main.yml
 create mode 100644 roles/matrix-prometheus-node-exporter/tasks/init.yml
 create mode 100644 roles/matrix-prometheus-node-exporter/tasks/main.yml
 create mode 100644 roles/matrix-prometheus-node-exporter/tasks/setup.yml
 create mode 100644 roles/matrix-prometheus-node-exporter/tasks/validate_config.yml
 create mode 100644 roles/matrix-prometheus-node-exporter/templates/systemd/matrix-prometheus-node-exporter.service.j2

diff --git a/group_vars/matrix_servers b/group_vars/matrix_servers
index 833089a2f..4f2cfa6a4 100755
--- a/group_vars/matrix_servers
+++ b/group_vars/matrix_servers
@@ -1368,6 +1368,27 @@ matrix_synapse_admin_container_self_build: "{{ matrix_architecture != 'amd64' }}
 
 
 
+######################################################################
+#
+# matrix-prometheus-node-exporter
+#
+######################################################################
+
+matrix_prometheus_node_exporter_enabled: false
+
+# Normally, matrix-nginx-proxy is enabled and nginx can reach Prometheus Node Exporter over the container network.
+# If matrix-nginx-proxy is not enabled, or you otherwise have a need for it, you can expose
+# Prometheus' HTTP port to the local host.
+matrix_prometheus_node_exporter_container_http_host_bind_port: "{{ '' if matrix_nginx_proxy_enabled else '127.0.0.1:9100' }}"
+
+######################################################################
+#
+# /matrix-prometheus-node-exporter
+#
+######################################################################
+
+
+
 ######################################################################
 #
 # matrix-prometheus
diff --git a/roles/matrix-prometheus-node-exporter/defaults/main.yml b/roles/matrix-prometheus-node-exporter/defaults/main.yml
new file mode 100644
index 000000000..a5664b836
--- /dev/null
+++ b/roles/matrix-prometheus-node-exporter/defaults/main.yml
@@ -0,0 +1,21 @@
+# matrix-prometheus-node-exporter is an Prometheus exporter for machine metrics
+# See: https://prometheus.io/docs/guides/node-exporter/
+
+matrix_prometheus_node_exporter_enabled: false
+
+matrix_prometheus_node_exporter_docker_image: "docker.io/prom/node-exporter:v1.0.1"
+matrix_prometheus_node_exporter_docker_image_force_pull: "{{ matrix_prometheus_node_exporter_docker_image.endswith(':latest') }}"
+
+# A list of extra arguments to pass to the container
+matrix_prometheus_node_exporter_container_extra_arguments: []
+
+# List of systemd services that matrix-prometheus.service depends on
+matrix_prometheus_node_exporter_systemd_required_services_list: ['docker.service']
+
+# List of systemd services that matrix-prometheus.service wants
+matrix_prometheus_node_exporter_systemd_wanted_services_list: []
+
+# Controls whether the matrix-prometheus container exposes its HTTP port (tcp/9100 in the container).
+#
+# Takes an "<ip>:<port>" or "<port>" value (e.g. "127.0.0.1:9100"), or empty string to not expose.
+matrix_prometheus_node_exporter_container_http_host_bind_port: ''
diff --git a/roles/matrix-prometheus-node-exporter/tasks/init.yml b/roles/matrix-prometheus-node-exporter/tasks/init.yml
new file mode 100644
index 000000000..2894b7176
--- /dev/null
+++ b/roles/matrix-prometheus-node-exporter/tasks/init.yml
@@ -0,0 +1,5 @@
+- set_fact:
+    matrix_systemd_services_list: "{{ matrix_systemd_services_list + ['matrix-prometheus-node-exporter.service'] }}"
+  when: matrix_prometheus_node_exporter_enabled|bool
+
+
diff --git a/roles/matrix-prometheus-node-exporter/tasks/main.yml b/roles/matrix-prometheus-node-exporter/tasks/main.yml
new file mode 100644
index 000000000..172b57215
--- /dev/null
+++ b/roles/matrix-prometheus-node-exporter/tasks/main.yml
@@ -0,0 +1,8 @@
+- import_tasks: "{{ role_path }}/tasks/init.yml"
+  tags:
+    - always
+
+- import_tasks: "{{ role_path }}/tasks/setup.yml"
+  tags:
+    - setup-all
+    - setup-prometheus-node-exporter
diff --git a/roles/matrix-prometheus-node-exporter/tasks/setup.yml b/roles/matrix-prometheus-node-exporter/tasks/setup.yml
new file mode 100644
index 000000000..6f03fbaa3
--- /dev/null
+++ b/roles/matrix-prometheus-node-exporter/tasks/setup.yml
@@ -0,0 +1,60 @@
+---
+
+#
+# Tasks related to setting up matrix-prometheus-node-exporter
+#
+
+- name: Ensure matrix-prometheus-node-exporter image is pulled
+  docker_image:
+    name: "{{ matrix_prometheus_node_exporter_docker_image }}"
+    source: "{{ 'pull' if ansible_version.major > 2 or ansible_version.minor > 7 else omit }}"
+    force_source: "{{ matrix_prometheus_node_exporter_docker_image_force_pull if ansible_version.major > 2 or ansible_version.minor >= 8 else omit }}"
+    force: "{{ omit if ansible_version.major > 2 or ansible_version.minor >= 8 else matrix_prometheus_node_exporter_docker_image_force_pull }}"
+  when: "matrix_prometheus_node_exporter_enabled|bool"
+
+- name: Ensure matrix-prometheus-node-exporter.service installed
+  template:
+    src: "{{ role_path }}/templates/systemd/matrix-prometheus-node-exporter.service.j2"
+    dest: "{{ matrix_systemd_path }}/matrix-prometheus-node-exporter.service"
+    mode: 0644
+  register: matrix_prometheus_node_exporter_systemd_service_result
+  when: matrix_prometheus_node_exporter_enabled|bool
+
+- name: Ensure systemd reloaded after matrix-prometheus.service installation
+  service:
+    daemon_reload: yes
+  when: "matrix_prometheus_node_exporter_enabled|bool and matrix_prometheus_node_exporter_systemd_service_result.changed"
+
+#
+# Tasks related to getting rid of matrix-prometheus-node-exporter (if it was previously enabled)
+#
+
+- name: Check existence of matrix-prometheus-node-exporter service
+  stat:
+    path: "{{ matrix_systemd_path }}/matrix-prometheus-node-exporter.service"
+  register: matrix_prometheus_node_exporter_service_stat
+
+- name: Ensure matrix-prometheus-node-exporter is stopped
+  service:
+    name: matrix-prometheus-node-exporter
+    state: stopped
+    daemon_reload: yes
+  register: stopping_result
+  when: "not matrix_prometheus_node_exporter_enabled|bool and matrix_prometheus_node_exporter_service_stat.stat.exists"
+
+- name: Ensure matrix-prometheus-node-exporter.service doesn't exist
+  file:
+    path: "{{ matrix_systemd_path }}/matrix-prometheus-node-exporter.service"
+    state: absent
+  when: "not matrix_prometheus_node_exporter_enabled|bool and matrix_prometheus_node_exporter_service_stat.stat.exists"
+
+- name: Ensure systemd reloaded after matrix-prometheus-node-exporter.service removal
+  service:
+    daemon_reload: yes
+  when: "not matrix_prometheus_node_exporter_enabled|bool and matrix_prometheus_node_exporter_service_stat.stat.exists"
+
+- name: Ensure matrix-prometheus-node-exporter Docker image doesn't exist
+  docker_image:
+    name: "{{ matrix_prometheus_node_exporter_docker_image }}"
+    state: absent
+  when: "not matrix_prometheus_node_exporter_enabled|bool"
diff --git a/roles/matrix-prometheus-node-exporter/tasks/validate_config.yml b/roles/matrix-prometheus-node-exporter/tasks/validate_config.yml
new file mode 100644
index 000000000..713646ae0
--- /dev/null
+++ b/roles/matrix-prometheus-node-exporter/tasks/validate_config.yml
@@ -0,0 +1,7 @@
+---
+
+- name: Fail if Synapse metrics or Prometheus Node Exporter not enabled
+  fail:
+    msg: >
+      You need to enable `matrix_synapse_metrics_enabled` and/or `matrix_prometheus_node_exporter_enabled` for Prometheus grab metrics.
+  when: "not matrix_synapse_metrics_enabled and not matrix_prometheus_node_exporter_enabled"
diff --git a/roles/matrix-prometheus-node-exporter/templates/systemd/matrix-prometheus-node-exporter.service.j2 b/roles/matrix-prometheus-node-exporter/templates/systemd/matrix-prometheus-node-exporter.service.j2
new file mode 100644
index 000000000..622947d08
--- /dev/null
+++ b/roles/matrix-prometheus-node-exporter/templates/systemd/matrix-prometheus-node-exporter.service.j2
@@ -0,0 +1,40 @@
+#jinja2: lstrip_blocks: "True"
+[Unit]
+Description=matrix-prometheus-node-exporter
+{% for service in matrix_prometheus_node_exporter_systemd_required_services_list %}
+Requires={{ service }}
+After={{ service }}
+{% endfor %}
+{% for service in matrix_prometheus_node_exporter_systemd_wanted_services_list %}
+Wants={{ service }}
+{% endfor %}
+DefaultDependencies=no
+
+[Service]
+Type=simple
+Environment="HOME={{ matrix_systemd_unit_home_path }}"
+ExecStartPre=-{{ matrix_host_command_sh }} -c '{{ matrix_host_command_docker }} kill matrix-prometheus-node-exporter 2>/dev/null'
+ExecStartPre=-{{ matrix_host_command_sh }} -c '{{ matrix_host_command_docker }} rm matrix-prometheus-node-exporter 2>/dev/null'
+
+
+ExecStart={{ matrix_host_command_docker }} run --rm --name matrix-prometheus-node-exporter \
+			--log-driver=none \
+			--user={{ matrix_user_uid }}:{{ matrix_user_gid }} \
+			--cap-drop=ALL \
+			--network={{ matrix_docker_network }} \
+			{% if matrix_prometheus_node_exporter_container_http_host_bind_port %}
+			-p {{ matrix_prometheus_node_exporter_container_http_host_bind_port }}:9100 \
+			{% endif %}
+			{% for arg in matrix_prometheus_node_exporter_container_extra_arguments %}
+			{{ arg }} \
+			{% endfor %}
+			{{ matrix_prometheus_node_exporter_docker_image }}
+
+ExecStop=-{{ matrix_host_command_sh }} -c '{{ matrix_host_command_docker }} kill matrix-prometheus-node-exporter 2>/dev/null'
+ExecStop=-{{ matrix_host_command_sh }} -c '{{ matrix_host_command_docker }} rm matrix-prometheus-node-exporter 2>/dev/null'
+Restart=always
+RestartSec=30
+SyslogIdentifier=matrix-prometheus-node-exporter
+
+[Install]
+WantedBy=multi-user.target
diff --git a/roles/matrix-prometheus/tasks/validate_config.yml b/roles/matrix-prometheus/tasks/validate_config.yml
index b614b4385..713646ae0 100644
--- a/roles/matrix-prometheus/tasks/validate_config.yml
+++ b/roles/matrix-prometheus/tasks/validate_config.yml
@@ -1,7 +1,7 @@
 ---
 
-- name: Fail if Synapse metrics not enabled
+- name: Fail if Synapse metrics or Prometheus Node Exporter not enabled
   fail:
     msg: >
-      You need to enable `matrix_synapse_metrics_enabled` for Prometheus grab metrics.
-  when: "not matrix_synapse_metrics_enabled"
+      You need to enable `matrix_synapse_metrics_enabled` and/or `matrix_prometheus_node_exporter_enabled` for Prometheus grab metrics.
+  when: "not matrix_synapse_metrics_enabled and not matrix_prometheus_node_exporter_enabled"
diff --git a/roles/matrix-prometheus/templates/prometheus.yml.j2 b/roles/matrix-prometheus/templates/prometheus.yml.j2
index 7b90baeb3..317dcd168 100644
--- a/roles/matrix-prometheus/templates/prometheus.yml.j2
+++ b/roles/matrix-prometheus/templates/prometheus.yml.j2
@@ -33,3 +33,8 @@ scrape_configs:
     - targets: ['matrix-synapse:{{ matrix_synapse_metrics_port }}']
   {% endif %}
 
+  {% if matrix_prometheus_node_exporter_enabled %}
+  - job_name: node
+    static_configs:
+      - targets: ['matrix-prometheus-node-exporter:9100']
+  {% endif %}
diff --git a/setup.yml b/setup.yml
index 7965185c5..838e08c89 100755
--- a/setup.yml
+++ b/setup.yml
@@ -28,6 +28,7 @@
     - matrix-bot-matrix-reminder-bot
     - matrix-synapse
     - matrix-synapse-admin
+    - matrix-prometheus-node-exporter
     - matrix-prometheus
     - matrix-registration
     - matrix-client-element

From eb5aa93e8a5b83593de4030982e583eae8aa8ee8 Mon Sep 17 00:00:00 2001
From: Peetz0r <github@haas-en-berg.nl>
Date: Fri, 29 Jan 2021 09:10:49 +0100
Subject: [PATCH 38/66] Grafana

Also includes the dashboards for Synapse and for Node Exporter.

Again has only been tested on debian amd64 so far, but the grafana docker image is available for arm64 and arm32. Nice.
---
 group_vars/matrix_servers                     |  21 ++++
 roles/matrix-grafana/defaults/main.yml        |  47 +++++++
 roles/matrix-grafana/tasks/init.yml           |   5 +
 roles/matrix-grafana/tasks/main.yml           |  14 +++
 roles/matrix-grafana/tasks/setup.yml          | 115 ++++++++++++++++++
 .../matrix-grafana/tasks/validate_config.yml  |   7 ++
 .../templates/dashboards.yaml.j2              |   9 ++
 .../templates/datasources.yaml.j2             |   8 ++
 roles/matrix-grafana/templates/grafana.ini.j2 |  20 +++
 .../systemd/matrix-grafana.service.j2         |  42 +++++++
 setup.yml                                     |   1 +
 11 files changed, 289 insertions(+)
 create mode 100644 roles/matrix-grafana/defaults/main.yml
 create mode 100644 roles/matrix-grafana/tasks/init.yml
 create mode 100644 roles/matrix-grafana/tasks/main.yml
 create mode 100644 roles/matrix-grafana/tasks/setup.yml
 create mode 100644 roles/matrix-grafana/tasks/validate_config.yml
 create mode 100644 roles/matrix-grafana/templates/dashboards.yaml.j2
 create mode 100644 roles/matrix-grafana/templates/datasources.yaml.j2
 create mode 100644 roles/matrix-grafana/templates/grafana.ini.j2
 create mode 100644 roles/matrix-grafana/templates/systemd/matrix-grafana.service.j2

diff --git a/group_vars/matrix_servers b/group_vars/matrix_servers
index 4f2cfa6a4..976a0de12 100755
--- a/group_vars/matrix_servers
+++ b/group_vars/matrix_servers
@@ -1410,6 +1410,27 @@ matrix_prometheus_container_http_host_bind_port: "{{ '' if matrix_nginx_proxy_en
 
 
 
+######################################################################
+#
+# matrix-grafana
+#
+######################################################################
+
+matrix_grafana_enabled: false
+
+# Normally, matrix-nginx-proxy is enabled and nginx can reach Grafana over the container network.
+# If matrix-nginx-proxy is not enabled, or you otherwise have a need for it, you can expose
+# Grafana's HTTP port to the local host.
+matrix_grafana_container_http_host_bind_port: "{{ '' if matrix_nginx_proxy_enabled else '127.0.0.1:3000' }}"
+
+######################################################################
+#
+# /matrix-grafana
+#
+######################################################################
+
+
+
 ######################################################################
 #
 # matrix-registration
diff --git a/roles/matrix-grafana/defaults/main.yml b/roles/matrix-grafana/defaults/main.yml
new file mode 100644
index 000000000..2257d7941
--- /dev/null
+++ b/roles/matrix-grafana/defaults/main.yml
@@ -0,0 +1,47 @@
+# matrix-grafana is open source visualization and analytics software
+# See: https://github.com/matrix-org/synapse/blob/master/docs/metrics-howto.md
+
+matrix_grafana_enabled: false
+
+matrix_grafana_docker_image: "docker.io/grafana/grafana:7.3.7"
+matrix_grafana_docker_image_force_pull: "{{ matrix_grafana_docker_image.endswith(':latest') }}"
+
+# Not conditional, because when someone disables metrics
+# they might still want to look at the old existing data.
+# So it would be silly to delete the dashboard in such case.
+matrix_grafana_dashboard_download_urls:
+- "https://raw.githubusercontent.com/matrix-org/synapse/master/contrib/grafana/synapse.json"
+- "https://raw.githubusercontent.com/rfrail3/grafana-dashboards/master/prometheus/node-exporter-full.json"
+  
+matrix_grafana_base_path: "{{ matrix_base_data_path }}/grafana"
+matrix_grafana_config_path: "{{ matrix_grafana_base_path }}/config"
+matrix_grafana_data_path: "{{ matrix_grafana_base_path }}/data"
+
+# Allow viewing Grafana without logging in
+matrix_grafana_anonymous_access: false
+
+# specify organization name that should be used for unauthenticated users
+# if you change this in the Grafana admin panel, this needs to be updated
+# to match to keep anonymous logins working
+matrix_grafana_anonymous_access_org_name: 'Main Org.'
+
+
+# default admin credentials, you are asked to change these on first login
+matrix_grafana_default_admin_user: admin
+matrix_grafana_default_admin_password: admin
+
+# A list of extra arguments to pass to the container
+matrix_grafana_container_extra_arguments: []
+
+# List of systemd services that matrix-grafana.service depends on
+matrix_grafana_systemd_required_services_list: ['docker.service']
+
+# List of systemd services that matrix-grafana.service wants
+matrix_grafana_systemd_wanted_services_list: []
+
+# Controls whether the matrix-grafana container exposes its HTTP port (tcp/3000 in the container).
+#
+# Takes an "<ip>:<port>" or "<port>" value (e.g. "127.0.0.1:3000"), or empty string to not expose.
+matrix_grafana_container_http_host_bind_port: ''
+
+
diff --git a/roles/matrix-grafana/tasks/init.yml b/roles/matrix-grafana/tasks/init.yml
new file mode 100644
index 000000000..8a22e3018
--- /dev/null
+++ b/roles/matrix-grafana/tasks/init.yml
@@ -0,0 +1,5 @@
+- set_fact:
+    matrix_systemd_services_list: "{{ matrix_systemd_services_list + ['matrix-grafana.service'] }}"
+  when: matrix_grafana_enabled|bool
+
+
diff --git a/roles/matrix-grafana/tasks/main.yml b/roles/matrix-grafana/tasks/main.yml
new file mode 100644
index 000000000..122ec65e1
--- /dev/null
+++ b/roles/matrix-grafana/tasks/main.yml
@@ -0,0 +1,14 @@
+- import_tasks: "{{ role_path }}/tasks/init.yml"
+  tags:
+    - always
+
+- import_tasks: "{{ role_path }}/tasks/validate_config.yml"
+  when: run_setup|bool
+  tags:
+    - setup-all
+    - setup-grafana
+
+- import_tasks: "{{ role_path }}/tasks/setup.yml"
+  tags:
+    - setup-all
+    - setup-grafana
diff --git a/roles/matrix-grafana/tasks/setup.yml b/roles/matrix-grafana/tasks/setup.yml
new file mode 100644
index 000000000..581e66174
--- /dev/null
+++ b/roles/matrix-grafana/tasks/setup.yml
@@ -0,0 +1,115 @@
+---
+
+#
+# Tasks related to setting up matrix-grafana
+#
+
+- name: Ensure matrix-grafana image is pulled
+  docker_image:
+    name: "{{ matrix_grafana_docker_image }}"
+    source: "{{ 'pull' if ansible_version.major > 2 or ansible_version.minor > 7 else omit }}"
+    force_source: "{{ matrix_grafana_docker_image_force_pull if ansible_version.major > 2 or ansible_version.minor >= 8 else omit }}"
+    force: "{{ omit if ansible_version.major > 2 or ansible_version.minor >= 8 else matrix_grafana_docker_image_force_pull }}"
+  when: "matrix_grafana_enabled|bool"
+
+- name: Ensure grafana paths exists
+  file:
+    path: "{{ item }}"
+    state: directory
+    mode: 0750
+    owner: "{{ matrix_user_username }}"
+    group: "{{ matrix_user_groupname }}"
+  with_items:
+    - "{{ matrix_grafana_base_path }}"
+    - "{{ matrix_grafana_config_path }}"
+    - "{{ matrix_grafana_config_path }}/provisioning"
+    - "{{ matrix_grafana_config_path }}/provisioning/datasources"
+    - "{{ matrix_grafana_config_path }}/provisioning/dashboards"
+    - "{{ matrix_grafana_config_path }}/dashboards"
+    - "{{ matrix_grafana_data_path }}"
+  when: matrix_grafana_enabled|bool
+  
+- name: Ensure grafana.ini present
+  template:
+    src: "{{ role_path }}/templates/grafana.ini.j2"
+    dest: "{{ matrix_grafana_config_path }}/grafana.ini"
+    mode: 0440
+    owner: "{{ matrix_user_username }}"
+    group: "{{ matrix_user_groupname }}"
+  when: matrix_grafana_enabled|bool
+  
+- name: Ensure provisioning/datasources/default.yaml present
+  template:
+    src: "{{ role_path }}/templates/datasources.yaml.j2"
+    dest: "{{ matrix_grafana_config_path }}/provisioning/datasources/default.yaml"
+    mode: 0440
+    owner: "{{ matrix_user_username }}"
+    group: "{{ matrix_user_groupname }}"
+  when: matrix_grafana_enabled|bool
+  
+- name: Ensure provisioning/dashboards/default.yaml present
+  template:
+    src: "{{ role_path }}/templates/dashboards.yaml.j2"
+    dest: "{{ matrix_grafana_config_path }}/provisioning/dashboards/default.yaml"
+    mode: 0440
+    owner: "{{ matrix_user_username }}"
+    group: "{{ matrix_user_groupname }}"
+  when: matrix_grafana_enabled|bool
+  
+- name: Ensure dashboard(s) downloaded
+  get_url:
+    url: "{{ item }}"
+    dest: "{{ matrix_grafana_config_path }}/dashboards/"
+    force: true
+    mode: 0440
+    owner: "{{ matrix_user_username }}"
+    group: "{{ matrix_user_groupname }}"
+  with_items: "{{ matrix_grafana_dashboard_download_urls }}"
+  when: matrix_grafana_enabled|bool
+
+- name: Ensure matrix-grafana.service installed
+  template:
+    src: "{{ role_path }}/templates/systemd/matrix-grafana.service.j2"
+    dest: "{{ matrix_systemd_path }}/matrix-grafana.service"
+    mode: 0644
+  register: matrix_grafana_systemd_service_result
+  when: matrix_grafana_enabled|bool
+
+- name: Ensure systemd reloaded after matrix-grafana.service installation
+  service:
+    daemon_reload: yes
+  when: "matrix_grafana_enabled|bool and matrix_grafana_systemd_service_result.changed"
+
+#
+# Tasks related to getting rid of matrix-grafana (if it was previously enabled)
+#
+
+- name: Check existence of matrix-grafana service
+  stat:
+    path: "{{ matrix_systemd_path }}/matrix-grafana.service"
+  register: matrix_grafana_service_stat
+
+- name: Ensure matrix-grafana is stopped
+  service:
+    name: matrix-grafana
+    state: stopped
+    daemon_reload: yes
+  register: stopping_result
+  when: "not matrix_grafana_enabled|bool and matrix_grafana_service_stat.stat.exists"
+
+- name: Ensure matrix-grafana.service doesn't exist
+  file:
+    path: "{{ matrix_systemd_path }}/matrix-grafana.service"
+    state: absent
+  when: "not matrix_grafana_enabled|bool and matrix_grafana_service_stat.stat.exists"
+
+- name: Ensure systemd reloaded after matrix-grafana.service removal
+  service:
+    daemon_reload: yes
+  when: "not matrix_grafana_enabled|bool and matrix_grafana_service_stat.stat.exists"
+
+- name: Ensure matrix-grafana Docker image doesn't exist
+  docker_image:
+    name: "{{ matrix_grafana_docker_image }}"
+    state: absent
+  when: "not matrix_grafana_enabled|bool"
diff --git a/roles/matrix-grafana/tasks/validate_config.yml b/roles/matrix-grafana/tasks/validate_config.yml
new file mode 100644
index 000000000..63d4919a3
--- /dev/null
+++ b/roles/matrix-grafana/tasks/validate_config.yml
@@ -0,0 +1,7 @@
+---
+
+- name: Fail if Prometheus not enabled
+  fail:
+    msg: >
+      You need to enable `matrix_prometheus_enabled` to use Prometheus as data source for Grafana.
+  when: "not matrix_prometheus_enabled"
diff --git a/roles/matrix-grafana/templates/dashboards.yaml.j2 b/roles/matrix-grafana/templates/dashboards.yaml.j2
new file mode 100644
index 000000000..b6662e597
--- /dev/null
+++ b/roles/matrix-grafana/templates/dashboards.yaml.j2
@@ -0,0 +1,9 @@
+apiVersion: 1
+
+providers:
+  - name: {{ matrix_domain }} - Dashboards
+    folder: '' # The folder where to place the dashboards
+    type: file
+    allowUiUpdates: true
+    options:
+      path: /etc/grafana/dashboards
diff --git a/roles/matrix-grafana/templates/datasources.yaml.j2 b/roles/matrix-grafana/templates/datasources.yaml.j2
new file mode 100644
index 000000000..ffa6046b0
--- /dev/null
+++ b/roles/matrix-grafana/templates/datasources.yaml.j2
@@ -0,0 +1,8 @@
+apiVersion: 1
+
+datasources:
+  - name: {{ matrix_domain }} - Prometheus
+    type: prometheus
+    # Access mode - proxy (server in the UI) or direct (browser in the UI).
+    access: proxy
+    url: http://matrix-prometheus:9090
diff --git a/roles/matrix-grafana/templates/grafana.ini.j2 b/roles/matrix-grafana/templates/grafana.ini.j2
new file mode 100644
index 000000000..694bf7d7e
--- /dev/null
+++ b/roles/matrix-grafana/templates/grafana.ini.j2
@@ -0,0 +1,20 @@
+[security]
+# default admin user, created on startup
+admin_user = {{ matrix_grafana_default_admin_user }}
+
+# default admin password, can be changed before first start of grafana,  or in profile settings
+admin_password = {{ matrix_grafana_default_admin_password }}
+
+[auth.anonymous]
+# enable anonymous access
+enabled = {{ matrix_grafana_anonymous_access }}
+
+# specify organization name that should be used for unauthenticated users
+org_name = {{ matrix_grafana_anonymous_access_org_name }}
+
+[dashboards]
+{% if matrix_synapse_metrics_enabled %}
+default_home_dashboard_path = /etc/grafana/dashboards/synapse.json
+{% else %}
+default_home_dashboard_path = /etc/grafana/dashboards/node-exporter-full.json
+{% endif %}
diff --git a/roles/matrix-grafana/templates/systemd/matrix-grafana.service.j2 b/roles/matrix-grafana/templates/systemd/matrix-grafana.service.j2
new file mode 100644
index 000000000..f2ab66424
--- /dev/null
+++ b/roles/matrix-grafana/templates/systemd/matrix-grafana.service.j2
@@ -0,0 +1,42 @@
+#jinja2: lstrip_blocks: "True"
+[Unit]
+Description=matrix-grafana
+{% for service in matrix_grafana_systemd_required_services_list %}
+Requires={{ service }}
+After={{ service }}
+{% endfor %}
+{% for service in matrix_grafana_systemd_wanted_services_list %}
+Wants={{ service }}
+{% endfor %}
+DefaultDependencies=no
+
+[Service]
+Type=simple
+Environment="HOME={{ matrix_systemd_unit_home_path }}"
+ExecStartPre=-{{ matrix_host_command_sh }} -c '{{ matrix_host_command_docker }} kill matrix-grafana 2>/dev/null'
+ExecStartPre=-{{ matrix_host_command_sh }} -c '{{ matrix_host_command_docker }} rm matrix-grafana 2>/dev/null'
+
+
+ExecStart={{ matrix_host_command_docker }} run --rm --name matrix-grafana \
+			--log-driver=none \
+			--user={{ matrix_user_uid }}:{{ matrix_user_gid }} \
+			--cap-drop=ALL \
+			--network={{ matrix_docker_network }} \
+			{% if matrix_grafana_container_http_host_bind_port %}
+			-p {{ matrix_grafana_container_http_host_bind_port }}:3000 \
+			{% endif %}
+			-v {{ matrix_grafana_config_path }}:/etc/grafana:z \
+			-v {{ matrix_grafana_data_path }}:/var/lib/grafana:z \
+			{% for arg in matrix_grafana_container_extra_arguments %}
+			{{ arg }} \
+			{% endfor %}
+			{{ matrix_grafana_docker_image }}
+
+ExecStop=-{{ matrix_host_command_sh }} -c '{{ matrix_host_command_docker }} kill matrix-grafana 2>/dev/null'
+ExecStop=-{{ matrix_host_command_sh }} -c '{{ matrix_host_command_docker }} rm matrix-grafana 2>/dev/null'
+Restart=always
+RestartSec=30
+SyslogIdentifier=matrix-grafana
+
+[Install]
+WantedBy=multi-user.target
diff --git a/setup.yml b/setup.yml
index 838e08c89..e7fdae191 100755
--- a/setup.yml
+++ b/setup.yml
@@ -30,6 +30,7 @@
     - matrix-synapse-admin
     - matrix-prometheus-node-exporter
     - matrix-prometheus
+    - matrix-grafana
     - matrix-registration
     - matrix-client-element
     - matrix-jitsi

From 989100b1c14a126051d7ad68c323d954061714b8 Mon Sep 17 00:00:00 2001
From: Peetz0r <github@haas-en-berg.nl>
Date: Fri, 29 Jan 2021 10:30:04 +0100
Subject: [PATCH 39/66] Grafana nginx proxy config

---
 group_vars/matrix_servers                     |  3 +
 roles/matrix-base/defaults/main.yml           |  3 +
 roles/matrix-nginx-proxy/defaults/main.yml    |  7 ++
 .../tasks/setup_nginx_proxy.yml               | 13 +++
 .../nginx/conf.d/matrix-grafana.conf.j2       | 79 +++++++++++++++++++
 5 files changed, 105 insertions(+)
 create mode 100644 roles/matrix-nginx-proxy/templates/nginx/conf.d/matrix-grafana.conf.j2

diff --git a/group_vars/matrix_servers b/group_vars/matrix_servers
index 976a0de12..b314dc99c 100755
--- a/group_vars/matrix_servers
+++ b/group_vars/matrix_servers
@@ -974,6 +974,7 @@ matrix_nginx_proxy_proxy_matrix_enabled: true
 matrix_nginx_proxy_proxy_element_enabled: "{{ matrix_client_element_enabled }}"
 matrix_nginx_proxy_proxy_dimension_enabled: "{{ matrix_dimension_enabled }}"
 matrix_nginx_proxy_proxy_jitsi_enabled: "{{ matrix_jitsi_enabled }}"
+matrix_nginx_proxy_proxy_grafana_enabled: "{{ matrix_grafana_enabled }}"
 
 matrix_nginx_proxy_proxy_matrix_corporal_api_enabled: "{{ matrix_corporal_enabled and matrix_corporal_http_api_enabled }}"
 matrix_nginx_proxy_proxy_matrix_corporal_api_addr_with_container: "matrix-corporal:41081"
@@ -1024,6 +1025,8 @@ matrix_ssl_domains_to_obtain_certificates_for: |
     +
     ([matrix_server_fqn_jitsi] if matrix_jitsi_enabled else [])
     +
+    ([matrix_server_fqn_grafana] if matrix_grafana_enabled else [])
+    +
     ([matrix_domain] if matrix_nginx_proxy_base_domain_serving_enabled else [])
   }}
 
diff --git a/roles/matrix-base/defaults/main.yml b/roles/matrix-base/defaults/main.yml
index a238e5037..2aa99a32a 100644
--- a/roles/matrix-base/defaults/main.yml
+++ b/roles/matrix-base/defaults/main.yml
@@ -21,6 +21,9 @@ matrix_server_fqn_dimension: "dimension.{{ matrix_domain }}"
 # This is where you access Jitsi.
 matrix_server_fqn_jitsi: "jitsi.{{ matrix_domain }}"
 
+# This is where you access Grafana.
+matrix_server_fqn_grafana: "stats.{{ matrix_domain }}"
+
 matrix_federation_public_port: 8448
 
 # The architecture that your server runs.
diff --git a/roles/matrix-nginx-proxy/defaults/main.yml b/roles/matrix-nginx-proxy/defaults/main.yml
index 5eedb4cec..d0ff6d959 100644
--- a/roles/matrix-nginx-proxy/defaults/main.yml
+++ b/roles/matrix-nginx-proxy/defaults/main.yml
@@ -115,6 +115,10 @@ matrix_nginx_proxy_proxy_dimension_hostname: "{{ matrix_server_fqn_dimension }}"
 matrix_nginx_proxy_proxy_jitsi_enabled: false
 matrix_nginx_proxy_proxy_jitsi_hostname: "{{ matrix_server_fqn_jitsi }}"
 
+# Controls whether proxying the grafana domain should be done.
+matrix_nginx_proxy_proxy_grafana_enabled: false
+matrix_nginx_proxy_proxy_grafana_hostname: "{{ matrix_server_fqn_grafana }}"
+
 # Controls whether proxying for the matrix-corporal API (`/_matrix/corporal`) should be done (on the matrix domain)
 matrix_nginx_proxy_proxy_matrix_corporal_api_enabled: false
 matrix_nginx_proxy_proxy_matrix_corporal_api_addr_with_container: "matrix-corporal:41081"
@@ -212,6 +216,9 @@ matrix_nginx_proxy_proxy_dimension_additional_server_configuration_blocks: []
 # A list of strings containing additional configuration blocks to add to Jitsi's server configuration.
 matrix_nginx_proxy_proxy_jitsi_additional_server_configuration_blocks: []
 
+# A list of strings containing additional configuration blocks to add to Grafana's server configuration.
+matrix_nginx_proxy_proxy_grafana_additional_server_configuration_blocks: []
+
 # A list of strings containing additional configuration blocks to add to the base domain server configuration.
 matrix_nginx_proxy_proxy_domain_additional_server_configuration_blocks: []
 
diff --git a/roles/matrix-nginx-proxy/tasks/setup_nginx_proxy.yml b/roles/matrix-nginx-proxy/tasks/setup_nginx_proxy.yml
index 90f0da73c..9d7ea5157 100644
--- a/roles/matrix-nginx-proxy/tasks/setup_nginx_proxy.yml
+++ b/roles/matrix-nginx-proxy/tasks/setup_nginx_proxy.yml
@@ -80,6 +80,13 @@
     mode: 0644
   when: matrix_nginx_proxy_proxy_jitsi_enabled|bool
 
+- name: Ensure Matrix nginx-proxy configuration for grafana domain exists
+  template:
+    src: "{{ role_path }}/templates/nginx/conf.d/matrix-grafana.conf.j2"
+    dest: "{{ matrix_nginx_proxy_confd_path }}/matrix-grafana.conf"
+    mode: 0644
+  when: matrix_nginx_proxy_proxy_grafana_enabled|bool
+
 - name: Ensure Matrix nginx-proxy data directory for base domain exists
   file:
     path: "{{ matrix_nginx_proxy_data_path }}/matrix-domain"
@@ -183,6 +190,12 @@
     state: absent
   when: "not matrix_nginx_proxy_proxy_jitsi_enabled|bool"
 
+- name: Ensure Matrix nginx-proxy configuration for grafana domain deleted
+  file:
+    path: "{{ matrix_nginx_proxy_confd_path }}/matrix-grafana.conf"
+    state: absent
+  when: "not matrix_nginx_proxy_proxy_grafana_enabled|bool"
+
 - name: Ensure Matrix nginx-proxy homepage for base domain deleted
   file:
     path: "{{ matrix_nginx_proxy_data_path }}/matrix-domain/index.html"
diff --git a/roles/matrix-nginx-proxy/templates/nginx/conf.d/matrix-grafana.conf.j2 b/roles/matrix-nginx-proxy/templates/nginx/conf.d/matrix-grafana.conf.j2
new file mode 100644
index 000000000..0e1f1c2d7
--- /dev/null
+++ b/roles/matrix-nginx-proxy/templates/nginx/conf.d/matrix-grafana.conf.j2
@@ -0,0 +1,79 @@
+#jinja2: lstrip_blocks: "True"
+
+{% macro render_vhost_directives() %}
+	gzip on;
+	gzip_types text/plain application/json application/javascript text/css image/x-icon font/ttf image/gif;
+	add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
+	add_header X-Content-Type-Options nosniff;
+	add_header X-Frame-Options SAMEORIGIN;
+	{% for configuration_block in matrix_nginx_proxy_proxy_grafana_additional_server_configuration_blocks %}
+		{{- configuration_block }}
+	{% endfor %}
+
+	location / {
+		{% if matrix_nginx_proxy_enabled %}
+			{# Use the embedded DNS resolver in Docker containers to discover the service #}
+			resolver 127.0.0.11 valid=5s;
+			set $backend "matrix-grafana:3000";
+			proxy_pass http://$backend;
+		{% else %}
+			{# Generic configuration for use outside of our container setup #}
+			proxy_pass http://127.0.0.1:3000;
+		{% endif %}
+
+		proxy_set_header Host $host;
+		proxy_set_header X-Forwarded-For $remote_addr;
+	}
+{% endmacro %}
+
+server {
+	listen {{ 8080 if matrix_nginx_proxy_enabled else 80 }};
+
+	server_name {{ matrix_nginx_proxy_proxy_grafana_hostname }};
+
+	server_tokens off;
+	root /dev/null;
+
+	{% if matrix_nginx_proxy_https_enabled %}
+		location /.well-known/acme-challenge {
+			{% if matrix_nginx_proxy_enabled %}
+				{# Use the embedded DNS resolver in Docker containers to discover the service #}
+				resolver 127.0.0.11 valid=5s;
+				set $backend "matrix-certbot:8080";
+				proxy_pass http://$backend;
+			{% else %}
+				{# Generic configuration for use outside of our container setup #}
+				proxy_pass http://127.0.0.1:{{ matrix_ssl_lets_encrypt_certbot_standalone_http_port }};
+			{% endif %}
+		}
+
+		location / {
+			return 301 https://$http_host$request_uri;
+		}
+	{% else %}
+		{{ render_vhost_directives() }}
+	{% endif %}
+}
+
+{% if matrix_nginx_proxy_https_enabled %}
+server {
+	listen {{ 8443 if matrix_nginx_proxy_enabled else 443 }} ssl http2;
+	listen [::]:{{ 8443 if matrix_nginx_proxy_enabled else 443 }} ssl http2;
+
+	server_name {{ matrix_nginx_proxy_proxy_grafana_hostname }};
+
+	server_tokens off;
+	root /dev/null;
+
+	ssl_certificate {{ matrix_ssl_config_dir_path }}/live/{{ matrix_nginx_proxy_proxy_grafana_hostname }}/fullchain.pem;
+	ssl_certificate_key {{ matrix_ssl_config_dir_path }}/live/{{ matrix_nginx_proxy_proxy_grafana_hostname }}/privkey.pem;
+
+	ssl_protocols {{ matrix_nginx_proxy_ssl_protocols }};
+	{% if matrix_nginx_proxy_ssl_ciphers != "" %}
+	ssl_ciphers {{ matrix_nginx_proxy_ssl_ciphers }};
+	{% endif %}
+	ssl_prefer_server_ciphers {{ matrix_nginx_proxy_ssl_prefer_server_ciphers }};
+
+	{{ render_vhost_directives() }}
+}
+{% endif %}

From a10e3244d914cd42ef88688949994d245b852556 Mon Sep 17 00:00:00 2001
From: Peetz0r <github@haas-en-berg.nl>
Date: Fri, 29 Jan 2021 10:59:27 +0100
Subject: [PATCH 40/66] Documentation for graphs

---
 ...configuring-playbook-prometheus-grafana.md | 36 +++++++++++++++++++
 1 file changed, 36 insertions(+)
 create mode 100644 docs/configuring-playbook-prometheus-grafana.md

diff --git a/docs/configuring-playbook-prometheus-grafana.md b/docs/configuring-playbook-prometheus-grafana.md
new file mode 100644
index 000000000..5ad1449b2
--- /dev/null
+++ b/docs/configuring-playbook-prometheus-grafana.md
@@ -0,0 +1,36 @@
+# Enabling metrics and graphs for your Matrix server (optional)
+
+It can be useful to have some (visual) insight in the performance of your homeserver.
+
+You can enable this with the following settings in your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
+
+```yaml
+matrix_prometheus_enabled: true
+
+matrix_synapse_metrics_enabled: true
+matrix_prometheus_node_exporter_enabled: true
+
+matrix_grafana_enabled: true
+matrix_grafana_anonymous_access: true
+matrix_grafana_default_admin_user: yourname
+matrix_grafana_default_admin_password: securelongpassword
+```
+
+## What does it do?
+
+Name | Description
+-----|----------
+`matrix_prometheus_enabled`|Prometheus is a time series database. It holds all the data we're going to talk about.
+`matrix_synapse_metrics_enabled`|Enables metrics specific to Synapse
+`matrix_prometheus_node_exporter_enabled`|Node Exporter is an addon of sorts to Prometheus that collects generic system information such as CPU, memory, filesystem, and even system temperatures
+`matrix_grafana_enabled`|Grafana is the visual component. It shows the dashboards with the graphs that we're interested in
+`matrix_grafana_anonymous_access`|By default you need to login to see graphs. If you want to publicly share your graphs (e.g. when asking for help in [`#synapse:matrix.org`](https://matrix.to/#/#synapse:matrix.org?via=matrix.org&via=privacytools.io&via=mozilla.org)) you'll want to enable this option.
+`matrix_grafana_default_admin_user`<br>`matrix_grafana_default_admin_password`|By default Grafana creates a user with `admin` as the username and password. If you feel this is insecure and you want to change it beforehand, you can do that here
+
+## More inforation
+
+- [Understanding Synapse Performance Issues Through Grafana Graphs](https://github.com/matrix-org/synapse/wiki/Understanding-Synapse-Performance-Issues-Through-Grafana-Graphs) at the Synapse Github Wiki
+- [The Prometheus scraping rules](https://github.com/matrix-org/synapse/tree/master/contrib/prometheus) (we use v2)
+- [The Synapse Grafana dashboard](https://github.com/matrix-org/synapse/tree/master/contrib/grafana)
+- [The Node Exporter dashboard](https://github.com/rfrail3/grafana-dashboards) (for generic non-synapse performance graphs)
+

From 76d7e84be533884ac8148ad3084f1e89cb3e9550 Mon Sep 17 00:00:00 2001
From: Peetz0r <github@haas-en-berg.nl>
Date: Fri, 29 Jan 2021 12:23:59 +0100
Subject: [PATCH 41/66] Make prometheus-node-exporter a bit more capable

By running it in a more privileged container with access to the host network stack and such
---
 .../systemd/matrix-prometheus-node-exporter.service.j2     | 7 +++++--
 roles/matrix-prometheus/templates/prometheus.yml.j2        | 2 +-
 2 files changed, 6 insertions(+), 3 deletions(-)

diff --git a/roles/matrix-prometheus-node-exporter/templates/systemd/matrix-prometheus-node-exporter.service.j2 b/roles/matrix-prometheus-node-exporter/templates/systemd/matrix-prometheus-node-exporter.service.j2
index 622947d08..b7f410f1a 100644
--- a/roles/matrix-prometheus-node-exporter/templates/systemd/matrix-prometheus-node-exporter.service.j2
+++ b/roles/matrix-prometheus-node-exporter/templates/systemd/matrix-prometheus-node-exporter.service.j2
@@ -21,14 +21,17 @@ ExecStart={{ matrix_host_command_docker }} run --rm --name matrix-prometheus-nod
 			--log-driver=none \
 			--user={{ matrix_user_uid }}:{{ matrix_user_gid }} \
 			--cap-drop=ALL \
-			--network={{ matrix_docker_network }} \
 			{% if matrix_prometheus_node_exporter_container_http_host_bind_port %}
 			-p {{ matrix_prometheus_node_exporter_container_http_host_bind_port }}:9100 \
 			{% endif %}
 			{% for arg in matrix_prometheus_node_exporter_container_extra_arguments %}
 			{{ arg }} \
 			{% endfor %}
-			{{ matrix_prometheus_node_exporter_docker_image }}
+			--net="host" \
+			--pid="host" \
+			-v "/:/host:ro,rslave" \
+			{{ matrix_prometheus_node_exporter_docker_image }} \
+			--path.rootfs=/host
 
 ExecStop=-{{ matrix_host_command_sh }} -c '{{ matrix_host_command_docker }} kill matrix-prometheus-node-exporter 2>/dev/null'
 ExecStop=-{{ matrix_host_command_sh }} -c '{{ matrix_host_command_docker }} rm matrix-prometheus-node-exporter 2>/dev/null'
diff --git a/roles/matrix-prometheus/templates/prometheus.yml.j2 b/roles/matrix-prometheus/templates/prometheus.yml.j2
index 317dcd168..6e91ace23 100644
--- a/roles/matrix-prometheus/templates/prometheus.yml.j2
+++ b/roles/matrix-prometheus/templates/prometheus.yml.j2
@@ -36,5 +36,5 @@ scrape_configs:
   {% if matrix_prometheus_node_exporter_enabled %}
   - job_name: node
     static_configs:
-      - targets: ['matrix-prometheus-node-exporter:9100']
+      - targets: ['172.18.0.1:9100']
   {% endif %}

From 1079272563ea95b132bc0fda55358a04c51abbd1 Mon Sep 17 00:00:00 2001
From: Peetz0r <github@haas-en-berg.nl>
Date: Sat, 30 Jan 2021 06:11:44 +0100
Subject: [PATCH 42/66] Mention stats subdomain in docs

---
 docs/configuring-dns.md                         | 3 +++
 docs/configuring-playbook-prometheus-grafana.md | 2 ++
 2 files changed, 5 insertions(+)

diff --git a/docs/configuring-dns.md b/docs/configuring-dns.md
index cef4cd501..84e2cd0bb 100644
--- a/docs/configuring-dns.md
+++ b/docs/configuring-dns.md
@@ -24,6 +24,7 @@ If you decide to go with the alternative method ([Server Delegation via a DNS SR
 | CNAME | `element`                    | -        | -      | -    | `matrix.<your-domain>` |
 | CNAME | `dimension` (*)              | -        | -      | -    | `matrix.<your-domain>` |
 | CNAME | `jitsi` (*)                  | -        | -      | -    | `matrix.<your-domain>` |
+| CNAME | `stats` (*)                  | -        | -      | -    | `matrix.<your-domain>` |
 | SRV   | `_matrix-identity._tcp`      | 10       | 0      | 443  | `matrix.<your-domain>` |
 
 
@@ -42,6 +43,8 @@ The `dimension.<your-domain>` subdomain may be necessary, because this playbook
 
 The `jitsi.<your-domain>` subdomain may be necessary, because this playbook could install the [Jitsi video-conferencing platform](https://jitsi.org/) for you. Jitsi installation is disabled by default, because it may be heavy and is not a core required component. To learn how to install it, see our [Jitsi](configuring-playbook-jitsi.md) guide. If you do not wish to set up Jitsi, feel free to skip the `jitsi.<your-domain>` DNS record.
 
+The `stats.<your-domain>` subdomain may be necessary, because this playbook could install [Grafana](https://grafana.com/) and setup performance metrics for you. Grafana installation is disabled by default, it is not a core required component. To learn how to install it, see our [metrics and graphs guide](configuring-playbook-prometheus-grafana.md). If you do not wish to set up Grafana, feel free to skip the `stats.<your-domain>` DNS record. It is possible to install Prometheus without installing Grafana, this would also not require the `stats.<your-domain>` subdomain.
+
 
 ## `_matrix-identity._tcp` SRV record setup
 
diff --git a/docs/configuring-playbook-prometheus-grafana.md b/docs/configuring-playbook-prometheus-grafana.md
index 5ad1449b2..b714dc2cf 100644
--- a/docs/configuring-playbook-prometheus-grafana.md
+++ b/docs/configuring-playbook-prometheus-grafana.md
@@ -16,6 +16,8 @@ matrix_grafana_default_admin_user: yourname
 matrix_grafana_default_admin_password: securelongpassword
 ```
 
+The dashboards will by default be available on the `stats.<your-domain>` subdomain, proxied via Nginx.
+
 ## What does it do?
 
 Name | Description

From 8aafb44cb86c19d2bfaa8cea296edc954c1428f0 Mon Sep 17 00:00:00 2001
From: Peetz0r <github@haas-en-berg.nl>
Date: Sat, 30 Jan 2021 06:38:15 +0100
Subject: [PATCH 43/66] Mention new images in docks

---
 docs/container-images.md | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/docs/container-images.md b/docs/container-images.md
index aee24b045..28fce950a 100644
--- a/docs/container-images.md
+++ b/docs/container-images.md
@@ -85,3 +85,9 @@ These services are not part of our default installation, but can be enabled by [
 - [anoa/matrix-reminder-bot](https://hub.docker.com/r/anoa/matrix-reminder-bot) - the [matrix-reminder-bot](https://github.com/anoadragon453/matrix-reminder-bot) bot for one-off & recurring reminders and alarms (optional)
 
 - [awesometechnologies/synapse-admin](https://hub.docker.com/r/awesometechnologies/synapse-admin) - the [synapse-admin](https://github.com/Awesome-Technologies/synapse-admin) web UI tool for administrating users and rooms on your Matrix server (optional)
+
+- [prom/prometheus](https://hub.docker.com/r/prom/prometheus/) - [Prometheus](https://github.com/prometheus/prometheus/) is a systems and service monitoring system
+
+- [prom/node-exporter](https://hub.docker.com/r/prom/node-exporter/) - [Prometheus Node Exporter](https://github.com/prometheus/node_exporter/) is an addon for Prometheus that gathers standard system metrics
+
+- [grafana/grafana](https://hub.docker.com/r/grafana/grafana/) - [Grafana](https://github.com/grafana/grafana/) is a graphing tool that works well with the above two images. Our playbook also adds two dashboards for [Synapse](https://github.com/matrix-org/synapse/tree/master/contrib/grafana) and  [Node Exporter](https://github.com/rfrail3/grafana-dashboards)

From da82d670af40140923fee9703d3c5487df1b6805 Mon Sep 17 00:00:00 2001
From: Peetz0r <github@haas-en-berg.nl>
Date: Sat, 30 Jan 2021 07:43:26 +0100
Subject: [PATCH 44/66] Document security and privacy considerations for stats.

---
 docs/configuring-playbook-prometheus-grafana.md | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/docs/configuring-playbook-prometheus-grafana.md b/docs/configuring-playbook-prometheus-grafana.md
index b714dc2cf..9e2c5dd40 100644
--- a/docs/configuring-playbook-prometheus-grafana.md
+++ b/docs/configuring-playbook-prometheus-grafana.md
@@ -29,6 +29,12 @@ Name | Description
 `matrix_grafana_anonymous_access`|By default you need to login to see graphs. If you want to publicly share your graphs (e.g. when asking for help in [`#synapse:matrix.org`](https://matrix.to/#/#synapse:matrix.org?via=matrix.org&via=privacytools.io&via=mozilla.org)) you'll want to enable this option.
 `matrix_grafana_default_admin_user`<br>`matrix_grafana_default_admin_password`|By default Grafana creates a user with `admin` as the username and password. If you feel this is insecure and you want to change it beforehand, you can do that here
 
+## Security and privacy
+
+Metrics and resulting graphs can contain a lot if information. This includes system specs but also usage patterns. This applies especially to small personal/family scale homeservers. Someone might be able to figure out when you wake up and go to sleep by looking at the graphs over time. Think about this before enabling anonymous access. And you should really not forget to change your Grafana password.
+
+Most of our docker containers run with limited system access, but the `prometheus-node-exporter` has access to the host network stack and (readonly) root filesystem. This is required to report on them. If you don't like that, you can set `matrix_prometheus_node_exporter_enabled: false` (which is actually the default). You will still get Synapse metrics with this container disabled. Both of the dashboards will always be enabled, so you can still look at historical data after disabling either source.
+
 ## More inforation
 
 - [Understanding Synapse Performance Issues Through Grafana Graphs](https://github.com/matrix-org/synapse/wiki/Understanding-Synapse-Performance-Issues-Through-Grafana-Graphs) at the Synapse Github Wiki

From 144a5e61983e77045247c5b7aaade0aba43be84d Mon Sep 17 00:00:00 2001
From: Peetz0r <github@haas-en-berg.nl>
Date: Sun, 31 Jan 2021 02:09:12 +0100
Subject: [PATCH 45/66] Register docker network info and use it for
 prometheus-node-exporter

Using the hardcoded IP did break while I was
messing with IPv6 stuff on the other branch
---
 roles/matrix-base/tasks/setup_matrix_base.yml       | 1 +
 roles/matrix-prometheus/templates/prometheus.yml.j2 | 2 +-
 2 files changed, 2 insertions(+), 1 deletion(-)

diff --git a/roles/matrix-base/tasks/setup_matrix_base.yml b/roles/matrix-base/tasks/setup_matrix_base.yml
index 0fad2b3d6..b74b0316d 100644
--- a/roles/matrix-base/tasks/setup_matrix_base.yml
+++ b/roles/matrix-base/tasks/setup_matrix_base.yml
@@ -23,6 +23,7 @@
   docker_network:
     name: "{{ matrix_docker_network }}"
     driver: bridge
+  register: matrix_docker_network_info
 
 - name: Ensure matrix-remove-all script created
   template:
diff --git a/roles/matrix-prometheus/templates/prometheus.yml.j2 b/roles/matrix-prometheus/templates/prometheus.yml.j2
index 6e91ace23..08e6fcf1c 100644
--- a/roles/matrix-prometheus/templates/prometheus.yml.j2
+++ b/roles/matrix-prometheus/templates/prometheus.yml.j2
@@ -36,5 +36,5 @@ scrape_configs:
   {% if matrix_prometheus_node_exporter_enabled %}
   - job_name: node
     static_configs:
-      - targets: ['172.18.0.1:9100']
+      - targets: ['{{ matrix_docker_network_info.network.IPAM.Config[0].Gateway }}:9100']
   {% endif %}

From 3a77261dc60ef00f51f598ef38d00895e5e931e0 Mon Sep 17 00:00:00 2001
From: Peetz0r <github@haas-en-berg.nl>
Date: Wed, 10 Feb 2021 23:11:02 +0100
Subject: [PATCH 46/66] Update Grafana 7.3.7 => 7.4.0

---
 roles/matrix-grafana/defaults/main.yml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/roles/matrix-grafana/defaults/main.yml b/roles/matrix-grafana/defaults/main.yml
index 2257d7941..00ed947e7 100644
--- a/roles/matrix-grafana/defaults/main.yml
+++ b/roles/matrix-grafana/defaults/main.yml
@@ -3,7 +3,7 @@
 
 matrix_grafana_enabled: false
 
-matrix_grafana_docker_image: "docker.io/grafana/grafana:7.3.7"
+matrix_grafana_docker_image: "docker.io/grafana/grafana:7.4.0"
 matrix_grafana_docker_image_force_pull: "{{ matrix_grafana_docker_image.endswith(':latest') }}"
 
 # Not conditional, because when someone disables metrics
@@ -12,7 +12,7 @@ matrix_grafana_docker_image_force_pull: "{{ matrix_grafana_docker_image.endswith
 matrix_grafana_dashboard_download_urls:
 - "https://raw.githubusercontent.com/matrix-org/synapse/master/contrib/grafana/synapse.json"
 - "https://raw.githubusercontent.com/rfrail3/grafana-dashboards/master/prometheus/node-exporter-full.json"
-  
+
 matrix_grafana_base_path: "{{ matrix_base_data_path }}/grafana"
 matrix_grafana_config_path: "{{ matrix_grafana_base_path }}/config"
 matrix_grafana_data_path: "{{ matrix_grafana_base_path }}/data"

From fde222a0417a66220784a4c59778f82850719321 Mon Sep 17 00:00:00 2001
From: Peetz0r <github@haas-en-berg.nl>
Date: Wed, 10 Feb 2021 23:11:17 +0100
Subject: [PATCH 47/66] Update Prometheus Node Exporter 1.0.1 => 1.1.0

---
 roles/matrix-prometheus-node-exporter/defaults/main.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/roles/matrix-prometheus-node-exporter/defaults/main.yml b/roles/matrix-prometheus-node-exporter/defaults/main.yml
index a5664b836..29dce3648 100644
--- a/roles/matrix-prometheus-node-exporter/defaults/main.yml
+++ b/roles/matrix-prometheus-node-exporter/defaults/main.yml
@@ -3,7 +3,7 @@
 
 matrix_prometheus_node_exporter_enabled: false
 
-matrix_prometheus_node_exporter_docker_image: "docker.io/prom/node-exporter:v1.0.1"
+matrix_prometheus_node_exporter_docker_image: "docker.io/prom/node-exporter:v1.1.0"
 matrix_prometheus_node_exporter_docker_image_force_pull: "{{ matrix_prometheus_node_exporter_docker_image.endswith(':latest') }}"
 
 # A list of extra arguments to pass to the container

From b7e68cb779bc5c125eb03cb406807efda814f737 Mon Sep 17 00:00:00 2001
From: efraimbart <efraimbart@gmail.com>
Date: Thu, 11 Feb 2021 22:56:37 -0500
Subject: [PATCH 48/66] Fix wrong docker image being pulled

Changed `matrix_mautrix_signal_docker_image_force_pull` to `matrix_mautrix_signal_daemon_docker_image_force_pull` when force pulling the daemon
---
 roles/matrix-bridge-mautrix-signal/tasks/setup_install.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/roles/matrix-bridge-mautrix-signal/tasks/setup_install.yml b/roles/matrix-bridge-mautrix-signal/tasks/setup_install.yml
index d6c3c24dd..61c6adff8 100644
--- a/roles/matrix-bridge-mautrix-signal/tasks/setup_install.yml
+++ b/roles/matrix-bridge-mautrix-signal/tasks/setup_install.yml
@@ -21,7 +21,7 @@
     name: "{{ matrix_mautrix_signal_daemon_docker_image }}"
     source: "{{ 'pull' if ansible_version.major > 2 or ansible_version.minor > 7 else omit }}"
     force_source: "{{ matrix_mautrix_signal_daemon_docker_image_force_pull if ansible_version.major > 2 or ansible_version.minor >= 8 else omit }}"
-    force: "{{ omit if ansible_version.major > 2 or ansible_version.minor >= 8 else matrix_mautrix_signal_docker_image_force_pull }}"
+    force: "{{ omit if ansible_version.major > 2 or ansible_version.minor >= 8 else matrix_mautrix_signal_daemon_docker_image_force_pull }}"
   when: matrix_mautrix_signal_enabled|bool
 
 - name: Ensure Mautrix Signal paths exist

From 9531d137869af24ea14f8583997c599f576bd7fd Mon Sep 17 00:00:00 2001
From: Peetz0r <github@haas-en-berg.nl>
Date: Sat, 30 Jan 2021 08:05:52 +0100
Subject: [PATCH 49/66] Split DNS table in default and optional parts

---
 docs/configuring-dns.md | 19 +++++++++++--------
 1 file changed, 11 insertions(+), 8 deletions(-)

diff --git a/docs/configuring-dns.md b/docs/configuring-dns.md
index 84e2cd0bb..c25b079e8 100644
--- a/docs/configuring-dns.md
+++ b/docs/configuring-dns.md
@@ -15,22 +15,25 @@ As we discuss in [Server Delegation](howto-server-delegation.md), there are 2 di
 This playbook mostly discusses the well-known file method, because it's easier to manage with regard to certificates.
 If you decide to go with the alternative method ([Server Delegation via a DNS SRV record (advanced)](howto-server-delegation.md#server-delegation-via-a-dns-srv-record-advanced)), please be aware that the general flow that this playbook guides you through may not match what you need to do.
 
-
-## General outline of DNS settings you need to do
+## Required DNS settings for services enabled by default
 
 | Type  | Host                         | Priority | Weight | Port | Target                 |
 | ----- | ---------------------------- | -------- | ------ | ---- | ---------------------- |
 | A     | `matrix`                     | -        | -      | -    | `matrix-server-IP`     |
 | CNAME | `element`                    | -        | -      | -    | `matrix.<your-domain>` |
+| SRV   | `_matrix-identity._tcp`      | 10       | 0      | 443  | `matrix.<your-domain>` |
+
+Be mindful as to how long it will take for the DNS records to propagate.
+
+If you are using Cloudflare DNS, make sure to disable the proxy and set all records to `DNS only`. Otherwise, fetching certificates will fail.
+
+## Required DNS settings for optional services
+
+| Type  | Host                         | Priority | Weight | Port | Target                 |
+| ----- | ---------------------------- | -------- | ------ | ---- | ---------------------- |
 | CNAME | `dimension` (*)              | -        | -      | -    | `matrix.<your-domain>` |
 | CNAME | `jitsi` (*)                  | -        | -      | -    | `matrix.<your-domain>` |
 | CNAME | `stats` (*)                  | -        | -      | -    | `matrix.<your-domain>` |
-| SRV   | `_matrix-identity._tcp`      | 10       | 0      | 443  | `matrix.<your-domain>` |
-
-
-DNS records marked with `(*)` above are optional. They refer to services that will not be installed by default (see the section below). If you won't be installing these services, feel free to skip creating these DNS records. Also be mindful as to how long it will take for the DNS records to propagate.
-
->  If you are using Cloudflare DNS, make sure to disable the proxy and set all records to `DNS only`. Otherwise, fetching certificates will fail.
 
 ## Subdomains setup
 

From f0cd29462845c70ba8b1e25bb8c5a927b4a7a207 Mon Sep 17 00:00:00 2001
From: Slavi Pantaleev <slavi@devture.com>
Date: Sun, 31 Jan 2021 11:41:22 +0200
Subject: [PATCH 50/66] Fix matrix-prometheus-node-exporter failure to start

The quotes around "host" for both `--pid` and `--net` were
causing trouble for me:

> docker: --pid: invalid PID mode.

and:

> docker: Error response from daemon: network "host" not found.

I've also changed the `-v` call to `--mount` for consistency with the
rest of the playbook.
---
 .../systemd/matrix-prometheus-node-exporter.service.j2      | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/roles/matrix-prometheus-node-exporter/templates/systemd/matrix-prometheus-node-exporter.service.j2 b/roles/matrix-prometheus-node-exporter/templates/systemd/matrix-prometheus-node-exporter.service.j2
index b7f410f1a..583494448 100644
--- a/roles/matrix-prometheus-node-exporter/templates/systemd/matrix-prometheus-node-exporter.service.j2
+++ b/roles/matrix-prometheus-node-exporter/templates/systemd/matrix-prometheus-node-exporter.service.j2
@@ -27,9 +27,9 @@ ExecStart={{ matrix_host_command_docker }} run --rm --name matrix-prometheus-nod
 			{% for arg in matrix_prometheus_node_exporter_container_extra_arguments %}
 			{{ arg }} \
 			{% endfor %}
-			--net="host" \
-			--pid="host" \
-			-v "/:/host:ro,rslave" \
+			--net=host \
+			--pid=host \
+			--mount type=bind,src=/,dst=/host,ro,bind-propagation=rslave \
 			{{ matrix_prometheus_node_exporter_docker_image }} \
 			--path.rootfs=/host
 

From 3ce97123888473cd29fab16a847196fd1538d724 Mon Sep 17 00:00:00 2001
From: Slavi Pantaleev <slavi@devture.com>
Date: Sun, 31 Jan 2021 12:01:56 +0200
Subject: [PATCH 51/66] Fix Grafana dashboard/datasource label

---
 roles/matrix-grafana/templates/dashboards.yaml.j2  | 2 +-
 roles/matrix-grafana/templates/datasources.yaml.j2 | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/roles/matrix-grafana/templates/dashboards.yaml.j2 b/roles/matrix-grafana/templates/dashboards.yaml.j2
index b6662e597..aae42ba29 100644
--- a/roles/matrix-grafana/templates/dashboards.yaml.j2
+++ b/roles/matrix-grafana/templates/dashboards.yaml.j2
@@ -1,7 +1,7 @@
 apiVersion: 1
 
 providers:
-  - name: {{ matrix_domain }} - Dashboards
+  - name: {{ matrix_server_fqn_matrix }} - Dashboards
     folder: '' # The folder where to place the dashboards
     type: file
     allowUiUpdates: true
diff --git a/roles/matrix-grafana/templates/datasources.yaml.j2 b/roles/matrix-grafana/templates/datasources.yaml.j2
index ffa6046b0..6ccbe3742 100644
--- a/roles/matrix-grafana/templates/datasources.yaml.j2
+++ b/roles/matrix-grafana/templates/datasources.yaml.j2
@@ -1,7 +1,7 @@
 apiVersion: 1
 
 datasources:
-  - name: {{ matrix_domain }} - Prometheus
+  - name: {{ matrix_server_fqn_matrix }} - Prometheus
     type: prometheus
     # Access mode - proxy (server in the UI) or direct (browser in the UI).
     access: proxy

From 1d7d99c5cd94c961d7fc78c6fb9e6b67ce7ec99c Mon Sep 17 00:00:00 2001
From: Slavi Pantaleev <slavi@devture.com>
Date: Sun, 31 Jan 2021 12:02:14 +0200
Subject: [PATCH 52/66] Improve metrics docs page a bit

We mainly switch the anonymous metrics viewing variable
to false, along with other wording changes.
---
 docs/configuring-playbook-prometheus-grafana.md | 11 ++++++++---
 1 file changed, 8 insertions(+), 3 deletions(-)

diff --git a/docs/configuring-playbook-prometheus-grafana.md b/docs/configuring-playbook-prometheus-grafana.md
index 9e2c5dd40..0c759692d 100644
--- a/docs/configuring-playbook-prometheus-grafana.md
+++ b/docs/configuring-playbook-prometheus-grafana.md
@@ -1,6 +1,6 @@
 # Enabling metrics and graphs for your Matrix server (optional)
 
-It can be useful to have some (visual) insight in the performance of your homeserver.
+It can be useful to have some (visual) insight into the performance of your homeserver.
 
 You can enable this with the following settings in your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
 
@@ -11,8 +11,13 @@ matrix_synapse_metrics_enabled: true
 matrix_prometheus_node_exporter_enabled: true
 
 matrix_grafana_enabled: true
-matrix_grafana_anonymous_access: true
+
+matrix_grafana_anonymous_access: false
+
 matrix_grafana_default_admin_user: yourname
+
+# Passwords containing special characters may be troublesome.
+# Changing the password subsequently won't work.
 matrix_grafana_default_admin_password: securelongpassword
 ```
 
@@ -26,7 +31,7 @@ Name | Description
 `matrix_synapse_metrics_enabled`|Enables metrics specific to Synapse
 `matrix_prometheus_node_exporter_enabled`|Node Exporter is an addon of sorts to Prometheus that collects generic system information such as CPU, memory, filesystem, and even system temperatures
 `matrix_grafana_enabled`|Grafana is the visual component. It shows the dashboards with the graphs that we're interested in
-`matrix_grafana_anonymous_access`|By default you need to login to see graphs. If you want to publicly share your graphs (e.g. when asking for help in [`#synapse:matrix.org`](https://matrix.to/#/#synapse:matrix.org?via=matrix.org&via=privacytools.io&via=mozilla.org)) you'll want to enable this option.
+`matrix_grafana_anonymous_access`|By default you need to log in to see graphs. If you want to publicly share your graphs (e.g. when asking for help in [`#synapse:matrix.org`](https://matrix.to/#/#synapse:matrix.org?via=matrix.org&via=privacytools.io&via=mozilla.org)) you'll want to enable this option.
 `matrix_grafana_default_admin_user`<br>`matrix_grafana_default_admin_password`|By default Grafana creates a user with `admin` as the username and password. If you feel this is insecure and you want to change it beforehand, you can do that here
 
 ## Security and privacy

From df3dd1c82459b61b4ed549797580de4c37ebad4b Mon Sep 17 00:00:00 2001
From: Slavi Pantaleev <slavi@devture.com>
Date: Sun, 31 Jan 2021 17:34:32 +0200
Subject: [PATCH 53/66] Use --read-only FS for metrics-related containers

It seems like it doesn't cause any issues for any of these services.
---
 roles/matrix-grafana/templates/systemd/matrix-grafana.service.j2 | 1 +
 .../templates/systemd/matrix-prometheus-node-exporter.service.j2 | 1 +
 .../templates/systemd/matrix-prometheus.service.j2               | 1 +
 3 files changed, 3 insertions(+)

diff --git a/roles/matrix-grafana/templates/systemd/matrix-grafana.service.j2 b/roles/matrix-grafana/templates/systemd/matrix-grafana.service.j2
index f2ab66424..a4f81e357 100644
--- a/roles/matrix-grafana/templates/systemd/matrix-grafana.service.j2
+++ b/roles/matrix-grafana/templates/systemd/matrix-grafana.service.j2
@@ -21,6 +21,7 @@ ExecStart={{ matrix_host_command_docker }} run --rm --name matrix-grafana \
 			--log-driver=none \
 			--user={{ matrix_user_uid }}:{{ matrix_user_gid }} \
 			--cap-drop=ALL \
+			--read-only \
 			--network={{ matrix_docker_network }} \
 			{% if matrix_grafana_container_http_host_bind_port %}
 			-p {{ matrix_grafana_container_http_host_bind_port }}:3000 \
diff --git a/roles/matrix-prometheus-node-exporter/templates/systemd/matrix-prometheus-node-exporter.service.j2 b/roles/matrix-prometheus-node-exporter/templates/systemd/matrix-prometheus-node-exporter.service.j2
index 583494448..93638c191 100644
--- a/roles/matrix-prometheus-node-exporter/templates/systemd/matrix-prometheus-node-exporter.service.j2
+++ b/roles/matrix-prometheus-node-exporter/templates/systemd/matrix-prometheus-node-exporter.service.j2
@@ -21,6 +21,7 @@ ExecStart={{ matrix_host_command_docker }} run --rm --name matrix-prometheus-nod
 			--log-driver=none \
 			--user={{ matrix_user_uid }}:{{ matrix_user_gid }} \
 			--cap-drop=ALL \
+			--read-only \
 			{% if matrix_prometheus_node_exporter_container_http_host_bind_port %}
 			-p {{ matrix_prometheus_node_exporter_container_http_host_bind_port }}:9100 \
 			{% endif %}
diff --git a/roles/matrix-prometheus/templates/systemd/matrix-prometheus.service.j2 b/roles/matrix-prometheus/templates/systemd/matrix-prometheus.service.j2
index dd3ac72cb..ad75d664a 100644
--- a/roles/matrix-prometheus/templates/systemd/matrix-prometheus.service.j2
+++ b/roles/matrix-prometheus/templates/systemd/matrix-prometheus.service.j2
@@ -21,6 +21,7 @@ ExecStart={{ matrix_host_command_docker }} run --rm --name matrix-prometheus \
 			--log-driver=none \
 			--user={{ matrix_user_uid }}:{{ matrix_user_gid }} \
 			--cap-drop=ALL \
+			--read-only \
 			--network={{ matrix_docker_network }} \
 			{% if matrix_prometheus_container_http_host_bind_port %}
 			-p {{ matrix_prometheus_container_http_host_bind_port }}:9090 \

From 85a260daaf5d04795f2be4a8de09fac26be57ecd Mon Sep 17 00:00:00 2001
From: Slavi Pantaleev <slavi@devture.com>
Date: Sun, 31 Jan 2021 18:17:57 +0200
Subject: [PATCH 54/66] Make --tags=setup-prometheus not break, relying on
 matrix-base facts

---
 roles/matrix-base/tasks/setup_matrix_base.yml   |  1 -
 roles/matrix-prometheus/defaults/main.yml       |  3 +++
 roles/matrix-prometheus/tasks/setup.yml         | 17 ++++++++++++++++-
 .../templates/prometheus.yml.j2                 |  2 +-
 4 files changed, 20 insertions(+), 3 deletions(-)

diff --git a/roles/matrix-base/tasks/setup_matrix_base.yml b/roles/matrix-base/tasks/setup_matrix_base.yml
index b74b0316d..0fad2b3d6 100644
--- a/roles/matrix-base/tasks/setup_matrix_base.yml
+++ b/roles/matrix-base/tasks/setup_matrix_base.yml
@@ -23,7 +23,6 @@
   docker_network:
     name: "{{ matrix_docker_network }}"
     driver: bridge
-  register: matrix_docker_network_info
 
 - name: Ensure matrix-remove-all script created
   template:
diff --git a/roles/matrix-prometheus/defaults/main.yml b/roles/matrix-prometheus/defaults/main.yml
index 104244241..a0e79acc0 100644
--- a/roles/matrix-prometheus/defaults/main.yml
+++ b/roles/matrix-prometheus/defaults/main.yml
@@ -26,6 +26,9 @@ matrix_prometheus_systemd_wanted_services_list: []
 # Takes an "<ip>:<port>" or "<port>" value (e.g. "127.0.0.1:9090"), or empty string to not expose.
 matrix_prometheus_container_http_host_bind_port: ''
 
+# Target addresses for the "node" scraper configuration.
+# Unless you define this as a non-empty list, it gets populated at runtime with the IP address of `matrix-prometheus-node-exporter` and port 9100.
+matrix_prometheus_endpoint_node_targets: []
 
 # Default prometheus configuration template which covers the generic use case.
 # You can customize it by controlling the various variables inside it.
diff --git a/roles/matrix-prometheus/tasks/setup.yml b/roles/matrix-prometheus/tasks/setup.yml
index 1746b9617..c9a207eca 100644
--- a/roles/matrix-prometheus/tasks/setup.yml
+++ b/roles/matrix-prometheus/tasks/setup.yml
@@ -24,7 +24,22 @@
     - "{{ matrix_prometheus_config_path }}"
     - "{{ matrix_prometheus_data_path }}"
   when: matrix_prometheus_enabled|bool
-  
+
+- block:
+    # Well, this actually creates the network if it doesn't exist, but..
+    # The network should have been created by `matrix-base` already.
+    # We don't rely on that other call and its result, because it runs
+    # on `--tags=setup-all`, but will get skipped during `--tags=setup-prometheus`.
+    - name: Fetch Matrix Docker network details
+      docker_network:
+        name: "{{ matrix_docker_network }}"
+        driver: bridge
+      register: matrix_docker_network_info
+
+    - set_fact:
+        matrix_prometheus_endpoint_node_targets: ["{{ matrix_docker_network_info.network.IPAM.Config[0].Gateway }}:9100"]
+  when: "matrix_prometheus_enabled|bool and matrix_prometheus_node_exporter_enabled|bool and matrix_prometheus_endpoint_node_targets|length == 0"
+
 - name: Ensure prometheus.yml installed
   copy:
     content: "{{ matrix_prometheus_configuration|to_nice_yaml }}"
diff --git a/roles/matrix-prometheus/templates/prometheus.yml.j2 b/roles/matrix-prometheus/templates/prometheus.yml.j2
index 08e6fcf1c..4fdf9905c 100644
--- a/roles/matrix-prometheus/templates/prometheus.yml.j2
+++ b/roles/matrix-prometheus/templates/prometheus.yml.j2
@@ -36,5 +36,5 @@ scrape_configs:
   {% if matrix_prometheus_node_exporter_enabled %}
   - job_name: node
     static_configs:
-      - targets: ['{{ matrix_docker_network_info.network.IPAM.Config[0].Gateway }}:9100']
+      - targets: {{ matrix_prometheus_endpoint_node_targets|to_json }}
   {% endif %}

From 18e31526a885cd9590b8d639e75da507db29fa35 Mon Sep 17 00:00:00 2001
From: Slavi Pantaleev <slavi@devture.com>
Date: Sun, 31 Jan 2021 18:26:08 +0200
Subject: [PATCH 55/66] Rename some variables

---
 group_vars/matrix_servers                           | 2 ++
 roles/matrix-prometheus/defaults/main.yml           | 6 +++++-
 roles/matrix-prometheus/tasks/setup.yml             | 4 ++--
 roles/matrix-prometheus/templates/prometheus.yml.j2 | 4 ++--
 4 files changed, 11 insertions(+), 5 deletions(-)

diff --git a/group_vars/matrix_servers b/group_vars/matrix_servers
index b314dc99c..ad700597d 100755
--- a/group_vars/matrix_servers
+++ b/group_vars/matrix_servers
@@ -1405,6 +1405,8 @@ matrix_prometheus_enabled: false
 # Prometheus' HTTP port to the local host.
 matrix_prometheus_container_http_host_bind_port: "{{ '' if matrix_nginx_proxy_enabled else '127.0.0.1:9090' }}"
 
+matrix_prometheus_scraper_node_enabled: "{{ matrix_prometheus_node_exporter_enabled }}"
+
 ######################################################################
 #
 # /matrix-prometheus
diff --git a/roles/matrix-prometheus/defaults/main.yml b/roles/matrix-prometheus/defaults/main.yml
index a0e79acc0..c07c38018 100644
--- a/roles/matrix-prometheus/defaults/main.yml
+++ b/roles/matrix-prometheus/defaults/main.yml
@@ -26,9 +26,13 @@ matrix_prometheus_systemd_wanted_services_list: []
 # Takes an "<ip>:<port>" or "<port>" value (e.g. "127.0.0.1:9090"), or empty string to not expose.
 matrix_prometheus_container_http_host_bind_port: ''
 
+# Tells whether the "node" scraper configuration is enabled.
+# This configuration aims to scrape the current node (this server).
+matrix_prometheus_scraper_node_enabled: false
+
 # Target addresses for the "node" scraper configuration.
 # Unless you define this as a non-empty list, it gets populated at runtime with the IP address of `matrix-prometheus-node-exporter` and port 9100.
-matrix_prometheus_endpoint_node_targets: []
+matrix_prometheus_scraper_node_targets: []
 
 # Default prometheus configuration template which covers the generic use case.
 # You can customize it by controlling the various variables inside it.
diff --git a/roles/matrix-prometheus/tasks/setup.yml b/roles/matrix-prometheus/tasks/setup.yml
index c9a207eca..7b98b76ab 100644
--- a/roles/matrix-prometheus/tasks/setup.yml
+++ b/roles/matrix-prometheus/tasks/setup.yml
@@ -37,8 +37,8 @@
       register: matrix_docker_network_info
 
     - set_fact:
-        matrix_prometheus_endpoint_node_targets: ["{{ matrix_docker_network_info.network.IPAM.Config[0].Gateway }}:9100"]
-  when: "matrix_prometheus_enabled|bool and matrix_prometheus_node_exporter_enabled|bool and matrix_prometheus_endpoint_node_targets|length == 0"
+        matrix_prometheus_scraper_node_targets: ["{{ matrix_docker_network_info.network.IPAM.Config[0].Gateway }}:9100"]
+  when: "matrix_prometheus_enabled|bool and matrix_prometheus_scraper_node_enabled|bool and matrix_prometheus_scraper_node_targets|length == 0"
 
 - name: Ensure prometheus.yml installed
   copy:
diff --git a/roles/matrix-prometheus/templates/prometheus.yml.j2 b/roles/matrix-prometheus/templates/prometheus.yml.j2
index 4fdf9905c..4fe8394df 100644
--- a/roles/matrix-prometheus/templates/prometheus.yml.j2
+++ b/roles/matrix-prometheus/templates/prometheus.yml.j2
@@ -33,8 +33,8 @@ scrape_configs:
     - targets: ['matrix-synapse:{{ matrix_synapse_metrics_port }}']
   {% endif %}
 
-  {% if matrix_prometheus_node_exporter_enabled %}
+  {% if matrix_prometheus_scraper_node_enabled %}
   - job_name: node
     static_configs:
-      - targets: {{ matrix_prometheus_endpoint_node_targets|to_json }}
+      - targets: {{ matrix_prometheus_scraper_node_targets|to_json }}
   {% endif %}

From 6842102e008a0682bc676793556f32c2593ff723 Mon Sep 17 00:00:00 2001
From: Slavi Pantaleev <slavi@devture.com>
Date: Sun, 31 Jan 2021 18:30:02 +0200
Subject: [PATCH 56/66] Split install/uninstall tasks in matrix-prometheus

---
 roles/matrix-prometheus/tasks/main.yml        |  9 +++-
 .../tasks/{setup.yml => setup_install.yml}    | 48 +------------------
 .../tasks/setup_uninstall.yml                 | 31 ++++++++++++
 3 files changed, 41 insertions(+), 47 deletions(-)
 rename roles/matrix-prometheus/tasks/{setup.yml => setup_install.yml} (59%)
 create mode 100644 roles/matrix-prometheus/tasks/setup_uninstall.yml

diff --git a/roles/matrix-prometheus/tasks/main.yml b/roles/matrix-prometheus/tasks/main.yml
index 2290048f3..edb019881 100644
--- a/roles/matrix-prometheus/tasks/main.yml
+++ b/roles/matrix-prometheus/tasks/main.yml
@@ -8,7 +8,14 @@
     - setup-all
     - setup-prometheus
 
-- import_tasks: "{{ role_path }}/tasks/setup.yml"
+- import_tasks: "{{ role_path }}/tasks/setup_install.yml"
+  when: "run_setup|bool and matrix_prometheus_enabled|bool"
+  tags:
+    - setup-all
+    - setup-prometheus
+
+- import_tasks: "{{ role_path }}/tasks/setup_uninstall.yml"
+  when: "run_setup|bool and not matrix_prometheus_enabled|bool"
   tags:
     - setup-all
     - setup-prometheus
diff --git a/roles/matrix-prometheus/tasks/setup.yml b/roles/matrix-prometheus/tasks/setup_install.yml
similarity index 59%
rename from roles/matrix-prometheus/tasks/setup.yml
rename to roles/matrix-prometheus/tasks/setup_install.yml
index 7b98b76ab..b69e349d8 100644
--- a/roles/matrix-prometheus/tasks/setup.yml
+++ b/roles/matrix-prometheus/tasks/setup_install.yml
@@ -1,16 +1,11 @@
 ---
 
-#
-# Tasks related to setting up matrix-prometheus
-#
-
 - name: Ensure matrix-prometheus image is pulled
   docker_image:
     name: "{{ matrix_prometheus_docker_image }}"
     source: "{{ 'pull' if ansible_version.major > 2 or ansible_version.minor > 7 else omit }}"
     force_source: "{{ matrix_prometheus_docker_image_force_pull if ansible_version.major > 2 or ansible_version.minor >= 8 else omit }}"
     force: "{{ omit if ansible_version.major > 2 or ansible_version.minor >= 8 else matrix_prometheus_docker_image_force_pull }}"
-  when: "matrix_prometheus_enabled|bool"
 
 - name: Ensure Prometheus paths exists
   file:
@@ -23,7 +18,6 @@
     - "{{ matrix_prometheus_base_path }}"
     - "{{ matrix_prometheus_config_path }}"
     - "{{ matrix_prometheus_data_path }}"
-  when: matrix_prometheus_enabled|bool
 
 - block:
     # Well, this actually creates the network if it doesn't exist, but..
@@ -38,7 +32,7 @@
 
     - set_fact:
         matrix_prometheus_scraper_node_targets: ["{{ matrix_docker_network_info.network.IPAM.Config[0].Gateway }}:9100"]
-  when: "matrix_prometheus_enabled|bool and matrix_prometheus_scraper_node_enabled|bool and matrix_prometheus_scraper_node_targets|length == 0"
+  when: "matrix_prometheus_scraper_node_enabled|bool and matrix_prometheus_scraper_node_targets|length == 0"
 
 - name: Ensure prometheus.yml installed
   copy:
@@ -47,7 +41,6 @@
     mode: 0644
     owner: "{{ matrix_user_username }}"
     group: "{{ matrix_user_groupname }}"
-  when: matrix_prometheus_enabled|bool
 
 - name: Download synapse-v2.rules
   get_url:
@@ -57,8 +50,6 @@
     mode: 0440
     owner: "{{ matrix_user_username }}"
     group: "{{ matrix_user_groupname }}"
-  when: matrix_prometheus_enabled|bool
-
 
 - name: Ensure matrix-prometheus.service installed
   template:
@@ -66,43 +57,8 @@
     dest: "{{ matrix_systemd_path }}/matrix-prometheus.service"
     mode: 0644
   register: matrix_prometheus_systemd_service_result
-  when: matrix_prometheus_enabled|bool
 
 - name: Ensure systemd reloaded after matrix-prometheus.service installation
   service:
     daemon_reload: yes
-  when: "matrix_prometheus_enabled|bool and matrix_prometheus_systemd_service_result.changed"
-
-#
-# Tasks related to getting rid of matrix-prometheus (if it was previously enabled)
-#
-
-- name: Check existence of matrix-prometheus service
-  stat:
-    path: "{{ matrix_systemd_path }}/matrix-prometheus.service"
-  register: matrix_prometheus_service_stat
-
-- name: Ensure matrix-prometheus is stopped
-  service:
-    name: matrix-prometheus
-    state: stopped
-    daemon_reload: yes
-  register: stopping_result
-  when: "not matrix_prometheus_enabled|bool and matrix_prometheus_service_stat.stat.exists"
-
-- name: Ensure matrix-prometheus.service doesn't exist
-  file:
-    path: "{{ matrix_systemd_path }}/matrix-prometheus.service"
-    state: absent
-  when: "not matrix_prometheus_enabled|bool and matrix_prometheus_service_stat.stat.exists"
-
-- name: Ensure systemd reloaded after matrix-prometheus.service removal
-  service:
-    daemon_reload: yes
-  when: "not matrix_prometheus_enabled|bool and matrix_prometheus_service_stat.stat.exists"
-
-- name: Ensure matrix-prometheus Docker image doesn't exist
-  docker_image:
-    name: "{{ matrix_prometheus_docker_image }}"
-    state: absent
-  when: "not matrix_prometheus_enabled|bool"
+  when: "matrix_prometheus_systemd_service_result.changed|bool"
diff --git a/roles/matrix-prometheus/tasks/setup_uninstall.yml b/roles/matrix-prometheus/tasks/setup_uninstall.yml
new file mode 100644
index 000000000..0a4a8cb64
--- /dev/null
+++ b/roles/matrix-prometheus/tasks/setup_uninstall.yml
@@ -0,0 +1,31 @@
+---
+
+- name: Check existence of matrix-prometheus service
+  stat:
+    path: "{{ matrix_systemd_path }}/matrix-prometheus.service"
+  register: matrix_prometheus_service_stat
+
+- name: Ensure matrix-prometheus is stopped
+  service:
+    name: matrix-prometheus
+    state: stopped
+    daemon_reload: yes
+  register: stopping_result
+  when: "matrix_prometheus_service_stat.stat.exists|bool"
+
+- name: Ensure matrix-prometheus.service doesn't exist
+  file:
+    path: "{{ matrix_systemd_path }}/matrix-prometheus.service"
+    state: absent
+  when: "matrix_prometheus_service_stat.stat.exists|bool"
+
+- name: Ensure systemd reloaded after matrix-prometheus.service removal
+  service:
+    daemon_reload: yes
+  when: "matrix_prometheus_service_stat.stat.exists|bool"
+
+- name: Ensure matrix-prometheus Docker image doesn't exist
+  docker_image:
+    name: "{{ matrix_prometheus_docker_image }}"
+    state: absent
+  when: "not matrix_prometheus_enabled|bool"

From c8ab200cb1ded35d57b45514902ed807821e4b89 Mon Sep 17 00:00:00 2001
From: Slavi Pantaleev <slavi@devture.com>
Date: Sun, 31 Jan 2021 19:23:12 +0200
Subject: [PATCH 57/66] Break dependency between matrix-prometheus and
 (matrix-prometheus-node-exporter, matrix-synapse)

---
 group_vars/matrix_servers                     |  4 ++++
 roles/matrix-prometheus/defaults/main.yml     | 12 +++++++++--
 .../matrix-prometheus/tasks/setup_install.yml | 20 ++++++++++---------
 .../tasks/validate_config.yml                 |  4 ++--
 .../templates/prometheus.yml.j2               |  6 +++---
 5 files changed, 30 insertions(+), 16 deletions(-)

diff --git a/group_vars/matrix_servers b/group_vars/matrix_servers
index ad700597d..a8bddf6ea 100755
--- a/group_vars/matrix_servers
+++ b/group_vars/matrix_servers
@@ -1405,6 +1405,10 @@ matrix_prometheus_enabled: false
 # Prometheus' HTTP port to the local host.
 matrix_prometheus_container_http_host_bind_port: "{{ '' if matrix_nginx_proxy_enabled else '127.0.0.1:9090' }}"
 
+matrix_prometheus_scraper_synapse_enabled: "{{ matrix_synapse_enabled and matrix_synapse_metrics_enabled }}"
+matrix_prometheus_scraper_synapse_targets: ['matrix-synapse:{{ matrix_synapse_metrics_port }}']
+matrix_prometheus_scraper_synapse_rules_synapse_tag: "{{ matrix_synapse_docker_image_tag }}"
+
 matrix_prometheus_scraper_node_enabled: "{{ matrix_prometheus_node_exporter_enabled }}"
 
 ######################################################################
diff --git a/roles/matrix-prometheus/defaults/main.yml b/roles/matrix-prometheus/defaults/main.yml
index c07c38018..56018ba6d 100644
--- a/roles/matrix-prometheus/defaults/main.yml
+++ b/roles/matrix-prometheus/defaults/main.yml
@@ -6,8 +6,6 @@ matrix_prometheus_enabled: false
 matrix_prometheus_docker_image: "docker.io/prom/prometheus:v2.24.1"
 matrix_prometheus_docker_image_force_pull: "{{ matrix_prometheus_docker_image.endswith(':latest') }}"
 
-matrix_synapse_prometheus_rules_download_url: "https://raw.githubusercontent.com/matrix-org/synapse/{{ matrix_synapse_docker_image_tag }}/contrib/prometheus/synapse-v2.rules"
-
 matrix_prometheus_base_path: "{{ matrix_base_data_path }}/prometheus"
 matrix_prometheus_config_path: "{{ matrix_prometheus_base_path }}/config"
 matrix_prometheus_data_path: "{{ matrix_prometheus_base_path }}/data"
@@ -26,6 +24,16 @@ matrix_prometheus_systemd_wanted_services_list: []
 # Takes an "<ip>:<port>" or "<port>" value (e.g. "127.0.0.1:9090"), or empty string to not expose.
 matrix_prometheus_container_http_host_bind_port: ''
 
+# Tells whether the "synapse" scraper configuration is enabled.
+matrix_prometheus_scraper_synapse_enabled: false
+
+# Tells whether to download and load a Synapse rules file
+matrix_prometheus_scraper_synapse_rules_enabled: "{{ matrix_prometheus_scraper_synapse_enabled }}"
+matrix_prometheus_scraper_synapse_rules_synapse_tag: "master"
+matrix_prometheus_scraper_synapse_rules_download_url: "https://raw.githubusercontent.com/matrix-org/synapse/{{ matrix_prometheus_scraper_synapse_rules_synapse_tag }}/contrib/prometheus/synapse-v2.rules"
+
+matrix_prometheus_scraper_synapse_targets: []
+
 # Tells whether the "node" scraper configuration is enabled.
 # This configuration aims to scrape the current node (this server).
 matrix_prometheus_scraper_node_enabled: false
diff --git a/roles/matrix-prometheus/tasks/setup_install.yml b/roles/matrix-prometheus/tasks/setup_install.yml
index b69e349d8..8aee5178c 100644
--- a/roles/matrix-prometheus/tasks/setup_install.yml
+++ b/roles/matrix-prometheus/tasks/setup_install.yml
@@ -34,6 +34,17 @@
         matrix_prometheus_scraper_node_targets: ["{{ matrix_docker_network_info.network.IPAM.Config[0].Gateway }}:9100"]
   when: "matrix_prometheus_scraper_node_enabled|bool and matrix_prometheus_scraper_node_targets|length == 0"
 
+
+- name: Download synapse-v2.rules
+  get_url:
+    url: "{{ matrix_prometheus_scraper_synapse_rules_download_url }}"
+    dest: "{{ matrix_prometheus_config_path }}/synapse-v2.rules"
+    force: true
+    mode: 0440
+    owner: "{{ matrix_user_username }}"
+    group: "{{ matrix_user_groupname }}"
+  when: "matrix_prometheus_scraper_synapse_rules_enabled|bool"
+
 - name: Ensure prometheus.yml installed
   copy:
     content: "{{ matrix_prometheus_configuration|to_nice_yaml }}"
@@ -42,15 +53,6 @@
     owner: "{{ matrix_user_username }}"
     group: "{{ matrix_user_groupname }}"
 
-- name: Download synapse-v2.rules
-  get_url:
-    url: "{{ matrix_synapse_prometheus_rules_download_url }}"
-    dest: "{{ matrix_prometheus_config_path }}/synapse-v2.rules"
-    force: true
-    mode: 0440
-    owner: "{{ matrix_user_username }}"
-    group: "{{ matrix_user_groupname }}"
-
 - name: Ensure matrix-prometheus.service installed
   template:
     src: "{{ role_path }}/templates/systemd/matrix-prometheus.service.j2"
diff --git a/roles/matrix-prometheus/tasks/validate_config.yml b/roles/matrix-prometheus/tasks/validate_config.yml
index 713646ae0..9fcfe12b2 100644
--- a/roles/matrix-prometheus/tasks/validate_config.yml
+++ b/roles/matrix-prometheus/tasks/validate_config.yml
@@ -3,5 +3,5 @@
 - name: Fail if Synapse metrics or Prometheus Node Exporter not enabled
   fail:
     msg: >
-      You need to enable `matrix_synapse_metrics_enabled` and/or `matrix_prometheus_node_exporter_enabled` for Prometheus grab metrics.
-  when: "not matrix_synapse_metrics_enabled and not matrix_prometheus_node_exporter_enabled"
+      You need to enable `matrix_prometheus_scraper_synapse_enabled` and/or `matrix_prometheus_scraper_node_enabled` for Prometheus grab metrics.
+  when: "not matrix_prometheus_scraper_synapse_enabled and not matrix_prometheus_scraper_node_enabled"
diff --git a/roles/matrix-prometheus/templates/prometheus.yml.j2 b/roles/matrix-prometheus/templates/prometheus.yml.j2
index 4fe8394df..9502a08b6 100644
--- a/roles/matrix-prometheus/templates/prometheus.yml.j2
+++ b/roles/matrix-prometheus/templates/prometheus.yml.j2
@@ -6,7 +6,7 @@ global:
 
 # Load rules once and periodically evaluate them according to the global 'evaluation_interval'.
 rule_files:
-    {% if matrix_synapse_metrics_enabled %}
+    {% if matrix_prometheus_scraper_synapse_rules_enabled %}
     - 'synapse-v2.rules'
     {% endif %}
 
@@ -26,11 +26,11 @@ scrape_configs:
     static_configs:
       - targets: ['localhost:9090']
 
-  {% if matrix_synapse_metrics_enabled %}
+  {% if matrix_prometheus_scraper_synapse_enabled %}
   - job_name: 'synapse'
     metrics_path: '/_synapse/metrics'
     static_configs:
-    - targets: ['matrix-synapse:{{ matrix_synapse_metrics_port }}']
+    - targets: {{ matrix_prometheus_scraper_synapse_targets|to_json }}
   {% endif %}
 
   {% if matrix_prometheus_scraper_node_enabled %}

From eb9aac0ac9682104955a3498951fd02d102bb370 Mon Sep 17 00:00:00 2001
From: Slavi Pantaleev <slavi@devture.com>
Date: Sun, 31 Jan 2021 19:43:47 +0200
Subject: [PATCH 58/66] Minor docs updates

---
 docs/configuring-playbook-prometheus-grafana.md | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/docs/configuring-playbook-prometheus-grafana.md b/docs/configuring-playbook-prometheus-grafana.md
index 0c759692d..2010b1b59 100644
--- a/docs/configuring-playbook-prometheus-grafana.md
+++ b/docs/configuring-playbook-prometheus-grafana.md
@@ -8,17 +8,19 @@ You can enable this with the following settings in your configuration file (`inv
 matrix_prometheus_enabled: true
 
 matrix_synapse_metrics_enabled: true
+
 matrix_prometheus_node_exporter_enabled: true
 
 matrix_grafana_enabled: true
 
 matrix_grafana_anonymous_access: false
 
-matrix_grafana_default_admin_user: yourname
+# This has no relation to your Matrix user id. It can be any username you'd like.
+matrix_grafana_default_admin_user: some_username_chosen_by_you
 
 # Passwords containing special characters may be troublesome.
 # Changing the password subsequently won't work.
-matrix_grafana_default_admin_password: securelongpassword
+matrix_grafana_default_admin_password: some_strong_password_chosen_by_you
 ```
 
 The dashboards will by default be available on the `stats.<your-domain>` subdomain, proxied via Nginx.
@@ -28,7 +30,7 @@ The dashboards will by default be available on the `stats.<your-domain>` subdoma
 Name | Description
 -----|----------
 `matrix_prometheus_enabled`|Prometheus is a time series database. It holds all the data we're going to talk about.
-`matrix_synapse_metrics_enabled`|Enables metrics specific to Synapse
+`matrix_synapse_metrics_enabled`|Tell the Synapse server to expose metrics. This also cascades to other variables, which makes Prometheus collect said metrics
 `matrix_prometheus_node_exporter_enabled`|Node Exporter is an addon of sorts to Prometheus that collects generic system information such as CPU, memory, filesystem, and even system temperatures
 `matrix_grafana_enabled`|Grafana is the visual component. It shows the dashboards with the graphs that we're interested in
 `matrix_grafana_anonymous_access`|By default you need to log in to see graphs. If you want to publicly share your graphs (e.g. when asking for help in [`#synapse:matrix.org`](https://matrix.to/#/#synapse:matrix.org?via=matrix.org&via=privacytools.io&via=mozilla.org)) you'll want to enable this option.
@@ -36,7 +38,7 @@ Name | Description
 
 ## Security and privacy
 
-Metrics and resulting graphs can contain a lot if information. This includes system specs but also usage patterns. This applies especially to small personal/family scale homeservers. Someone might be able to figure out when you wake up and go to sleep by looking at the graphs over time. Think about this before enabling anonymous access. And you should really not forget to change your Grafana password.
+Metrics and resulting graphs can contain a lot of information. This includes system specs but also usage patterns. This applies especially to small personal/family scale homeservers. Someone might be able to figure out when you wake up and go to sleep by looking at the graphs over time. Think about this before enabling anonymous access. And you should really not forget to change your Grafana password.
 
 Most of our docker containers run with limited system access, but the `prometheus-node-exporter` has access to the host network stack and (readonly) root filesystem. This is required to report on them. If you don't like that, you can set `matrix_prometheus_node_exporter_enabled: false` (which is actually the default). You will still get Synapse metrics with this container disabled. Both of the dashboards will always be enabled, so you can still look at historical data after disabling either source.
 

From 2b47258c6cc382218cb659b3882bed247e304807 Mon Sep 17 00:00:00 2001
From: Slavi Pantaleev <slavi@devture.com>
Date: Fri, 12 Feb 2021 13:47:53 +0200
Subject: [PATCH 59/66] Do not auto-expose metrics on
 matrix.DOMAIN/_synapse/metrics

.. and other documentation improvements.
---
 ...configuring-playbook-prometheus-grafana.md | 23 +++++++++++++++----
 group_vars/matrix_servers                     |  8 ++++++-
 2 files changed, 26 insertions(+), 5 deletions(-)

diff --git a/docs/configuring-playbook-prometheus-grafana.md b/docs/configuring-playbook-prometheus-grafana.md
index 2010b1b59..006c99e9d 100644
--- a/docs/configuring-playbook-prometheus-grafana.md
+++ b/docs/configuring-playbook-prometheus-grafana.md
@@ -7,8 +7,6 @@ You can enable this with the following settings in your configuration file (`inv
 ```yaml
 matrix_prometheus_enabled: true
 
-matrix_synapse_metrics_enabled: true
-
 matrix_prometheus_node_exporter_enabled: true
 
 matrix_grafana_enabled: true
@@ -25,23 +23,40 @@ matrix_grafana_default_admin_password: some_strong_password_chosen_by_you
 
 The dashboards will by default be available on the `stats.<your-domain>` subdomain, proxied via Nginx.
 
+
 ## What does it do?
 
 Name | Description
 -----|----------
 `matrix_prometheus_enabled`|Prometheus is a time series database. It holds all the data we're going to talk about.
-`matrix_synapse_metrics_enabled`|Tell the Synapse server to expose metrics. This also cascades to other variables, which makes Prometheus collect said metrics
 `matrix_prometheus_node_exporter_enabled`|Node Exporter is an addon of sorts to Prometheus that collects generic system information such as CPU, memory, filesystem, and even system temperatures
-`matrix_grafana_enabled`|Grafana is the visual component. It shows the dashboards with the graphs that we're interested in
+`matrix_grafana_enabled`|Grafana is the visual component. It shows (on the `stats.<your-domain>` subdomain) the dashboards with the graphs that we're interested in
 `matrix_grafana_anonymous_access`|By default you need to log in to see graphs. If you want to publicly share your graphs (e.g. when asking for help in [`#synapse:matrix.org`](https://matrix.to/#/#synapse:matrix.org?via=matrix.org&via=privacytools.io&via=mozilla.org)) you'll want to enable this option.
 `matrix_grafana_default_admin_user`<br>`matrix_grafana_default_admin_password`|By default Grafana creates a user with `admin` as the username and password. If you feel this is insecure and you want to change it beforehand, you can do that here
 
+
 ## Security and privacy
 
 Metrics and resulting graphs can contain a lot of information. This includes system specs but also usage patterns. This applies especially to small personal/family scale homeservers. Someone might be able to figure out when you wake up and go to sleep by looking at the graphs over time. Think about this before enabling anonymous access. And you should really not forget to change your Grafana password.
 
 Most of our docker containers run with limited system access, but the `prometheus-node-exporter` has access to the host network stack and (readonly) root filesystem. This is required to report on them. If you don't like that, you can set `matrix_prometheus_node_exporter_enabled: false` (which is actually the default). You will still get Synapse metrics with this container disabled. Both of the dashboards will always be enabled, so you can still look at historical data after disabling either source.
 
+
+## Collecting metrics to an external Prometheus server
+
+If you wish, you could expose homeserver metrics without enabling (installing) Prometheus and Grafana via the playbook.
+
+To do this, you may be interested in the following variables:
+ `matrix_synapse_metrics_enabled` to `true`
+
+Name | Description
+-----|----------
+`matrix_synapse_metrics_enabled`|Set this to `true` to make Synapse expose metrics (locally, on the container network)
+`matrix_nginx_proxy_proxy_synapse_metrics`|Set this to `true` to make matrix-nginx-proxy expose the Synapse metrics at `https://matrix.DOMAIN/_synapse/metrics`
+`matrix_nginx_proxy_proxy_synapse_metrics_basic_auth_enabled`|Set this to `true` to password-protect (using HTTP Basic Auth) `https://matrix.DOMAIN/_synapse/metrics` (the username is always `prometheus`, the password is defined in `matrix_nginx_proxy_proxy_synapse_metrics_basic_auth_key`)
+`matrix_nginx_proxy_proxy_synapse_metrics_basic_auth_key`|Set this to a password to use for HTTP Basic Auth for protecting `https://matrix.DOMAIN/_synapse/metrics` (the username is always `prometheus` - it's not configurable)
+
+
 ## More inforation
 
 - [Understanding Synapse Performance Issues Through Grafana Graphs](https://github.com/matrix-org/synapse/wiki/Understanding-Synapse-Performance-Issues-Through-Grafana-Graphs) at the Synapse Github Wiki
diff --git a/group_vars/matrix_servers b/group_vars/matrix_servers
index a8bddf6ea..6d54f01d4 100755
--- a/group_vars/matrix_servers
+++ b/group_vars/matrix_servers
@@ -992,7 +992,10 @@ matrix_nginx_proxy_proxy_matrix_federation_api_addr_sans_container: "127.0.0.1:8
 
 matrix_nginx_proxy_container_federation_host_bind_port: "{{ matrix_federation_public_port }}"
 
-matrix_nginx_proxy_proxy_synapse_metrics: "{{ matrix_synapse_metrics_enabled }}"
+# This used to be hooked to `matrix_synapse_metrics_enabled`, but we don't do it anymore.
+# The fact that someone wishes to enable Synapse metrics does not necessarily mean they want to make them public.
+# A local Prometheus can consume them over the container network.
+matrix_nginx_proxy_proxy_synapse_metrics: false
 matrix_nginx_proxy_proxy_synapse_metrics_addr_with_container: "matrix-synapse:{{ matrix_synapse_metrics_port }}"
 matrix_nginx_proxy_proxy_synapse_metrics_addr_sans_container: "127.0.0.1:{{ matrix_synapse_metrics_port }}"
 
@@ -1300,6 +1303,9 @@ matrix_synapse_tls_private_key_path: ~
 
 matrix_synapse_federation_port_openid_resource_required: "{{ not matrix_synapse_federation_enabled and (matrix_dimension_enabled or matrix_ma1sd_enabled) }}"
 
+# If someone instals Prometheus via the playbook, they most likely wish to monitor Synapse.
+matrix_synapse_metrics_enabled: "{{ matrix_prometheus_enabled }}"
+
 matrix_synapse_email_enabled: "{{ matrix_mailer_enabled }}"
 matrix_synapse_email_smtp_host: "matrix-mailer"
 matrix_synapse_email_smtp_port: 8025

From 890e4ad1af0e89f14c9f87148919636d8628944e Mon Sep 17 00:00:00 2001
From: Slavi Pantaleev <slavi@devture.com>
Date: Fri, 12 Feb 2021 14:02:53 +0200
Subject: [PATCH 60/66] Announce Prometheus/Grafana

---
 CHANGELOG.md                                    |  9 +++++++++
 docs/configuring-playbook-prometheus-grafana.md | 12 ++++++------
 docs/configuring-playbook.md                    |  2 ++
 3 files changed, 17 insertions(+), 6 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1e23e58d2..a31fbc163 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,3 +1,12 @@
+# 2021-02-12
+
+## Monitoring/metrics support using Prometheus and Grafana
+
+Thanks to [@Peetz0r](https://github.com/Peetz0r), the playbook can now install a bunch of tools for monitoring your Matrix server: the [Prometheus](https://prometheus.io) time-series database server, the Prometheus [node-exporter](https://prometheus.io/docs/guides/node-exporter/) host metrics exporter, and the [Grafana](https://grafana.com/) web UI.
+
+To get get these installed, follow our [Enabling metrics and graphs (Prometheus, Grafana) for your Matrix server](docs/configuring-playbook-prometheus-grafana.md) docs page.
+
+
 # 2021-01-31
 
 ## Etherpad support
diff --git a/docs/configuring-playbook-prometheus-grafana.md b/docs/configuring-playbook-prometheus-grafana.md
index 006c99e9d..a10497cc6 100644
--- a/docs/configuring-playbook-prometheus-grafana.md
+++ b/docs/configuring-playbook-prometheus-grafana.md
@@ -14,6 +14,7 @@ matrix_grafana_enabled: true
 matrix_grafana_anonymous_access: false
 
 # This has no relation to your Matrix user id. It can be any username you'd like.
+# Changing the username subsequently won't work.
 matrix_grafana_default_admin_user: some_username_chosen_by_you
 
 # Passwords containing special characters may be troublesome.
@@ -21,16 +22,16 @@ matrix_grafana_default_admin_user: some_username_chosen_by_you
 matrix_grafana_default_admin_password: some_strong_password_chosen_by_you
 ```
 
-The dashboards will by default be available on the `stats.<your-domain>` subdomain, proxied via Nginx.
+By default, a [Grafana](https://grafana.com/) web user-interface will be available at `https://stats.<your-domain>`.
 
 
 ## What does it do?
 
 Name | Description
 -----|----------
-`matrix_prometheus_enabled`|Prometheus is a time series database. It holds all the data we're going to talk about.
-`matrix_prometheus_node_exporter_enabled`|Node Exporter is an addon of sorts to Prometheus that collects generic system information such as CPU, memory, filesystem, and even system temperatures
-`matrix_grafana_enabled`|Grafana is the visual component. It shows (on the `stats.<your-domain>` subdomain) the dashboards with the graphs that we're interested in
+`matrix_prometheus_enabled`|[Prometheus](https://prometheus.io) is a time series database. It holds all the data we're going to talk about.
+`matrix_prometheus_node_exporter_enabled`|[Node Exporter](https://prometheus.io/docs/guides/node-exporter/) is an addon of sorts to Prometheus that collects generic system information such as CPU, memory, filesystem, and even system temperatures
+`matrix_grafana_enabled`|[Grafana](https://grafana.com/) is the visual component. It shows (on the `stats.<your-domain>` subdomain) the dashboards with the graphs that we're interested in
 `matrix_grafana_anonymous_access`|By default you need to log in to see graphs. If you want to publicly share your graphs (e.g. when asking for help in [`#synapse:matrix.org`](https://matrix.to/#/#synapse:matrix.org?via=matrix.org&via=privacytools.io&via=mozilla.org)) you'll want to enable this option.
 `matrix_grafana_default_admin_user`<br>`matrix_grafana_default_admin_password`|By default Grafana creates a user with `admin` as the username and password. If you feel this is insecure and you want to change it beforehand, you can do that here
 
@@ -44,10 +45,9 @@ Most of our docker containers run with limited system access, but the `prometheu
 
 ## Collecting metrics to an external Prometheus server
 
-If you wish, you could expose homeserver metrics without enabling (installing) Prometheus and Grafana via the playbook.
+If you wish, you could expose homeserver metrics without enabling (installing) Prometheus and Grafana via the playbook. This may be useful for hooking Matrix services to an external Prometheus/Grafana installation.
 
 To do this, you may be interested in the following variables:
- `matrix_synapse_metrics_enabled` to `true`
 
 Name | Description
 -----|----------
diff --git a/docs/configuring-playbook.md b/docs/configuring-playbook.md
index 90dc01c5e..700602925 100644
--- a/docs/configuring-playbook.md
+++ b/docs/configuring-playbook.md
@@ -35,6 +35,8 @@ When you're done with all the configuration you'd like to do, continue with [Ins
 
 - [Setting up Dynamic DNS](configuring-playbook-dynamic-dns.md) (optional)
 
+- [Enabling metrics and graphs (Prometheus, Grafana) for your Matrix server](configuring-playbook-prometheus-grafana.md) (optional)
+
 ### Core service adjustments
 
 - [Configuring Synapse](configuring-playbook-synapse.md) (optional)

From 87ce12c3ebb788758cc10cf89d27f413c983a397 Mon Sep 17 00:00:00 2001
From: Slavi Pantaleev <slavi@devture.com>
Date: Fri, 12 Feb 2021 14:06:42 +0200
Subject: [PATCH 61/66] Add note about potential breaking change

---
 CHANGELOG.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index a31fbc163..540312684 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,11 +1,13 @@
 # 2021-02-12
 
-## Monitoring/metrics support using Prometheus and Grafana
+## (Potential Breaking Change) Monitoring/metrics support using Prometheus and Grafana
 
 Thanks to [@Peetz0r](https://github.com/Peetz0r), the playbook can now install a bunch of tools for monitoring your Matrix server: the [Prometheus](https://prometheus.io) time-series database server, the Prometheus [node-exporter](https://prometheus.io/docs/guides/node-exporter/) host metrics exporter, and the [Grafana](https://grafana.com/) web UI.
 
 To get get these installed, follow our [Enabling metrics and graphs (Prometheus, Grafana) for your Matrix server](docs/configuring-playbook-prometheus-grafana.md) docs page.
 
+This update comes with a **potential breaking change** for people who were already exposing Synapse metrics (for consumption via another Prometheus installation). From now on, `matrix_synapse_metrics_enabled: true` no longer exposes metrics publicly via matrix-nginx-proxy (at `https://matrix.DOMAIN/_synapse/metrics`). To do so, you'd need to explicitly set `matrix_nginx_proxy_proxy_synapse_metrics: true`.
+
 
 # 2021-01-31
 

From 66d5b0e5b90d85f7802083e521e3cf3a43041a65 Mon Sep 17 00:00:00 2001
From: Slavi Pantaleev <slavi@devture.com>
Date: Fri, 12 Feb 2021 15:41:15 +0200
Subject: [PATCH 62/66] Do not fail on unrelated validation tasks when
 Prometheus not enabled

These validation tasks should only run when Prometheus is enabled.
---
 .../tasks/validate_config.yml                              | 7 -------
 roles/matrix-prometheus/tasks/main.yml                     | 2 +-
 2 files changed, 1 insertion(+), 8 deletions(-)
 delete mode 100644 roles/matrix-prometheus-node-exporter/tasks/validate_config.yml

diff --git a/roles/matrix-prometheus-node-exporter/tasks/validate_config.yml b/roles/matrix-prometheus-node-exporter/tasks/validate_config.yml
deleted file mode 100644
index 713646ae0..000000000
--- a/roles/matrix-prometheus-node-exporter/tasks/validate_config.yml
+++ /dev/null
@@ -1,7 +0,0 @@
----
-
-- name: Fail if Synapse metrics or Prometheus Node Exporter not enabled
-  fail:
-    msg: >
-      You need to enable `matrix_synapse_metrics_enabled` and/or `matrix_prometheus_node_exporter_enabled` for Prometheus grab metrics.
-  when: "not matrix_synapse_metrics_enabled and not matrix_prometheus_node_exporter_enabled"
diff --git a/roles/matrix-prometheus/tasks/main.yml b/roles/matrix-prometheus/tasks/main.yml
index edb019881..20f18cc3b 100644
--- a/roles/matrix-prometheus/tasks/main.yml
+++ b/roles/matrix-prometheus/tasks/main.yml
@@ -3,7 +3,7 @@
     - always
 
 - import_tasks: "{{ role_path }}/tasks/validate_config.yml"
-  when: run_setup|bool
+  when: "run_setup|bool and matrix_prometheus_enabled|bool"
   tags:
     - setup-all
     - setup-prometheus

From 8434af10dec713e2ebcddccf64857d83e9fecdde Mon Sep 17 00:00:00 2001
From: Slavi Pantaleev <slavi@devture.com>
Date: Fri, 12 Feb 2021 15:45:19 +0200
Subject: [PATCH 63/66] Do not fail on unrelated validation tasks when Grafana
 not enabled

---
 roles/matrix-grafana/tasks/main.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/roles/matrix-grafana/tasks/main.yml b/roles/matrix-grafana/tasks/main.yml
index 122ec65e1..fb16c394b 100644
--- a/roles/matrix-grafana/tasks/main.yml
+++ b/roles/matrix-grafana/tasks/main.yml
@@ -3,7 +3,7 @@
     - always
 
 - import_tasks: "{{ role_path }}/tasks/validate_config.yml"
-  when: run_setup|bool
+  when: "run_setup|bool and matrix_grafana_enabled|bool"
   tags:
     - setup-all
     - setup-grafana

From 70a9a28ca32011dda7a5bc4c9b6fbbff5c033971 Mon Sep 17 00:00:00 2001
From: Slavi Pantaleev <slavi@devture.com>
Date: Fri, 12 Feb 2021 16:32:49 +0200
Subject: [PATCH 64/66] Mention Prometheus/Grafana on the README

---
 README.md | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 91f9314dc..55a69bea2 100644
--- a/README.md
+++ b/README.md
@@ -71,11 +71,11 @@ Using this playbook, you can get the following services configured on your serve
 
 - (optional) the [mx-puppet-instagram](https://github.com/Sorunome/mx-puppet-instagram) bridge for Instagram-DMs ([Instagram](https://www.instagram.com/)) - see [docs/configuring-playbook-bridge-mx-puppet-instagram.md](docs/configuring-playbook-bridge-mx-puppet-instagram.md) for setup documentation
 
-- (optional) the [mx-puppet-twitter](https://github.com/Sorunome/mx-puppet-twitter) bridge for Twitter-DMs ([Twitter](https://twitter.com/) - see [docs/configuring-playbook-bridge-mx-puppet-twitter.md](docs/configuring-playbook-bridge-mx-puppet-twitter.md) for setup documentation
+- (optional) the [mx-puppet-twitter](https://github.com/Sorunome/mx-puppet-twitter) bridge for Twitter-DMs ([Twitter](https://twitter.com/)) - see [docs/configuring-playbook-bridge-mx-puppet-twitter.md](docs/configuring-playbook-bridge-mx-puppet-twitter.md) for setup documentation
 
-- (optional) the [mx-puppet-discord](https://github.com/matrix-discord/mx-puppet-discord) bridge for [Discord](https://discordapp.com/)) - see [docs/configuring-playbook-bridge-mx-puppet-discord.md](docs/configuring-playbook-bridge-mx-puppet-discord.md) for setup documentation
+- (optional) the [mx-puppet-discord](https://github.com/matrix-discord/mx-puppet-discord) bridge for [Discord](https://discordapp.com/) - see [docs/configuring-playbook-bridge-mx-puppet-discord.md](docs/configuring-playbook-bridge-mx-puppet-discord.md) for setup documentation
 
-- (optional) the [mx-puppet-steam](https://github.com/icewind1991/mx-puppet-steam) bridge for [Steam](https://steamapp.com/)) - see [docs/configuring-playbook-bridge-mx-puppet-steam.md](docs/configuring-playbook-bridge-mx-puppet-steam.md) for setup documentation
+- (optional) the [mx-puppet-steam](https://github.com/icewind1991/mx-puppet-steam) bridge for [Steam](https://steamapp.com/) - see [docs/configuring-playbook-bridge-mx-puppet-steam.md](docs/configuring-playbook-bridge-mx-puppet-steam.md) for setup documentation
 
 - (optional) [Email2Matrix](https://github.com/devture/email2matrix) for relaying email messages to Matrix rooms - see [docs/configuring-playbook-email2matrix.md](docs/configuring-playbook-email2matrix.md) for setup documentation
 
@@ -91,6 +91,8 @@ Using this playbook, you can get the following services configured on your serve
 
 - (optional) [matrix-registration](https://github.com/ZerataX/matrix-registration), a simple python application to have a token based matrix registration - see [docs/configuring-playbook-matrix-registration.md](docs/configuring-playbook-matrix-registration.md) for setup documentation
 
+- (optional) the [Prometheus](https://prometheus.io) time-series database server, the Prometheus [node-exporter](https://prometheus.io/docs/guides/node-exporter/) host metrics exporter, and the [Grafana](https://grafana.com/) web UI - see [Enabling metrics and graphs (Prometheus, Grafana) for your Matrix server](docs/configuring-playbook-prometheus-grafana.md) for setup documentation
+
 Basically, this playbook aims to get you up-and-running with all the basic necessities around Matrix, without you having to do anything else.
 
 **Note**: the list above is exhaustive. It includes optional or even some advanced components that you will most likely not need.

From 7d39e5153a871a1db83d37f8f0772d2939c9b089 Mon Sep 17 00:00:00 2001
From: Slavi Pantaleev <slavi@devture.com>
Date: Sun, 14 Feb 2021 09:12:29 +0200
Subject: [PATCH 65/66] Upgrade Postgres minor versions

---
 roles/matrix-postgres/defaults/main.yml | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/roles/matrix-postgres/defaults/main.yml b/roles/matrix-postgres/defaults/main.yml
index d96a3ce89..09f3eb61b 100644
--- a/roles/matrix-postgres/defaults/main.yml
+++ b/roles/matrix-postgres/defaults/main.yml
@@ -17,11 +17,11 @@ matrix_postgres_architecture: amd64
 # > LOG:  startup process (PID 37) was terminated by signal 11: Segmentation fault
 matrix_postgres_docker_image_suffix: "{{ '-alpine' if matrix_postgres_architecture in ['amd64', 'arm64'] else '' }}"
 
-matrix_postgres_docker_image_v9: "docker.io/postgres:9.6.20{{ matrix_postgres_docker_image_suffix }}"
-matrix_postgres_docker_image_v10: "docker.io/postgres:10.15{{ matrix_postgres_docker_image_suffix }}"
-matrix_postgres_docker_image_v11: "docker.io/postgres:11.10{{ matrix_postgres_docker_image_suffix }}"
-matrix_postgres_docker_image_v12: "docker.io/postgres:12.5{{ matrix_postgres_docker_image_suffix }}"
-matrix_postgres_docker_image_v13: "docker.io/postgres:13.1{{ matrix_postgres_docker_image_suffix }}"
+matrix_postgres_docker_image_v9: "docker.io/postgres:9.6.21{{ matrix_postgres_docker_image_suffix }}"
+matrix_postgres_docker_image_v10: "docker.io/postgres:10.16{{ matrix_postgres_docker_image_suffix }}"
+matrix_postgres_docker_image_v11: "docker.io/postgres:11.11{{ matrix_postgres_docker_image_suffix }}"
+matrix_postgres_docker_image_v12: "docker.io/postgres:12.6{{ matrix_postgres_docker_image_suffix }}"
+matrix_postgres_docker_image_v13: "docker.io/postgres:13.2{{ matrix_postgres_docker_image_suffix }}"
 matrix_postgres_docker_image_latest: "{{ matrix_postgres_docker_image_v13 }}"
 
 # This variable is assigned at runtime. Overriding its value has no effect.

From a8e9f35708fa87746bb15d097d9a76a3f389d2a2 Mon Sep 17 00:00:00 2001
From: Slavi Pantaleev <slavi@devture.com>
Date: Sun, 14 Feb 2021 11:05:05 +0200
Subject: [PATCH 66/66] Touch up documentation a bit

---
 docs/configuring-playbook-nginx.md            |  4 ++--
 docs/configuring-playbook-ssl-certificates.md | 15 ++++++---------
 roles/matrix-nginx-proxy/defaults/main.yml    |  8 ++++++--
 3 files changed, 14 insertions(+), 13 deletions(-)

diff --git a/docs/configuring-playbook-nginx.md b/docs/configuring-playbook-nginx.md
index 91bed77cb..c8500b374 100644
--- a/docs/configuring-playbook-nginx.md
+++ b/docs/configuring-playbook-nginx.md
@@ -64,7 +64,7 @@ matrix_nginx_proxy_access_log_enabled: false
 
 This playbook also allows for additional configuration to be applied to the nginx server.
 
-If you want this playbook to obtain and renew certificates for other domains, then you can set the `matrix_ssl_additional_domains_to_obtain_certificates_for` variable. Make sure that you have set the DNS configuration for the domains you want to include to point at your server.
+If you want this playbook to obtain and renew certificates for other domains, then you can set the `matrix_ssl_additional_domains_to_obtain_certificates_for` variable (as mentioned in the [Obtaining SSL certificates for additional domains](configuring-playbook-ssl-certificates.md#obtaining-ssl-certificates-for-additional-domains) documentation as well). Make sure that you have set the DNS configuration for the domains you want to include to point at your server.
 
 ```yaml
 matrix_ssl_additional_domains_to_obtain_certificates_for:
@@ -72,7 +72,7 @@ matrix_ssl_additional_domains_to_obtain_certificates_for:
   - domain.two.example
 ```
 
-You can include additional nginx configuration by setting the `matrix_nginx_proxy_proxy_http_additional_server_configuration_blocks` variable. 
+You can include additional nginx configuration by setting the `matrix_nginx_proxy_proxy_http_additional_server_configuration_blocks` variable.
 
 ```yaml
 matrix_nginx_proxy_proxy_http_additional_server_configuration_blocks:
diff --git a/docs/configuring-playbook-ssl-certificates.md b/docs/configuring-playbook-ssl-certificates.md
index 7f05a5b25..1b5ea2349 100644
--- a/docs/configuring-playbook-ssl-certificates.md
+++ b/docs/configuring-playbook-ssl-certificates.md
@@ -74,15 +74,12 @@ If you are hosting other domains on the Matrix machine, you can make the playboo
 To do that, simply define your own custom configuration like this:
 
 ```yaml
-# Note: we need to explicitly list the aforementioned Matrix domains that you use (Matrix, Element, Dimension).
-# In this example, we retrieve an extra certificate - one for the base domain (in the `matrix_domain` variable).
+# In this example, we retrieve 2 extra certificates,
+# one for the base domain (in the `matrix_domain` variable) and one for a hardcoded domain.
 # Adding any other additional domains (hosted on the same machine) is possible.
-matrix_ssl_domains_to_obtain_certificates_for:
-  - '{{ matrix_server_fqn_matrix }}'
-  - '{{ matrix_server_fqn_element }}'
-  - '{{ matrix_server_fqn_dimension }}'
-  - '{{ matrix_server_fqn_jitsi }}'
+matrix_ssl_additional_domains_to_obtain_certificates_for:
   - '{{ matrix_domain }}'
+  - 'another.domain.example.com'
 ```
 
 After redefining `matrix_ssl_domains_to_obtain_certificates_for`, to actually obtain certificates you should:
@@ -91,9 +88,9 @@ After redefining `matrix_ssl_domains_to_obtain_certificates_for`, to actually ob
 
 - re-run the SSL part of the playbook and restart all services: `ansible-playbook -i inventory/hosts setup.yml --tags=setup-ssl,start`
 
-The certificate files would be available in `/matrix/ssl/config/live/<your-other-domain>/...`.
+The certificate files would be made available in `/matrix/ssl/config/live/<your-other-domain>/...`.
 
 For automated certificate renewal to work, each port `80` vhost for each domain you are obtaining certificates for needs to forward requests for `/.well-known/acme-challenge` to the certbot container we use for renewal.
 
 See how this is configured for the `matrix.` subdomain in `/matrix/nginx-proxy/conf.d/matrix-synapse.conf`
-Don't be alarmed if the above configuraiton file says port `8080`, instead of port `80`. It's due to port mapping due to our use of containers.
+Don't be alarmed if the above configuration file says port `8080`, instead of port `80`. It's due to port mapping due to our use of containers.
diff --git a/roles/matrix-nginx-proxy/defaults/main.yml b/roles/matrix-nginx-proxy/defaults/main.yml
index cb066277f..6d2c98560 100644
--- a/roles/matrix-nginx-proxy/defaults/main.yml
+++ b/roles/matrix-nginx-proxy/defaults/main.yml
@@ -290,8 +290,12 @@ matrix_ssl_retrieval_method: "lets-encrypt"
 
 matrix_ssl_architecture: "amd64"
 
-# The list of domains that this role will obtain certificates for.
-matrix_ssl_domains_to_obtain_certificates_for: []
+# The full list of domains that this role will obtain certificates for.
+# This variable is likely redefined outside of the role, to include the domains that are necessary (depending on the services that are enabled).
+# To add additional domain names, consider using `matrix_ssl_additional_domains_to_obtain_certificates_for` instead.
+matrix_ssl_domains_to_obtain_certificates_for: "{{ matrix_ssl_additional_domains_to_obtain_certificates_for }}"
+
+# A list of additional domain names to obtain certificates for.
 matrix_ssl_additional_domains_to_obtain_certificates_for: []
 
 # Controls whether to obtain production or staging certificates from Let's Encrypt.