From ec9f8e29319e6150eb6daa6417fa1afab7078b70 Mon Sep 17 00:00:00 2001
From: Julian Foad <julian@foad.me.uk>
Date: Tue, 21 Jun 2022 14:31:21 +0100
Subject: [PATCH 1/9] Add a role to install 'ntfy' push-notification server.

This commit adds a 'matrix-ntfy' role that runs Ntfy server in Docker with
simple configuration, and plumbing to add the role to the playbook.

TODO: documentation, self-check, database persistence.
---
 group_vars/matrix_servers                     |  19 ++++
 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-ntfy.conf.j2          | 100 ++++++++++++++++++
 roles/matrix-ntfy/README.md                   |  40 +++++++
 roles/matrix-ntfy/defaults/main.yml           |  16 +++
 roles/matrix-ntfy/tasks/init.yml              |   5 +
 roles/matrix-ntfy/tasks/main.yml              |  10 ++
 roles/matrix-ntfy/tasks/setup.yml             |  58 ++++++++++
 .../templates/systemd/matrix-ntfy.service.j2  |  37 +++++++
 setup.yml                                     |   1 +
 12 files changed, 309 insertions(+)
 create mode 100644 roles/matrix-nginx-proxy/templates/nginx/conf.d/matrix-ntfy.conf.j2
 create mode 100644 roles/matrix-ntfy/README.md
 create mode 100644 roles/matrix-ntfy/defaults/main.yml
 create mode 100644 roles/matrix-ntfy/tasks/init.yml
 create mode 100644 roles/matrix-ntfy/tasks/main.yml
 create mode 100644 roles/matrix-ntfy/tasks/setup.yml
 create mode 100644 roles/matrix-ntfy/templates/systemd/matrix-ntfy.service.j2

diff --git a/group_vars/matrix_servers b/group_vars/matrix_servers
index 8d3922764..1c30405dd 100755
--- a/group_vars/matrix_servers
+++ b/group_vars/matrix_servers
@@ -1552,6 +1552,7 @@ matrix_nginx_proxy_proxy_bot_go_neb_enabled: "{{ matrix_bot_go_neb_enabled }}"
 matrix_nginx_proxy_proxy_jitsi_enabled: "{{ matrix_jitsi_enabled }}"
 matrix_nginx_proxy_proxy_grafana_enabled: "{{ matrix_grafana_enabled }}"
 matrix_nginx_proxy_proxy_sygnal_enabled: "{{ matrix_sygnal_enabled }}"
+matrix_nginx_proxy_proxy_ntfy_enabled: "{{ matrix_ntfy_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"
@@ -1634,6 +1635,8 @@ matrix_nginx_proxy_systemd_wanted_services_list: |
     +
     (['matrix-sygnal.service'] if matrix_sygnal_enabled else [])
     +
+    (['matrix-ntfy.service'] if matrix_ntfy_enabled else [])
+    +
     (['matrix-jitsi.service'] if matrix_jitsi_enabled else [])
     +
     (['matrix-bot-go-neb.service'] if matrix_bot_go_neb_enabled else [])
@@ -1667,6 +1670,8 @@ matrix_ssl_domains_to_obtain_certificates_for: |
     +
     ([matrix_server_fqn_sygnal] if matrix_sygnal_enabled else [])
     +
+    ([matrix_server_fqn_ntfy] if matrix_ntfy_enabled else [])
+    +
     ([matrix_domain] if matrix_nginx_proxy_base_domain_serving_enabled else [])
     +
     matrix_ssl_additional_domains_to_obtain_certificates_for
@@ -1960,6 +1965,20 @@ matrix_sygnal_container_http_host_bind_port: "{{ '' if matrix_nginx_proxy_enable
 #
 ######################################################################
 
+######################################################################
+#
+# matrix-ntfy
+#
+######################################################################
+
+matrix_ntfy_enabled: false
+
+######################################################################
+#
+# /matrix-ntfy
+#
+######################################################################
+
 ######################################################################
 #
 # matrix-redis
diff --git a/roles/matrix-base/defaults/main.yml b/roles/matrix-base/defaults/main.yml
index 6b717f80f..9b6d45f84 100644
--- a/roles/matrix-base/defaults/main.yml
+++ b/roles/matrix-base/defaults/main.yml
@@ -59,6 +59,9 @@ matrix_server_fqn_grafana: "stats.{{ matrix_domain }}"
 # This is where you access the Sygnal push gateway.
 matrix_server_fqn_sygnal: "sygnal.{{ matrix_domain }}"
 
+# This is where you access the ntfy push notification service.
+matrix_server_fqn_ntfy: "ntfy.{{ 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 195b16fd9..f9b7a019f 100644
--- a/roles/matrix-nginx-proxy/defaults/main.yml
+++ b/roles/matrix-nginx-proxy/defaults/main.yml
@@ -192,6 +192,10 @@ matrix_nginx_proxy_proxy_grafana_hostname: "{{ matrix_server_fqn_grafana }}"
 matrix_nginx_proxy_proxy_sygnal_enabled: false
 matrix_nginx_proxy_proxy_sygnal_hostname: "{{ matrix_server_fqn_sygnal }}"
 
+# Controls whether proxying the ntfy domain should be done.
+matrix_nginx_proxy_proxy_ntfy_enabled: false
+matrix_nginx_proxy_proxy_ntfy_hostname: "{{ matrix_server_fqn_ntfy }}"
+
 # Controls whether proxying for (Prometheus) metrics (`/metrics/*`) for the various services should be done (on the matrix domain)
 # If the internal Prometheus server (`matrix-prometheus` role) is used, proxying is not necessary, since Prometheus can access each container directly.
 # This is only useful when an external Prometheus will be collecting metrics.
@@ -365,6 +369,9 @@ matrix_nginx_proxy_proxy_grafana_additional_server_configuration_blocks: []
 # A list of strings containing additional configuration blocks to add to Sygnal's server configuration (matrix-sygnal.conf).
 matrix_nginx_proxy_proxy_sygnal_additional_server_configuration_blocks: []
 
+# A list of strings containing additional configuration blocks to add to ntfy's server configuration (matrix-ntfy.conf).
+matrix_nginx_proxy_proxy_ntfy_additional_server_configuration_blocks: []
+
 # A list of strings containing additional configuration blocks to add to the base domain server configuration (matrix-base-domain.conf).
 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 0da9e52c7..70541fdc1 100644
--- a/roles/matrix-nginx-proxy/tasks/setup_nginx_proxy.yml
+++ b/roles/matrix-nginx-proxy/tasks/setup_nginx_proxy.yml
@@ -138,6 +138,13 @@
     mode: 0644
   when: matrix_nginx_proxy_proxy_sygnal_enabled|bool
 
+- name: Ensure Matrix nginx-proxy configuration for ntfy domain exists
+  template:
+    src: "{{ role_path }}/templates/nginx/conf.d/matrix-ntfy.conf.j2"
+    dest: "{{ matrix_nginx_proxy_confd_path }}/matrix-ntfy.conf"
+    mode: 0644
+  when: matrix_nginx_proxy_proxy_ntfy_enabled|bool
+
 - name: Ensure Matrix nginx-proxy configuration for Matrix domain exists
   template:
     src: "{{ role_path }}/templates/nginx/conf.d/matrix-domain.conf.j2"
@@ -288,6 +295,12 @@
     state: absent
   when: "not matrix_nginx_proxy_proxy_sygnal_enabled|bool"
 
+- name: Ensure Matrix nginx-proxy configuration for ntfy domain deleted
+  file:
+    path: "{{ matrix_nginx_proxy_confd_path }}/matrix-ntfy.conf"
+    state: absent
+  when: "not matrix_nginx_proxy_proxy_ntfy_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-ntfy.conf.j2 b/roles/matrix-nginx-proxy/templates/nginx/conf.d/matrix-ntfy.conf.j2
new file mode 100644
index 000000000..39818c1a7
--- /dev/null
+++ b/roles/matrix-nginx-proxy/templates/nginx/conf.d/matrix-ntfy.conf.j2
@@ -0,0 +1,100 @@
+#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;
+
+	{% if matrix_nginx_proxy_hsts_preload_enabled %}
+		add_header Strict-Transport-Security "max-age=31536000; includeSubDomains; preload" always;
+	{% else %}
+		add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
+	{% endif %}
+	add_header X-XSS-Protection "{{ matrix_nginx_proxy_xss_protection }}";
+	add_header X-Content-Type-Options nosniff;
+	add_header X-Frame-Options DENY;
+
+{% for configuration_block in matrix_nginx_proxy_proxy_ntfy_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-ntfy:80";
+			proxy_pass http://$backend;
+		{% else %}
+			{# Generic configuration for use outside of our container setup #}
+			proxy_pass http://127.0.0.1:80;
+		{% endif %}
+
+		proxy_set_header Host $host;
+		proxy_set_header X-Forwarded-For {{ matrix_nginx_proxy_x_forwarded_for }};
+		proxy_set_header X-Forwarded-Proto {{ matrix_nginx_proxy_x_forwarded_proto_value }};
+	}
+{% endmacro %}
+
+server {
+	listen {{ 8080 if matrix_nginx_proxy_enabled else 80 }};
+	listen [::]:{{ 8080 if matrix_nginx_proxy_enabled else 80 }};
+
+	server_name {{ matrix_nginx_proxy_proxy_ntfy_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_ntfy_hostname }};
+
+	server_tokens off;
+	root /dev/null;
+
+	ssl_certificate {{ matrix_ssl_config_dir_path }}/live/{{ matrix_nginx_proxy_proxy_ntfy_hostname }}/fullchain.pem;
+	ssl_certificate_key {{ matrix_ssl_config_dir_path }}/live/{{ matrix_nginx_proxy_proxy_ntfy_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 }};
+
+	{% if matrix_nginx_proxy_ocsp_stapling_enabled %}
+		ssl_stapling on;
+		ssl_stapling_verify on;
+		ssl_trusted_certificate {{ matrix_ssl_config_dir_path }}/live/{{ matrix_nginx_proxy_proxy_ntfy_hostname }}/chain.pem;
+	{% endif %}
+
+	{% if matrix_nginx_proxy_ssl_session_tickets_off %}
+		ssl_session_tickets off;
+	{% endif %}
+	ssl_session_cache {{ matrix_nginx_proxy_ssl_session_cache }};
+	ssl_session_timeout {{ matrix_nginx_proxy_ssl_session_timeout }};
+
+	{{ render_vhost_directives() }}
+}
+{% endif %}
diff --git a/roles/matrix-ntfy/README.md b/roles/matrix-ntfy/README.md
new file mode 100644
index 000000000..8b4f760a1
--- /dev/null
+++ b/roles/matrix-ntfy/README.md
@@ -0,0 +1,40 @@
+# A role to install the [ntfy](https://ntfy.sh) push-notification server.
+
+The ntfy server and clients implement self-hosted support push notifications
+from Matrix (and other) servers to Android (and other) clients, using the
+[UnifiedPush](https://unifiedpush.org) standard.
+
+This role installs ntfy server in Docker.  It is intended to support push
+notifications, via UnifiedPush, from the Matrix and Matrix-related services
+that are installed alongside it to any clients that support UnifiedPush.
+
+This role is not intended to support other features of the ntfy server and
+clients.
+
+
+# Using the ntfy role
+
+Configure the role by adding settings in your Ansible inventory.
+
+The only required setting is to enable ntfy:
+
+    matrix_ntfy_enabled: true
+
+The default domain for ntfy is `ntfy.<matrix_domain>`.  This can be changed
+with the `matrix_server_fqn_ntfy` variable:
+
+    matrix_server_fqn_ntfy: "my-ntfy.{{ matrix_domain }}"
+
+Other ntfy settings can be configured by adding extra arguments to the
+docker run command, e.g.:
+
+    matrix_ntfy_container_extra_arguments:
+      - '--env=NTFY_LOG_LEVEL=DEBUG'
+
+
+# TODO
+
+- Documentation.
+- Self-check.
+- Mount the ntfy database to disk so subscriptions persist across restarts.
+- Authentication?
diff --git a/roles/matrix-ntfy/defaults/main.yml b/roles/matrix-ntfy/defaults/main.yml
new file mode 100644
index 000000000..19e8af8f7
--- /dev/null
+++ b/roles/matrix-ntfy/defaults/main.yml
@@ -0,0 +1,16 @@
+---
+matrix_ntfy_enabled: true
+
+matrix_ntfy_base_path: "{{ matrix_base_data_path }}/ntfy"
+
+matrix_ntfy_version: v1.27.2
+matrix_ntfy_docker_image: "{{ matrix_container_global_registry_prefix }}binwiederhier/ntfy:{{ matrix_ntfy_version }}"
+matrix_ntfy_docker_image_force_pull: "{{ matrix_ntfy_docker_image.endswith(':latest') }}"
+
+# Controls whether the container exposes its HTTP port (tcp/8080 in the container).
+#
+# Takes an "<ip>:<port>" or "<port>" value (e.g. "127.0.0.1:8768"), or empty string to not expose.
+matrix_ntfy_container_http_host_bind_port: ''
+
+# A list of extra arguments to pass to the container
+matrix_ntfy_container_extra_arguments: []
diff --git a/roles/matrix-ntfy/tasks/init.yml b/roles/matrix-ntfy/tasks/init.yml
new file mode 100644
index 000000000..e2622655e
--- /dev/null
+++ b/roles/matrix-ntfy/tasks/init.yml
@@ -0,0 +1,5 @@
+---
+
+- set_fact:
+    matrix_systemd_services_list: "{{ matrix_systemd_services_list + ['matrix-ntfy.service'] }}"
+  when: matrix_ntfy_enabled|bool
diff --git a/roles/matrix-ntfy/tasks/main.yml b/roles/matrix-ntfy/tasks/main.yml
new file mode 100644
index 000000000..3f3975f58
--- /dev/null
+++ b/roles/matrix-ntfy/tasks/main.yml
@@ -0,0 +1,10 @@
+---
+
+- import_tasks: "{{ role_path }}/tasks/init.yml"
+  tags:
+    - always
+
+- import_tasks: "{{ role_path }}/tasks/setup.yml"
+  tags:
+    - setup-all
+    - setup-ntfy
diff --git a/roles/matrix-ntfy/tasks/setup.yml b/roles/matrix-ntfy/tasks/setup.yml
new file mode 100644
index 000000000..c06195ec9
--- /dev/null
+++ b/roles/matrix-ntfy/tasks/setup.yml
@@ -0,0 +1,58 @@
+---
+#
+# Tasks related to setting up matrix-ntfy
+#
+
+- name: Ensure matrix-ntfy image is pulled
+  docker_image:
+    name: "{{ matrix_ntfy_docker_image }}"
+    source: "{{ 'pull' if ansible_version.major > 2 or ansible_version.minor > 7 else omit }}"
+    force_source: "{{ matrix_ntfy_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_ntfy_docker_image_force_pull }}"
+  when: "matrix_ntfy_enabled|bool"
+  register: result
+  retries: "{{ matrix_container_retries_count }}"
+  delay: "{{ matrix_container_retries_delay }}"
+  until: result is not failed
+
+- name: Ensure matrix-ntfy.service installed
+  template:
+    src: "{{ role_path }}/templates/systemd/matrix-ntfy.service.j2"
+    dest: "{{ matrix_systemd_path }}/matrix-ntfy.service"
+    mode: 0644
+  register: matrix_ntfy_systemd_service_result
+  when: matrix_ntfy_enabled|bool
+
+- name: Ensure systemd reloaded after matrix-ntfy.service installation
+  service:
+    daemon_reload: true
+  when: "matrix_ntfy_enabled|bool and matrix_ntfy_systemd_service_result.changed"
+
+#
+# Tasks related to getting rid of matrix-ntfy (if it was previously enabled)
+#
+
+- name: Check existence of matrix-ntfy service
+  stat:
+    path: "{{ matrix_systemd_path }}/matrix-ntfy.service"
+  register: matrix_ntfy_service_stat
+
+- name: Ensure matrix-ntfy is stopped
+  service:
+    name: matrix-ntfy
+    state: stopped
+    enabled: false
+    daemon_reload: true
+  register: stopping_result
+  when: "not matrix_ntfy_enabled|bool and matrix_ntfy_service_stat.stat.exists"
+
+- name: Ensure matrix-ntfy.service doesn't exist
+  file:
+    path: "{{ matrix_systemd_path }}/matrix-ntfy.service"
+    state: absent
+  when: "not matrix_ntfy_enabled|bool and matrix_ntfy_service_stat.stat.exists"
+
+- name: Ensure systemd reloaded after matrix-ntfy.service removal
+  service:
+    daemon_reload: true
+  when: "not matrix_ntfy_enabled|bool and matrix_ntfy_service_stat.stat.exists"
diff --git a/roles/matrix-ntfy/templates/systemd/matrix-ntfy.service.j2 b/roles/matrix-ntfy/templates/systemd/matrix-ntfy.service.j2
new file mode 100644
index 000000000..85d032778
--- /dev/null
+++ b/roles/matrix-ntfy/templates/systemd/matrix-ntfy.service.j2
@@ -0,0 +1,37 @@
+#jinja2: lstrip_blocks: "True"
+[Unit]
+Description=matrix-ntfy
+After=docker.service
+Requires=docker.service
+DefaultDependencies=no
+
+[Service]
+Type=simple
+Environment="HOME={{ matrix_systemd_unit_home_path }}"
+ExecStartPre=-{{ matrix_host_command_sh }} -c '{{ matrix_host_command_docker }} kill matrix-ntfy 2>/dev/null || true'
+ExecStartPre=-{{ matrix_host_command_sh }} -c '{{ matrix_host_command_docker }} rm matrix-ntfy 2>/dev/null || true'
+
+ExecStart={{ matrix_host_command_docker }} run --rm --name matrix-ntfy \
+			--log-driver=none \
+			--user={{ matrix_user_uid }}:{{ matrix_user_gid }} \
+			--cap-drop=ALL \
+			--read-only \
+			{% for arg in matrix_ntfy_container_extra_arguments %}
+			{{ arg }} \
+			{% endfor %}
+			--network={{ matrix_docker_network }} \
+			{% if matrix_ntfy_container_http_host_bind_port %}
+			-p {{ matrix_ntfy_container_http_host_bind_port }}:80 \
+			{% endif %}
+			--env NTFY_BASE_URL=https://{{ matrix_server_fqn_ntfy }} \
+			{{ matrix_ntfy_docker_image }} \
+			serve --behind-proxy
+
+ExecStop=-{{ matrix_host_command_sh }} -c '{{ matrix_host_command_docker }} kill matrix-ntfy 2>/dev/null || true'
+ExecStop=-{{ matrix_host_command_sh }} -c '{{ matrix_host_command_docker }} rm matrix-ntfy 2>/dev/null || true'
+Restart=always
+RestartSec=30
+SyslogIdentifier=matrix-ntfy
+
+[Install]
+WantedBy=multi-user.target
diff --git a/setup.yml b/setup.yml
index 27aac7a72..c99da4d16 100755
--- a/setup.yml
+++ b/setup.yml
@@ -60,6 +60,7 @@
     - matrix-etherpad
     - matrix-email2matrix
     - matrix-sygnal
+    - matrix-ntfy
     - matrix-nginx-proxy
     - matrix-coturn
     - matrix-aux

From 2a516a16fbfd71339609df855ac48dc44cfd8af3 Mon Sep 17 00:00:00 2001
From: Julian Foad <julian@foad.me.uk>
Date: Fri, 24 Jun 2022 22:20:51 +0100
Subject: [PATCH 2/9] matrix-ntfy: enable WebSocket proxying

---
 .../templates/nginx/conf.d/matrix-ntfy.conf.j2                  | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/roles/matrix-nginx-proxy/templates/nginx/conf.d/matrix-ntfy.conf.j2 b/roles/matrix-nginx-proxy/templates/nginx/conf.d/matrix-ntfy.conf.j2
index 39818c1a7..e095e7213 100644
--- a/roles/matrix-nginx-proxy/templates/nginx/conf.d/matrix-ntfy.conf.j2
+++ b/roles/matrix-nginx-proxy/templates/nginx/conf.d/matrix-ntfy.conf.j2
@@ -27,6 +27,8 @@
 			{# Generic configuration for use outside of our container setup #}
 			proxy_pass http://127.0.0.1:80;
 		{% endif %}
+		proxy_set_header Upgrade $http_upgrade;
+		proxy_set_header Connection "upgrade";
 
 		proxy_set_header Host $host;
 		proxy_set_header X-Forwarded-For {{ matrix_nginx_proxy_x_forwarded_for }};

From 85b12b74a75d2e4360948843325238edac16cffd Mon Sep 17 00:00:00 2001
From: Julian Foad <julian@foad.me.uk>
Date: Mon, 27 Jun 2022 22:20:02 +0100
Subject: [PATCH 3/9] matrix-ntfy: documentation

---
 docs/configuring-dns.md                       |  3 +
 docs/configuring-playbook-ntfy.md             | 62 +++++++++++++++++++
 docs/configuring-playbook-ssl-certificates.md |  1 +
 docs/configuring-playbook.md                  |  2 +
 docs/container-images.md                      |  2 +
 roles/matrix-ntfy/README.md                   | 35 -----------
 roles/matrix-ntfy/defaults/main.yml           |  2 +-
 7 files changed, 71 insertions(+), 36 deletions(-)
 create mode 100644 docs/configuring-playbook-ntfy.md

diff --git a/docs/configuring-dns.md b/docs/configuring-dns.md
index 666f8a63d..aec3c2539 100644
--- a/docs/configuring-dns.md
+++ b/docs/configuring-dns.md
@@ -36,6 +36,7 @@ If you are using Cloudflare DNS, make sure to disable the proxy and set all reco
 | CNAME | `stats`                      | -        | -      | -    | `matrix.<your-domain>` |
 | CNAME | `goneb`                      | -        | -      | -    | `matrix.<your-domain>` |
 | CNAME | `sygnal`                     | -        | -      | -    | `matrix.<your-domain>` |
+| CNAME | `ntfy`                       | -        | -      | -    | `matrix.<your-domain>` |
 | CNAME | `hydrogen`                   | -        | -      | -    | `matrix.<your-domain>` |
 | CNAME | `cinny`                      | -        | -      | -    | `matrix.<your-domain>` |
 | CNAME | `buscarron`                  | -        | -      | -    | `matrix.<your-domain>` |
@@ -57,6 +58,8 @@ The `goneb.<your-domain>` subdomain may be necessary, because this playbook coul
 
 The `sygnal.<your-domain>` subdomain may be necessary, because this playbook could install the [Sygnal](https://github.com/matrix-org/sygnal) push gateway. The installation of Sygnal is disabled by default, it is not a core required component. To learn how to install it, see our [configuring Sygnal guide](configuring-playbook-sygnal.md). If you do not wish to set up Sygnal (you probably don't, unless you're also developing/building your own Matrix apps), feel free to skip the `sygnal.<your-domain>` DNS record.
 
+The `ntfy.<your-domain>` subdomain may be necessary, because this playbook could install the [ntfy](https://ntfy.sh/) UnifiedPush-compatible push notifications server. The installation of ntfy is disabled by default, it is not a core required component. To learn how to install it, see our [configuring ntfy guide](configuring-playbook-ntfy.md). If you do not wish to set up ntfy, feel free to skip the `ntfy.<your-domain>` DNS record.
+
 The `hydrogen.<your-domain>` subdomain may be necessary, because this playbook could install the [Hydrogen](https://github.com/vector-im/hydrogen-web) web client. The installation of Hydrogen is disabled by default, it is not a core required component. To learn how to install it, see our [configuring Hydrogen guide](configuring-playbook-client-hydrogen.md). If you do not wish to set up Hydrogen, feel free to skip the `hydrogen.<your-domain>` DNS record.
 
 The `cinny.<your-domain>` subdomain may be necessary, because this playbook could install the [Cinny](https://github.com/ajbura/cinny) web client. The installation of cinny is disabled by default, it is not a core required component. To learn how to install it, see our [configuring cinny guide](configuring-playbook-client-cinny.md). If you do not wish to set up cinny, feel free to skip the `cinny.<your-domain>` DNS record.
diff --git a/docs/configuring-playbook-ntfy.md b/docs/configuring-playbook-ntfy.md
new file mode 100644
index 000000000..03684b9c8
--- /dev/null
+++ b/docs/configuring-playbook-ntfy.md
@@ -0,0 +1,62 @@
+# Setting up ntfy (optional)
+
+The playbook can install and configure the [ntfy](https://ntfy.sh/) push notifications server for you.
+
+Using the [UnifiedPush](https://unifiedpush.org) standard, ntfy enables self-hosted (Google-free) push notifications from Matrix (and other) servers to UnifiedPush-compatible matrix compatible client apps running on Android and other devices.
+
+This role is intended to support UnifiedPush notifications for use with the Matrix and Matrix-related services that this playbook installs. This role is not intended to support all of ntfy's other features.
+
+**Note**: In contrast to push notifications using Google's FCM or Apple's APNs, the use of UnifiedPush allows each end-user to choose the push notification server that they prefer.  As a consequence, deploying this ntfy server does not by itself ensure any particular user or device or client app will use it.
+
+
+## Adjusting the playbook configuration
+
+Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file (adapt to your needs):
+
+```yaml
+# Enabling it is the only required setting
+matrix_ntfy_enabled: true
+
+# Some other options
+matrix_server_fqn_ntfy: "ntfy.{{ matrix_domain }}"
+matrix_ntfy_container_extra_arguments: [ '--env=NTFY_LOG_LEVEL=DEBUG' ]
+```
+
+For a more complete list of variables that you could override, see `roles/matrix-ntfy/defaults/main.yml`.
+
+For a complete list of ntfy config options that you could put in `matrix_ntfy_container_extra_arguments`, see the [ntfy config documentation](https://ntfy.sh/docs/config/#config-options).
+
+
+## Installing
+
+Don't forget to add `ntfy.<your-domain>` to DNS as described in [Configuring DNS](configuring-dns.md) before running the playbook.
+
+After configuring the playbook, run the [installation](installing.md) command again:
+
+```
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
+```
+
+
+## Usage
+
+To make use of your ntfy installation, on Android for example, first you need to install the `ntfy` client app and configure it to point to your ntfy server, such as `https://ntfy.DOMAIN`. That is the only thing you need to do in the ntfy client app. (It has many other features, but for our purposes you can ignore them.)
+
+Then any UnifiedPush-enabled matrix app on that device will discover it and tell your matrix server to use your ntfy server to send push notifications to that matrix app.
+
+If the matrix app asks, "Choose a distributor: FCM Fallback or ntfy", then choose "ntfy".
+
+If the matrix app doesn't seem to pick it up, try restarting it and try the Troubleshooting section below.
+
+
+## Troubleshooting
+
+First check that the matrix client app you are using supports UnifiedPush. There may well be different variants of the app.
+
+Set the ntfy server's log level to 'DEBUG', as shown in the example settings above, and watch the server's logs with `sudo journalctl -fu matrix-ntfy`.
+
+To check if UnifiedPush is correctly configured on the client device, look at "Settings -> Notifications -> Notification Targets" in Element-Android or SchildiChat, or "Settings -> Notifications -> Devices" in FluffyChat. There should be one entry for each matrix client app that has enabled push notifications, and when that client is using UnifiedPush you should see a URL that begins with your ntfy server's URL. In Element-Android or SchildiChat, two URLs are shown: "push\_key" and "Url", and both should begin with your ntfy server's URL.
+
+If it is not working, useful tools are "Settings -> Notifications -> Re-register push distributor" and "Settings -> Notifications -> Troubleshoot Notifications" in SchildiChat (possibly also Element-Android). In particular the "Endpoint/FCM" step of that troubleshooter should display your ntfy server's URL that it has discovered from the ntfy client app.
+
+The simple [UnifiedPush troubleshooting](https://unifiedpush.org/users/troubleshooting/) app [UP-Example](https://f-droid.org/en/packages/org.unifiedpush.example/) can be used to manually test UnifiedPush registration and operation on an Android device.
diff --git a/docs/configuring-playbook-ssl-certificates.md b/docs/configuring-playbook-ssl-certificates.md
index eae584e72..30a8f0b87 100644
--- a/docs/configuring-playbook-ssl-certificates.md
+++ b/docs/configuring-playbook-ssl-certificates.md
@@ -74,6 +74,7 @@ By default, it obtains certificates for:
 - possibly for `jitsi.<your-domain>`, if you have explicitly [set up Jitsi](configuring-playbook-jitsi.md).
 - possibly for `stats.<your-domain>`, if you have explicitly [set up Grafana](configuring-playbook-prometheus-grafana.md).
 - possibly for `sygnal.<your-domain>`, if you have explicitly [set up Sygnal](configuring-playbook-sygnal.md).
+- possibly for `ntfy.<your-domain>`, if you have explicitly [set up ntfy](configuring-playbook-ntfy.md).
 - possibly for your base domain (`<your-domain>`), if you have explicitly configured [Serving the base domain](configuring-playbook-base-domain-serving.md)
 
 If you are hosting other domains on the Matrix machine, you can make the playbook obtain and renew certificates for those other domains too.
diff --git a/docs/configuring-playbook.md b/docs/configuring-playbook.md
index 3bfb01bdc..f71a23f5c 100644
--- a/docs/configuring-playbook.md
+++ b/docs/configuring-playbook.md
@@ -168,3 +168,5 @@ When you're done with all the configuration you'd like to do, continue with [Ins
 ### Other specialized services
 
 - [Setting up the Sygnal push gateway](configuring-playbook-sygnal.md) (optional)
+
+- [Setting up the ntfy push notifications server](configuring-playbook-ntfy.md) (optional)
diff --git a/docs/container-images.md b/docs/container-images.md
index bf5885e06..25005d5ac 100644
--- a/docs/container-images.md
+++ b/docs/container-images.md
@@ -109,3 +109,5 @@ These services are not part of our default installation, but can be enabled by [
 - [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)
 
 - [matrixdotorg/sygnal](https://hub.docker.com/r/matrixdotorg/sygnal/) - [Sygnal](https://github.com/matrix-org/sygnal) is a reference Push Gateway for Matrix
+
+- [binwiederhier/ntfy](https://hub.docker.com/r/binwiederhier/ntfy/) - [ntfy](https://ntfy.sh/) is a self-hosted, UnifiedPush-compatible push notifications server
diff --git a/roles/matrix-ntfy/README.md b/roles/matrix-ntfy/README.md
index 8b4f760a1..2a5301f7f 100644
--- a/roles/matrix-ntfy/README.md
+++ b/roles/matrix-ntfy/README.md
@@ -1,40 +1,5 @@
-# A role to install the [ntfy](https://ntfy.sh) push-notification server.
-
-The ntfy server and clients implement self-hosted support push notifications
-from Matrix (and other) servers to Android (and other) clients, using the
-[UnifiedPush](https://unifiedpush.org) standard.
-
-This role installs ntfy server in Docker.  It is intended to support push
-notifications, via UnifiedPush, from the Matrix and Matrix-related services
-that are installed alongside it to any clients that support UnifiedPush.
-
-This role is not intended to support other features of the ntfy server and
-clients.
-
-
-# Using the ntfy role
-
-Configure the role by adding settings in your Ansible inventory.
-
-The only required setting is to enable ntfy:
-
-    matrix_ntfy_enabled: true
-
-The default domain for ntfy is `ntfy.<matrix_domain>`.  This can be changed
-with the `matrix_server_fqn_ntfy` variable:
-
-    matrix_server_fqn_ntfy: "my-ntfy.{{ matrix_domain }}"
-
-Other ntfy settings can be configured by adding extra arguments to the
-docker run command, e.g.:
-
-    matrix_ntfy_container_extra_arguments:
-      - '--env=NTFY_LOG_LEVEL=DEBUG'
-
-
 # TODO
 
-- Documentation.
 - Self-check.
 - Mount the ntfy database to disk so subscriptions persist across restarts.
 - Authentication?
diff --git a/roles/matrix-ntfy/defaults/main.yml b/roles/matrix-ntfy/defaults/main.yml
index 19e8af8f7..2df796742 100644
--- a/roles/matrix-ntfy/defaults/main.yml
+++ b/roles/matrix-ntfy/defaults/main.yml
@@ -12,5 +12,5 @@ matrix_ntfy_docker_image_force_pull: "{{ matrix_ntfy_docker_image.endswith(':lat
 # Takes an "<ip>:<port>" or "<port>" value (e.g. "127.0.0.1:8768"), or empty string to not expose.
 matrix_ntfy_container_http_host_bind_port: ''
 
-# A list of extra arguments to pass to the container
+# A list of extra arguments to pass to the container (`docker run` command)
 matrix_ntfy_container_extra_arguments: []

From 763586e878fbf78b07ea3ef0fa31199bab0e4235 Mon Sep 17 00:00:00 2001
From: Julian Foad <julian@foad.me.uk>
Date: Wed, 29 Jun 2022 10:48:40 +0100
Subject: [PATCH 4/9] matrix-ntfy: add self-check

---
 roles/matrix-ntfy/README.md            |  1 -
 roles/matrix-ntfy/defaults/main.yml    |  3 +++
 roles/matrix-ntfy/tasks/main.yml       |  7 +++++++
 roles/matrix-ntfy/tasks/self_check.yml | 25 +++++++++++++++++++++++++
 4 files changed, 35 insertions(+), 1 deletion(-)
 create mode 100644 roles/matrix-ntfy/tasks/self_check.yml

diff --git a/roles/matrix-ntfy/README.md b/roles/matrix-ntfy/README.md
index 2a5301f7f..41f83f662 100644
--- a/roles/matrix-ntfy/README.md
+++ b/roles/matrix-ntfy/README.md
@@ -1,5 +1,4 @@
 # TODO
 
-- Self-check.
 - Mount the ntfy database to disk so subscriptions persist across restarts.
 - Authentication?
diff --git a/roles/matrix-ntfy/defaults/main.yml b/roles/matrix-ntfy/defaults/main.yml
index 2df796742..916591e7b 100644
--- a/roles/matrix-ntfy/defaults/main.yml
+++ b/roles/matrix-ntfy/defaults/main.yml
@@ -14,3 +14,6 @@ matrix_ntfy_container_http_host_bind_port: ''
 
 # A list of extra arguments to pass to the container (`docker run` command)
 matrix_ntfy_container_extra_arguments: []
+
+# Controls whether the self-check feature should validate SSL certificates.
+matrix_ntfy_self_check_validate_certificates: true
diff --git a/roles/matrix-ntfy/tasks/main.yml b/roles/matrix-ntfy/tasks/main.yml
index 3f3975f58..b2abac665 100644
--- a/roles/matrix-ntfy/tasks/main.yml
+++ b/roles/matrix-ntfy/tasks/main.yml
@@ -8,3 +8,10 @@
   tags:
     - setup-all
     - setup-ntfy
+
+- import_tasks: "{{ role_path }}/tasks/self_check.yml"
+  delegate_to: 127.0.0.1
+  become: false
+  when: "run_self_check|bool and matrix_ntfy_enabled|bool"
+  tags:
+    - self-check
diff --git a/roles/matrix-ntfy/tasks/self_check.yml b/roles/matrix-ntfy/tasks/self_check.yml
new file mode 100644
index 000000000..324a2d952
--- /dev/null
+++ b/roles/matrix-ntfy/tasks/self_check.yml
@@ -0,0 +1,25 @@
+---
+
+# Query an arbitrary ntfy topic using ntfy's UnifiedPush topic name syntax.
+# Expect an empty response (because we query 'since=1s').
+
+- set_fact:
+    matrix_ntfy_url_endpoint_public: "https://{{ matrix_server_fqn_ntfy }}/upSELFCHECK123/json?poll=1&since=1s"
+
+- name: Check ntfy
+  uri:
+    url: "{{ matrix_ntfy_url_endpoint_public }}"
+    follow_redirects: none
+    validate_certs: "{{ matrix_ntfy_self_check_validate_certificates }}"
+  register: matrix_ntfy_self_check_result
+  check_mode: false
+  ignore_errors: true
+
+- name: Fail if ntfy not working
+  fail:
+    msg: "Failed checking ntfy is up at `{{ matrix_server_fqn_ntfy }}` (checked endpoint: `{{ matrix_ntfy_url_endpoint_public }}`). Is ntfy running? Is port 443 open in your firewall? Full error: {{ matrix_ntfy_self_check_result }}"
+  when: "matrix_ntfy_self_check_result.failed"
+
+- name: Report working ntfy
+  debug:
+    msg: "ntfy at `{{ matrix_server_fqn_ntfy }}` is working (checked endpoint: `{{ matrix_ntfy_url_endpoint_public }}`)"

From 3866fff5a830d75575ae959dd28a2374ffad31b1 Mon Sep 17 00:00:00 2001
From: Julian Foad <julian@foad.me.uk>
Date: Sat, 2 Jul 2022 17:35:53 +0100
Subject: [PATCH 5/9] matrix-ntfy: persist cache on disk

---
 roles/matrix-ntfy/README.md                           |  1 -
 roles/matrix-ntfy/defaults/main.yml                   |  1 +
 roles/matrix-ntfy/tasks/setup.yml                     | 11 +++++++++++
 .../templates/systemd/matrix-ntfy.service.j2          |  2 ++
 4 files changed, 14 insertions(+), 1 deletion(-)

diff --git a/roles/matrix-ntfy/README.md b/roles/matrix-ntfy/README.md
index 41f83f662..26da0a42b 100644
--- a/roles/matrix-ntfy/README.md
+++ b/roles/matrix-ntfy/README.md
@@ -1,4 +1,3 @@
 # TODO
 
-- Mount the ntfy database to disk so subscriptions persist across restarts.
 - Authentication?
diff --git a/roles/matrix-ntfy/defaults/main.yml b/roles/matrix-ntfy/defaults/main.yml
index 916591e7b..5dff2ec3b 100644
--- a/roles/matrix-ntfy/defaults/main.yml
+++ b/roles/matrix-ntfy/defaults/main.yml
@@ -2,6 +2,7 @@
 matrix_ntfy_enabled: true
 
 matrix_ntfy_base_path: "{{ matrix_base_data_path }}/ntfy"
+matrix_ntfy_data_path: "{{ matrix_ntfy_base_path }}/data"
 
 matrix_ntfy_version: v1.27.2
 matrix_ntfy_docker_image: "{{ matrix_container_global_registry_prefix }}binwiederhier/ntfy:{{ matrix_ntfy_version }}"
diff --git a/roles/matrix-ntfy/tasks/setup.yml b/roles/matrix-ntfy/tasks/setup.yml
index c06195ec9..9a2c15596 100644
--- a/roles/matrix-ntfy/tasks/setup.yml
+++ b/roles/matrix-ntfy/tasks/setup.yml
@@ -15,6 +15,17 @@
   delay: "{{ matrix_container_retries_delay }}"
   until: result is not failed
 
+- name: Ensure matrix-ntfy paths exists
+  file:
+    path: "{{ item }}"
+    state: directory
+    mode: 0750
+    owner: "{{ matrix_user_username }}"
+    group: "{{ matrix_user_groupname }}"
+  with_items:
+    - "{{ matrix_ntfy_base_path }}"
+    - "{{ matrix_ntfy_data_path }}"
+
 - name: Ensure matrix-ntfy.service installed
   template:
     src: "{{ role_path }}/templates/systemd/matrix-ntfy.service.j2"
diff --git a/roles/matrix-ntfy/templates/systemd/matrix-ntfy.service.j2 b/roles/matrix-ntfy/templates/systemd/matrix-ntfy.service.j2
index 85d032778..78963a082 100644
--- a/roles/matrix-ntfy/templates/systemd/matrix-ntfy.service.j2
+++ b/roles/matrix-ntfy/templates/systemd/matrix-ntfy.service.j2
@@ -23,6 +23,8 @@ ExecStart={{ matrix_host_command_docker }} run --rm --name matrix-ntfy \
 			{% if matrix_ntfy_container_http_host_bind_port %}
 			-p {{ matrix_ntfy_container_http_host_bind_port }}:80 \
 			{% endif %}
+			--mount type=bind,src={{ matrix_ntfy_data_path }},dst=/data \
+			--env NTFY_CACHE_FILE=/data/cache.db \
 			--env NTFY_BASE_URL=https://{{ matrix_server_fqn_ntfy }} \
 			{{ matrix_ntfy_docker_image }} \
 			serve --behind-proxy

From 408e2e9b4ee97802422a67405f28a3ac14c271cd Mon Sep 17 00:00:00 2001
From: Julian Foad <julian@foad.me.uk>
Date: Sat, 2 Jul 2022 17:37:45 +0100
Subject: [PATCH 6/9] matrix-ntfy: remove almost-empty README.md

---
 roles/matrix-ntfy/README.md | 3 ---
 1 file changed, 3 deletions(-)
 delete mode 100644 roles/matrix-ntfy/README.md

diff --git a/roles/matrix-ntfy/README.md b/roles/matrix-ntfy/README.md
deleted file mode 100644
index 26da0a42b..000000000
--- a/roles/matrix-ntfy/README.md
+++ /dev/null
@@ -1,3 +0,0 @@
-# TODO
-
-- Authentication?

From efe1f21f05c483aa785a707eea454ecaed4c8daf Mon Sep 17 00:00:00 2001
From: Julian Foad <julian@foad.me.uk>
Date: Mon, 4 Jul 2022 14:51:55 +0100
Subject: [PATCH 7/9] matrix-ntfy: fix and separate out uninstall tasks

---
 roles/matrix-ntfy/tasks/main.yml              |  9 ++++-
 .../tasks/{setup.yml => setup_install.yml}    | 36 +------------------
 roles/matrix-ntfy/tasks/setup_uninstall.yml   | 36 +++++++++++++++++++
 3 files changed, 45 insertions(+), 36 deletions(-)
 rename roles/matrix-ntfy/tasks/{setup.yml => setup_install.yml} (53%)
 create mode 100644 roles/matrix-ntfy/tasks/setup_uninstall.yml

diff --git a/roles/matrix-ntfy/tasks/main.yml b/roles/matrix-ntfy/tasks/main.yml
index b2abac665..5dd0d172a 100644
--- a/roles/matrix-ntfy/tasks/main.yml
+++ b/roles/matrix-ntfy/tasks/main.yml
@@ -4,7 +4,14 @@
   tags:
     - always
 
-- import_tasks: "{{ role_path }}/tasks/setup.yml"
+- import_tasks: "{{ role_path }}/tasks/setup_install.yml"
+  when: "run_setup|bool and matrix_ntfy_enabled|bool"
+  tags:
+    - setup-all
+    - setup-ntfy
+
+- import_tasks: "{{ role_path }}/tasks/setup_uninstall.yml"
+  when: "run_setup|bool and not matrix_ntfy_enabled|bool"
   tags:
     - setup-all
     - setup-ntfy
diff --git a/roles/matrix-ntfy/tasks/setup.yml b/roles/matrix-ntfy/tasks/setup_install.yml
similarity index 53%
rename from roles/matrix-ntfy/tasks/setup.yml
rename to roles/matrix-ntfy/tasks/setup_install.yml
index 9a2c15596..b674d3208 100644
--- a/roles/matrix-ntfy/tasks/setup.yml
+++ b/roles/matrix-ntfy/tasks/setup_install.yml
@@ -1,7 +1,4 @@
 ---
-#
-# Tasks related to setting up matrix-ntfy
-#
 
 - name: Ensure matrix-ntfy image is pulled
   docker_image:
@@ -9,7 +6,6 @@
     source: "{{ 'pull' if ansible_version.major > 2 or ansible_version.minor > 7 else omit }}"
     force_source: "{{ matrix_ntfy_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_ntfy_docker_image_force_pull }}"
-  when: "matrix_ntfy_enabled|bool"
   register: result
   retries: "{{ matrix_container_retries_count }}"
   delay: "{{ matrix_container_retries_delay }}"
@@ -32,38 +28,8 @@
     dest: "{{ matrix_systemd_path }}/matrix-ntfy.service"
     mode: 0644
   register: matrix_ntfy_systemd_service_result
-  when: matrix_ntfy_enabled|bool
 
 - name: Ensure systemd reloaded after matrix-ntfy.service installation
   service:
     daemon_reload: true
-  when: "matrix_ntfy_enabled|bool and matrix_ntfy_systemd_service_result.changed"
-
-#
-# Tasks related to getting rid of matrix-ntfy (if it was previously enabled)
-#
-
-- name: Check existence of matrix-ntfy service
-  stat:
-    path: "{{ matrix_systemd_path }}/matrix-ntfy.service"
-  register: matrix_ntfy_service_stat
-
-- name: Ensure matrix-ntfy is stopped
-  service:
-    name: matrix-ntfy
-    state: stopped
-    enabled: false
-    daemon_reload: true
-  register: stopping_result
-  when: "not matrix_ntfy_enabled|bool and matrix_ntfy_service_stat.stat.exists"
-
-- name: Ensure matrix-ntfy.service doesn't exist
-  file:
-    path: "{{ matrix_systemd_path }}/matrix-ntfy.service"
-    state: absent
-  when: "not matrix_ntfy_enabled|bool and matrix_ntfy_service_stat.stat.exists"
-
-- name: Ensure systemd reloaded after matrix-ntfy.service removal
-  service:
-    daemon_reload: true
-  when: "not matrix_ntfy_enabled|bool and matrix_ntfy_service_stat.stat.exists"
+  when: "matrix_ntfy_systemd_service_result.changed"
diff --git a/roles/matrix-ntfy/tasks/setup_uninstall.yml b/roles/matrix-ntfy/tasks/setup_uninstall.yml
new file mode 100644
index 000000000..e63caa9a7
--- /dev/null
+++ b/roles/matrix-ntfy/tasks/setup_uninstall.yml
@@ -0,0 +1,36 @@
+---
+
+- name: Check existence of matrix-ntfy service
+  stat:
+    path: "{{ matrix_systemd_path }}/matrix-ntfy.service"
+  register: matrix_ntfy_service_stat
+
+- name: Ensure matrix-ntfy is stopped
+  service:
+    name: matrix-ntfy
+    state: stopped
+    enabled: false
+    daemon_reload: true
+  register: stopping_result
+  when: "matrix_ntfy_service_stat.stat.exists"
+
+- name: Ensure matrix-ntfy.service doesn't exist
+  file:
+    path: "{{ matrix_systemd_path }}/matrix-ntfy.service"
+    state: absent
+  when: "matrix_ntfy_service_stat.stat.exists"
+
+- name: Ensure systemd reloaded after matrix-ntfy.service removal
+  service:
+    daemon_reload: true
+  when: "matrix_ntfy_service_stat.stat.exists"
+
+- name: Ensure matrix-ntfy path doesn't exist
+  file:
+    path: "{{ matrix_ntfy_base_path }}"
+    state: absent
+
+- name: Ensure ntfy Docker image doesn't exist
+  docker_image:
+    name: "{{ matrix_ntfy_docker_image }}"
+    state: absent

From e119512c5928ded244ef629fbf8ef37f7694c4b3 Mon Sep 17 00:00:00 2001
From: Julian Foad <julian@foad.me.uk>
Date: Mon, 4 Jul 2022 15:27:23 +0100
Subject: [PATCH 8/9] matrix-ntfy: add variable 'matrix_ntfy_base_url'

---
 roles/matrix-ntfy/defaults/main.yml                        | 3 +++
 roles/matrix-ntfy/tasks/self_check.yml                     | 2 +-
 roles/matrix-ntfy/templates/systemd/matrix-ntfy.service.j2 | 2 +-
 3 files changed, 5 insertions(+), 2 deletions(-)

diff --git a/roles/matrix-ntfy/defaults/main.yml b/roles/matrix-ntfy/defaults/main.yml
index 5dff2ec3b..6c540beba 100644
--- a/roles/matrix-ntfy/defaults/main.yml
+++ b/roles/matrix-ntfy/defaults/main.yml
@@ -8,6 +8,9 @@ matrix_ntfy_version: v1.27.2
 matrix_ntfy_docker_image: "{{ matrix_container_global_registry_prefix }}binwiederhier/ntfy:{{ matrix_ntfy_version }}"
 matrix_ntfy_docker_image_force_pull: "{{ matrix_ntfy_docker_image.endswith(':latest') }}"
 
+# Public facing base URL of the ntfy service
+matrix_ntfy_base_url: "https://{{ matrix_server_fqn_ntfy }}"
+
 # Controls whether the container exposes its HTTP port (tcp/8080 in the container).
 #
 # Takes an "<ip>:<port>" or "<port>" value (e.g. "127.0.0.1:8768"), or empty string to not expose.
diff --git a/roles/matrix-ntfy/tasks/self_check.yml b/roles/matrix-ntfy/tasks/self_check.yml
index 324a2d952..e91047341 100644
--- a/roles/matrix-ntfy/tasks/self_check.yml
+++ b/roles/matrix-ntfy/tasks/self_check.yml
@@ -4,7 +4,7 @@
 # Expect an empty response (because we query 'since=1s').
 
 - set_fact:
-    matrix_ntfy_url_endpoint_public: "https://{{ matrix_server_fqn_ntfy }}/upSELFCHECK123/json?poll=1&since=1s"
+    matrix_ntfy_url_endpoint_public: "{{ matrix_ntfy_base_url }}/upSELFCHECK123/json?poll=1&since=1s"
 
 - name: Check ntfy
   uri:
diff --git a/roles/matrix-ntfy/templates/systemd/matrix-ntfy.service.j2 b/roles/matrix-ntfy/templates/systemd/matrix-ntfy.service.j2
index 78963a082..5bb28470a 100644
--- a/roles/matrix-ntfy/templates/systemd/matrix-ntfy.service.j2
+++ b/roles/matrix-ntfy/templates/systemd/matrix-ntfy.service.j2
@@ -25,7 +25,7 @@ ExecStart={{ matrix_host_command_docker }} run --rm --name matrix-ntfy \
 			{% endif %}
 			--mount type=bind,src={{ matrix_ntfy_data_path }},dst=/data \
 			--env NTFY_CACHE_FILE=/data/cache.db \
-			--env NTFY_BASE_URL=https://{{ matrix_server_fqn_ntfy }} \
+			--env NTFY_BASE_URL={{ matrix_ntfy_base_url }} \
 			{{ matrix_ntfy_docker_image }} \
 			serve --behind-proxy
 

From e60d20dc6a6ca11efb58ba8993e307e0912a164e Mon Sep 17 00:00:00 2001
From: Julian Foad <julian@foad.me.uk>
Date: Mon, 4 Jul 2022 21:30:29 +0100
Subject: [PATCH 9/9] matrix-ntfy: store settings in a config file

---
 docs/configuring-playbook-ntfy.md             |  5 ++--
 roles/matrix-ntfy/defaults/main.yml           | 23 +++++++++++++++++++
 roles/matrix-ntfy/tasks/setup_install.yml     |  9 ++++++++
 .../matrix-ntfy/templates/ntfy/server.yml.j2  |  3 +++
 .../templates/systemd/matrix-ntfy.service.j2  |  5 ++--
 5 files changed, 40 insertions(+), 5 deletions(-)
 create mode 100644 roles/matrix-ntfy/templates/ntfy/server.yml.j2

diff --git a/docs/configuring-playbook-ntfy.md b/docs/configuring-playbook-ntfy.md
index 03684b9c8..56c859f30 100644
--- a/docs/configuring-playbook-ntfy.md
+++ b/docs/configuring-playbook-ntfy.md
@@ -19,12 +19,13 @@ matrix_ntfy_enabled: true
 
 # Some other options
 matrix_server_fqn_ntfy: "ntfy.{{ matrix_domain }}"
-matrix_ntfy_container_extra_arguments: [ '--env=NTFY_LOG_LEVEL=DEBUG' ]
+matrix_ntfy_configuration_extension_yaml: |
+  log_level: DEBUG
 ```
 
 For a more complete list of variables that you could override, see `roles/matrix-ntfy/defaults/main.yml`.
 
-For a complete list of ntfy config options that you could put in `matrix_ntfy_container_extra_arguments`, see the [ntfy config documentation](https://ntfy.sh/docs/config/#config-options).
+For a complete list of ntfy config options that you could put in `matrix_ntfy_configuration_extension_yaml`, see the [ntfy config documentation](https://ntfy.sh/docs/config/#config-options).
 
 
 ## Installing
diff --git a/roles/matrix-ntfy/defaults/main.yml b/roles/matrix-ntfy/defaults/main.yml
index 6c540beba..4f0e2e55d 100644
--- a/roles/matrix-ntfy/defaults/main.yml
+++ b/roles/matrix-ntfy/defaults/main.yml
@@ -2,6 +2,7 @@
 matrix_ntfy_enabled: true
 
 matrix_ntfy_base_path: "{{ matrix_base_data_path }}/ntfy"
+matrix_ntfy_config_dir_path: "{{ matrix_ntfy_base_path }}/config"
 matrix_ntfy_data_path: "{{ matrix_ntfy_base_path }}/data"
 
 matrix_ntfy_version: v1.27.2
@@ -21,3 +22,25 @@ matrix_ntfy_container_extra_arguments: []
 
 # Controls whether the self-check feature should validate SSL certificates.
 matrix_ntfy_self_check_validate_certificates: true
+
+# Default ntfy 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_ntfy_configuration_extension_yaml`)
+# or completely replace this variable with your own template.
+matrix_ntfy_configuration_yaml: "{{ lookup('template', 'templates/ntfy/server.yml.j2') }}"
+
+matrix_ntfy_configuration_extension_yaml: |
+  # Your custom YAML configuration for ntfy goes here.
+  # This configuration extends the default starting configuration (`matrix_ntfy_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_ntfy_configuration_yaml`.
+
+matrix_ntfy_configuration_extension: "{{ matrix_ntfy_configuration_extension_yaml|from_yaml if matrix_ntfy_configuration_extension_yaml|from_yaml is mapping else {} }}"
+
+# Holds the final ntfy configuration (a combination of the default and its extension).
+# You most likely don't need to touch this variable. Instead, see `matrix_ntfy_configuration_yaml`.
+matrix_ntfy_configuration: "{{ matrix_ntfy_configuration_yaml|from_yaml|combine(matrix_ntfy_configuration_extension, recursive=True) }}"
diff --git a/roles/matrix-ntfy/tasks/setup_install.yml b/roles/matrix-ntfy/tasks/setup_install.yml
index b674d3208..461d31763 100644
--- a/roles/matrix-ntfy/tasks/setup_install.yml
+++ b/roles/matrix-ntfy/tasks/setup_install.yml
@@ -20,8 +20,17 @@
     group: "{{ matrix_user_groupname }}"
   with_items:
     - "{{ matrix_ntfy_base_path }}"
+    - "{{ matrix_ntfy_config_dir_path }}"
     - "{{ matrix_ntfy_data_path }}"
 
+- name: Ensure matrix-ntfy config installed
+  copy:
+    content: "{{ matrix_ntfy_configuration|to_nice_yaml(indent=2, width=999999) }}"
+    dest: "{{ matrix_ntfy_config_dir_path }}/server.yml"
+    mode: 0644
+    owner: "{{ matrix_user_username }}"
+    group: "{{ matrix_user_groupname }}"
+
 - name: Ensure matrix-ntfy.service installed
   template:
     src: "{{ role_path }}/templates/systemd/matrix-ntfy.service.j2"
diff --git a/roles/matrix-ntfy/templates/ntfy/server.yml.j2 b/roles/matrix-ntfy/templates/ntfy/server.yml.j2
new file mode 100644
index 000000000..4cafcd62a
--- /dev/null
+++ b/roles/matrix-ntfy/templates/ntfy/server.yml.j2
@@ -0,0 +1,3 @@
+base_url: {{ matrix_ntfy_base_url }}
+behind_proxy: true
+cache_file: /data/cache.db
diff --git a/roles/matrix-ntfy/templates/systemd/matrix-ntfy.service.j2 b/roles/matrix-ntfy/templates/systemd/matrix-ntfy.service.j2
index 5bb28470a..da292e5ce 100644
--- a/roles/matrix-ntfy/templates/systemd/matrix-ntfy.service.j2
+++ b/roles/matrix-ntfy/templates/systemd/matrix-ntfy.service.j2
@@ -23,11 +23,10 @@ ExecStart={{ matrix_host_command_docker }} run --rm --name matrix-ntfy \
 			{% if matrix_ntfy_container_http_host_bind_port %}
 			-p {{ matrix_ntfy_container_http_host_bind_port }}:80 \
 			{% endif %}
+			--mount type=bind,src={{ matrix_ntfy_config_dir_path }},dst=/etc/ntfy,ro \
 			--mount type=bind,src={{ matrix_ntfy_data_path }},dst=/data \
-			--env NTFY_CACHE_FILE=/data/cache.db \
-			--env NTFY_BASE_URL={{ matrix_ntfy_base_url }} \
 			{{ matrix_ntfy_docker_image }} \
-			serve --behind-proxy
+			serve
 
 ExecStop=-{{ matrix_host_command_sh }} -c '{{ matrix_host_command_docker }} kill matrix-ntfy 2>/dev/null || true'
 ExecStop=-{{ matrix_host_command_sh }} -c '{{ matrix_host_command_docker }} rm matrix-ntfy 2>/dev/null || true'