From 83c40fce1583787ad5ab2eba996d40eab7f0c87a Mon Sep 17 00:00:00 2001 From: Aine Date: Fri, 4 Nov 2022 11:36:10 +0200 Subject: [PATCH 1/5] standalone etherpad --- docs/configuring-dns.md | 3 + docs/configuring-playbook-etherpad.md | 31 ++--- group_vars/matrix_servers | 5 + roles/custom/matrix-base/defaults/main.yml | 3 + .../custom/matrix-etherpad/defaults/main.yml | 1 + roles/custom/matrix-etherpad/tasks/init.yml | 2 +- .../matrix-etherpad/tasks/validate_config.yml | 6 - .../matrix-nginx-proxy/defaults/main.yml | 7 ++ .../tasks/setup_nginx_proxy.yml | 7 ++ .../nginx/conf.d/matrix-etherpad.conf.j2 | 108 ++++++++++++++++++ 10 files changed, 152 insertions(+), 21 deletions(-) create mode 100644 roles/custom/matrix-nginx-proxy/templates/nginx/conf.d/matrix-etherpad.conf.j2 diff --git a/docs/configuring-dns.md b/docs/configuring-dns.md index 3803ba8f..d7ccf17e 100644 --- a/docs/configuring-dns.md +++ b/docs/configuring-dns.md @@ -39,6 +39,7 @@ When you're done configuring DNS, proceed to [Configuring the playbook](configur | [Go-NEB](configuring-playbook-bot-go-neb.md) bot | CNAME | `goneb` | - | - | - | `matrix.` | | [Sygnal](configuring-playbook-sygnal.md) push notification gateway | CNAME | `sygnal` | - | - | - | `matrix.` | | [ntfy](configuring-playbook-ntfy.md) push notifications server | CNAME | `ntfy` | - | - | - | `matrix.` | +| [Etherpad](configuring-playbook-etherpad.md) collaborative text editor | CNAME | `etherpad` | - | - | - | `matrix.` | | [Hydrogen](configuring-playbook-client-hydrogen.md) web client | CNAME | `hydrogen` | - | - | - | `matrix.` | | [Cinny](configuring-playbook-client-cinny.md) web client | CNAME | `cinny` | - | - | - | `matrix.` | | [Buscarron](configuring-playbook-bot-buscarron.md) helpdesk bot | CNAME | `buscarron` | - | - | - | `matrix.` | @@ -68,6 +69,8 @@ The `sygnal.` subdomain may be necessary, because this playbook cou The `ntfy.` 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.` DNS record. +The `etherpad.` subdomain may be necessary, because this playbook could install the [Etherpad](https://etherpad.org/) a highly customizable open source online editor providing collaborative editing in really real-time. The installation of etherpad is disabled by default, it is not a core required component. To learn how to install it, see our [configuring etherpad guide](configuring-playbook-etherpad.md). If you do not wish to set up etherpad, feel free to skip the `etherpad.` DNS record. + The `hydrogen.` 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.` DNS record. The `cinny.` 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.` DNS record. diff --git a/docs/configuring-playbook-etherpad.md b/docs/configuring-playbook-etherpad.md index 4c38bb3c..3214d861 100644 --- a/docs/configuring-playbook-etherpad.md +++ b/docs/configuring-playbook-etherpad.md @@ -1,12 +1,14 @@ # 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) +[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) or used as standalone web app 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) +The `etherpad.` DNS record must be created. See [Configuring your DNS server](configuring-dns.md) on how to set up DNS record correctly. + +You may enable and configure the **Dimension integrations manager** as described in [the playbook documentation](configuring-playbook-dimension.md) to integrate etherpad with Dimension. ## Installing @@ -16,16 +18,7 @@ For the self-hosted Etherpad instance to be available to your users, you must fi 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./etherpad/p/$roomId_$padName?showChat=false` - -### Etherpad Admin access (optional) +## Etherpad Admin access (optional) Etherpad comes with a admin web-UI which is disabled by default. You can enable it by setting a username and password in your configuration file (`inventory/host_vars/matrix./vars.yml`): @@ -36,11 +29,21 @@ matrix_etherpad_admin_password: some-password The admin web-UI should then be available on: `https://dimension./etherpad/admin` -### Managing / Deleting old pads +## Managing / Deleting old pads If you want to manage and remove old unused pads from Etherpad, you will first need to able Admin access as described above. -Then from the plugin manager page (`https://dimension./etherpad/admin/plugins`), install the `adminpads2` plugin. Once installed, you should have a "Manage pads" section in the Admin web-UI. +Then from the plugin manager page (`https://etherpad./admin/plugins` or `https://dimension./etherpad/admin/plugins`), install the `adminpads2` plugin. Once installed, you should have a "Manage pads" section in the Admin web-UI. + +## Set Dimension default to the self-hosted Etherpad (optional) + +If you decided to install [Dimension integration manager](configuring-playbook-dimension.md) alongside with 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./etherpad/p/$roomId_$padName?showChat=false` ## Known issues diff --git a/group_vars/matrix_servers b/group_vars/matrix_servers index 2e3a217c..26e5b35f 100755 --- a/group_vars/matrix_servers +++ b/group_vars/matrix_servers @@ -1486,6 +1486,8 @@ matrix_etherpad_enabled: false matrix_etherpad_container_http_host_bind_port: "{{ '' if matrix_nginx_proxy_enabled else '127.0.0.1:9001' }}" +matrix_etherpad_base_url: "{{ 'https://'+ matrix_server_fqn_dimension + matrix_etherpad_public_endpoint if matrix_dimension_enabled else 'https://' + matrix_server_fqn_etherpad + '/' }}" + matrix_etherpad_systemd_required_services_list: | {{ ['docker.service'] @@ -1710,6 +1712,7 @@ matrix_nginx_proxy_proxy_hydrogen_enabled: "{{ matrix_client_hydrogen_enabled }} matrix_nginx_proxy_proxy_cinny_enabled: "{{ matrix_client_cinny_enabled }}" matrix_nginx_proxy_proxy_buscarron_enabled: "{{ matrix_bot_buscarron_enabled }}" matrix_nginx_proxy_proxy_dimension_enabled: "{{ matrix_dimension_enabled }}" +matrix_nginx_proxy_proxy_etherpad_enabled: "{{ matrix_etherpad_enabled }}" 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 }}" @@ -1837,6 +1840,8 @@ matrix_ssl_domains_to_obtain_certificates_for: | + ([matrix_server_fqn_dimension] if matrix_dimension_enabled else []) + + ([matrix_server_fqn_etherpad] if matrix_etherpad_enabled else []) + + ([matrix_server_fqn_bot_go_neb] if matrix_bot_go_neb_enabled else []) + ([matrix_server_fqn_jitsi] if matrix_jitsi_enabled else []) diff --git a/roles/custom/matrix-base/defaults/main.yml b/roles/custom/matrix-base/defaults/main.yml index 52049ed5..02e26a93 100644 --- a/roles/custom/matrix-base/defaults/main.yml +++ b/roles/custom/matrix-base/defaults/main.yml @@ -62,6 +62,9 @@ matrix_server_fqn_buscarron: "buscarron.{{ matrix_domain }}" # This is where you access the Dimension. matrix_server_fqn_dimension: "dimension.{{ matrix_domain }}" +# This is where you access the etherpad (if enabled via matrix_etherpad_enabled; disabled by default). +matrix_server_fqn_etherpad: "etherpad.{{ matrix_domain }}" + # For use with Go-NEB! (github callback url for example) matrix_server_fqn_bot_go_neb: "goneb.{{ matrix_domain }}" diff --git a/roles/custom/matrix-etherpad/defaults/main.yml b/roles/custom/matrix-etherpad/defaults/main.yml index 8281f27f..35d24090 100644 --- a/roles/custom/matrix-etherpad/defaults/main.yml +++ b/roles/custom/matrix-etherpad/defaults/main.yml @@ -28,6 +28,7 @@ matrix_etherpad_container_http_host_bind_port: '' # A list of extra arguments to pass to the container matrix_etherpad_container_extra_arguments: [] +# Used for dimension only matrix_etherpad_public_endpoint: '/etherpad' # By default, the Etherpad app can be accessed within the Dimension domain diff --git a/roles/custom/matrix-etherpad/tasks/init.yml b/roles/custom/matrix-etherpad/tasks/init.yml index cfd127bd..c787548c 100644 --- a/roles/custom/matrix-etherpad/tasks/init.yml +++ b/roles/custom/matrix-etherpad/tasks/init.yml @@ -4,7 +4,7 @@ matrix_systemd_services_list: "{{ matrix_systemd_services_list + ['matrix-etherpad.service'] }}" when: matrix_etherpad_enabled | bool -- when: matrix_etherpad_enabled | bool +- when: matrix_etherpad_enabled | bool and matrix_dimension_enabled | default(False) | bool tags: - always block: diff --git a/roles/custom/matrix-etherpad/tasks/validate_config.yml b/roles/custom/matrix-etherpad/tasks/validate_config.yml index bf78c36f..9832b0b8 100644 --- a/roles/custom/matrix-etherpad/tasks/validate_config.yml +++ b/roles/custom/matrix-etherpad/tasks/validate_config.yml @@ -1,11 +1,5 @@ --- -- name: Fail if Etherpad is enabled without the Dimension integrations manager - ansible.builtin.fail: - msg: >- - To integrate Etherpad notes with Matrix rooms you need to set "matrix_dimension_enabled" to true - when: "not matrix_dimension_enabled | bool" - - name: Fail if no database is configured for Etherpad ansible.builtin.fail: msg: >- diff --git a/roles/custom/matrix-nginx-proxy/defaults/main.yml b/roles/custom/matrix-nginx-proxy/defaults/main.yml index ca4a15e7..b7d4819d 100644 --- a/roles/custom/matrix-nginx-proxy/defaults/main.yml +++ b/roles/custom/matrix-nginx-proxy/defaults/main.yml @@ -192,6 +192,10 @@ matrix_nginx_proxy_proxy_matrix_federation_port: 8448 matrix_nginx_proxy_proxy_dimension_enabled: false matrix_nginx_proxy_proxy_dimension_hostname: "{{ matrix_server_fqn_dimension }}" +# Controls whether proxying the etherpad domain should be done. +matrix_nginx_proxy_proxy_etherpad_enabled: false +matrix_nginx_proxy_proxy_etherpad_hostname: "{{ matrix_server_fqn_etherpad }}" + # Controls whether proxying the goneb domain should be done. matrix_nginx_proxy_proxy_bot_go_neb_enabled: false matrix_nginx_proxy_proxy_bot_go_neb_hostname: "{{ matrix_server_fqn_bot_go_neb }}" @@ -373,6 +377,9 @@ matrix_nginx_proxy_proxy_buscarron_additional_server_configuration_blocks: [] # A list of strings containing additional configuration blocks to add to Dimension's server configuration (matrix-dimension.conf). matrix_nginx_proxy_proxy_dimension_additional_server_configuration_blocks: [] +# A list of strings containing additional configuration blocks to add to etherpad's server configuration (matrix-etherpad.conf). +matrix_nginx_proxy_proxy_etherpad_additional_server_configuration_blocks: [] + # A list of strings containing additional configuration blocks to add to GoNEB's server configuration (matrix-bot-go-neb.conf). matrix_nginx_proxy_proxy_bot_go_neb_additional_server_configuration_blocks: [] diff --git a/roles/custom/matrix-nginx-proxy/tasks/setup_nginx_proxy.yml b/roles/custom/matrix-nginx-proxy/tasks/setup_nginx_proxy.yml index 11a1cc06..3892550f 100644 --- a/roles/custom/matrix-nginx-proxy/tasks/setup_nginx_proxy.yml +++ b/roles/custom/matrix-nginx-proxy/tasks/setup_nginx_proxy.yml @@ -123,6 +123,13 @@ mode: 0644 when: matrix_nginx_proxy_proxy_dimension_enabled | bool +- name: Ensure Matrix nginx-proxy configuration for etherpad domain exists + ansible.builtin.template: + src: "{{ role_path }}/templates/nginx/conf.d/matrix-etherpad.conf.j2" + dest: "{{ matrix_nginx_proxy_confd_path }}/matrix-etherpad.conf" + mode: 0644 + when: matrix_nginx_proxy_proxy_etherpad_enabled | bool + - name: Ensure Matrix nginx-proxy configuration for goneb domain exists ansible.builtin.template: src: "{{ role_path }}/templates/nginx/conf.d/matrix-bot-go-neb.conf.j2" diff --git a/roles/custom/matrix-nginx-proxy/templates/nginx/conf.d/matrix-etherpad.conf.j2 b/roles/custom/matrix-nginx-proxy/templates/nginx/conf.d/matrix-etherpad.conf.j2 new file mode 100644 index 00000000..8cad9ee3 --- /dev/null +++ b/roles/custom/matrix-nginx-proxy/templates/nginx/conf.d/matrix-etherpad.conf.j2 @@ -0,0 +1,108 @@ +#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; + {% if matrix_nginx_proxy_floc_optout_enabled %} + add_header Permissions-Policy interest-cohort=() always; + {% endif %} + +{% for configuration_block in matrix_nginx_proxy_proxy_etherpad_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 {{ matrix_nginx_proxy_http_level_resolver }} valid=5s; + set $backend "matrix-etherpad:9001"; + proxy_pass http://$backend; + {# 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 {{ matrix_nginx_proxy_x_forwarded_proto_value }}; {# 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 %} + } +{% 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_etherpad_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 {{ matrix_nginx_proxy_http_level_resolver }} 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_etherpad_hostname }}; + + server_tokens off; + root /dev/null; + + ssl_certificate {{ matrix_ssl_config_dir_path }}/live/{{ matrix_nginx_proxy_proxy_etherpad_hostname }}/fullchain.pem; + ssl_certificate_key {{ matrix_ssl_config_dir_path }}/live/{{ matrix_nginx_proxy_proxy_etherpad_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_etherpad_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 %} From a86cb2336a7d7ccab919812e8f63c3218ecdfc6b Mon Sep 17 00:00:00 2001 From: Aine Date: Fri, 4 Nov 2022 17:16:29 +0200 Subject: [PATCH 2/5] etherpad - do not request ssl cert for subdomain if dimension is installed --- group_vars/matrix_servers | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/group_vars/matrix_servers b/group_vars/matrix_servers index 26e5b35f..4a3c1193 100755 --- a/group_vars/matrix_servers +++ b/group_vars/matrix_servers @@ -1840,7 +1840,7 @@ matrix_ssl_domains_to_obtain_certificates_for: | + ([matrix_server_fqn_dimension] if matrix_dimension_enabled else []) + - ([matrix_server_fqn_etherpad] if matrix_etherpad_enabled else []) + ([matrix_server_fqn_etherpad] if (matrix_etherpad_enabled and not matrix_dimension_enabled) else []) + ([matrix_server_fqn_bot_go_neb] if matrix_bot_go_neb_enabled else []) + From 06eb186729c7d53a5627e2463f3f7a38cdc67664 Mon Sep 17 00:00:00 2001 From: Aine Date: Sat, 5 Nov 2022 09:17:47 +0200 Subject: [PATCH 3/5] add matrix_etherpad_mode --- docs/configuring-playbook-etherpad.md | 8 ++++++-- group_vars/matrix_servers | 8 ++++---- roles/custom/matrix-etherpad/defaults/main.yml | 8 ++++++-- roles/custom/matrix-etherpad/tasks/init.yml | 12 +----------- 4 files changed, 17 insertions(+), 19 deletions(-) diff --git a/docs/configuring-playbook-etherpad.md b/docs/configuring-playbook-etherpad.md index 3214d861..4c5df6fa 100644 --- a/docs/configuring-playbook-etherpad.md +++ b/docs/configuring-playbook-etherpad.md @@ -38,14 +38,18 @@ Then from the plugin manager page (`https://etherpad./admin/plugins ## Set Dimension default to the self-hosted Etherpad (optional) If you decided to install [Dimension integration manager](configuring-playbook-dimension.md) alongside with 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. +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 and add the following to your vars.yml: + +```yaml +matrix_etherpad_mode: dimension +``` ### 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./etherpad/p/$roomId_$padName?showChat=false` -## Known issues +### 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`. diff --git a/group_vars/matrix_servers b/group_vars/matrix_servers index fcdff5ac..7df71247 100755 --- a/group_vars/matrix_servers +++ b/group_vars/matrix_servers @@ -1526,7 +1526,7 @@ matrix_etherpad_enabled: false matrix_etherpad_container_http_host_bind_port: "{{ '' if matrix_nginx_proxy_enabled else '127.0.0.1:9001' }}" -matrix_etherpad_base_url: "{{ 'https://'+ matrix_server_fqn_dimension + matrix_etherpad_public_endpoint if matrix_dimension_enabled else 'https://' + matrix_server_fqn_etherpad + '/' }}" +matrix_etherpad_base_url: "{{ 'https://'+ matrix_server_fqn_dimension + matrix_etherpad_public_endpoint if matrix_etherpad_mode == 'dimension' else 'https://' + matrix_server_fqn_etherpad + '/' }}" matrix_etherpad_systemd_required_services_list: | {{ @@ -1752,7 +1752,7 @@ matrix_nginx_proxy_proxy_hydrogen_enabled: "{{ matrix_client_hydrogen_enabled }} matrix_nginx_proxy_proxy_cinny_enabled: "{{ matrix_client_cinny_enabled }}" matrix_nginx_proxy_proxy_buscarron_enabled: "{{ matrix_bot_buscarron_enabled }}" matrix_nginx_proxy_proxy_dimension_enabled: "{{ matrix_dimension_enabled }}" -matrix_nginx_proxy_proxy_etherpad_enabled: "{{ matrix_etherpad_enabled }}" +matrix_nginx_proxy_proxy_etherpad_enabled: "{{ matrix_etherpad_enabled and matrix_etherpad_mode == 'standalone' }}" 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 }}" @@ -1859,7 +1859,7 @@ matrix_nginx_proxy_systemd_wanted_services_list: | + (['matrix-bot-go-neb.service'] if matrix_bot_go_neb_enabled else []) + - (['matrix-etherpad.service'] if matrix_etherpad_enabled and matrix_dimension_enabled else []) + (['matrix-etherpad.service'] if matrix_etherpad_enabled else []) + (['matrix-hookshot.service'] if matrix_hookshot_enabled else []) }} @@ -1880,7 +1880,7 @@ matrix_ssl_domains_to_obtain_certificates_for: | + ([matrix_server_fqn_dimension] if matrix_dimension_enabled else []) + - ([matrix_server_fqn_etherpad] if (matrix_etherpad_enabled and not matrix_dimension_enabled) else []) + ([matrix_server_fqn_etherpad] if (matrix_etherpad_enabled and matrix_etherpad_mode == 'standalone') else []) + ([matrix_server_fqn_bot_go_neb] if matrix_bot_go_neb_enabled else []) + diff --git a/roles/custom/matrix-etherpad/defaults/main.yml b/roles/custom/matrix-etherpad/defaults/main.yml index 35d24090..2a8d24e8 100644 --- a/roles/custom/matrix-etherpad/defaults/main.yml +++ b/roles/custom/matrix-etherpad/defaults/main.yml @@ -3,6 +3,10 @@ matrix_etherpad_enabled: false +# standalone = etherpad installed on subdomain (etherpad.DOMAIN) and can be used as-is +# dimension = etherpad installed in subdir of dimension (dimension.DOMAIN/etherpad) and can be used with dimension +matrix_etherpad_mode: standalone + matrix_etherpad_base_path: "{{ matrix_base_data_path }}/etherpad" matrix_etherpad_version: 1.8.18 @@ -31,8 +35,8 @@ matrix_etherpad_container_extra_arguments: [] # Used for dimension only 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 }}" +# By default, the Etherpad app can be accessed on etherpad subdomain +matrix_etherpad_base_url: "https://{{ matrix_server_fqn_etherpad }}/" # Database-related configuration fields. # diff --git a/roles/custom/matrix-etherpad/tasks/init.yml b/roles/custom/matrix-etherpad/tasks/init.yml index c787548c..d35ed375 100644 --- a/roles/custom/matrix-etherpad/tasks/init.yml +++ b/roles/custom/matrix-etherpad/tasks/init.yml @@ -4,7 +4,7 @@ matrix_systemd_services_list: "{{ matrix_systemd_services_list + ['matrix-etherpad.service'] }}" when: matrix_etherpad_enabled | bool -- when: matrix_etherpad_enabled | bool and matrix_dimension_enabled | default(False) | bool +- when: matrix_etherpad_enabled | bool and matrix_etherpad_mode == 'dimension' tags: - always block: @@ -52,13 +52,3 @@ + [matrix_etherpad_matrix_nginx_proxy_configuration] }} - -- name: Warn about reverse-proxying if matrix-nginx-proxy not used - ansible.builtin.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 not matrix_nginx_proxy_enabled | default(False) | bool" From 39e4b419dd62d6c62609d51de32dd40ebabc82a5 Mon Sep 17 00:00:00 2001 From: Aine Date: Sat, 5 Nov 2022 09:29:53 +0200 Subject: [PATCH 4/5] matrix-etherpad: fail when mode is 'dimension', but dimension is disabled --- roles/custom/matrix-etherpad/tasks/main.yml | 10 +++++----- roles/custom/matrix-etherpad/tasks/validate_config.yml | 6 ++++++ 2 files changed, 11 insertions(+), 5 deletions(-) diff --git a/roles/custom/matrix-etherpad/tasks/main.yml b/roles/custom/matrix-etherpad/tasks/main.yml index b1c8ab55..caf0dda5 100644 --- a/roles/custom/matrix-etherpad/tasks/main.yml +++ b/roles/custom/matrix-etherpad/tasks/main.yml @@ -4,20 +4,20 @@ tags: - always -- ansible.builtin.import_tasks: "{{ role_path }}/tasks/setup_install.yml" +- ansible.builtin.import_tasks: "{{ role_path }}/tasks/validate_config.yml" when: run_setup | bool and matrix_etherpad_enabled | bool tags: - setup-all - setup-etherpad -- ansible.builtin.import_tasks: "{{ role_path }}/tasks/setup_uninstall.yml" - when: run_setup | bool and not matrix_etherpad_enabled | bool +- ansible.builtin.import_tasks: "{{ role_path }}/tasks/setup_install.yml" + when: run_setup | bool and matrix_etherpad_enabled | bool tags: - setup-all - setup-etherpad -- ansible.builtin.import_tasks: "{{ role_path }}/tasks/validate_config.yml" - when: run_setup | bool and matrix_etherpad_enabled | bool +- ansible.builtin.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/custom/matrix-etherpad/tasks/validate_config.yml b/roles/custom/matrix-etherpad/tasks/validate_config.yml index 9832b0b8..10ddc584 100644 --- a/roles/custom/matrix-etherpad/tasks/validate_config.yml +++ b/roles/custom/matrix-etherpad/tasks/validate_config.yml @@ -5,3 +5,9 @@ msg: >- Etherpad requires a dedicated Postgres database. Please enable the built in one, or configure an external DB by redefining "matrix_etherpad_database_hostname" when: matrix_etherpad_database_hostname == "matrix-postgres" and not matrix_postgres_enabled + +- name: Fail if wrong mode selected + ansible.builtin.fail: + msg: >- + You're using Etherpad in 'dimension' mode (`matrix_etherpad_serving_mode: dimension`), which tries to host Etherpad at the Dimension subdomain - `{{ matrix_server_fqn_dimension }}`. However, this isn't possible because Dimension is not enabled. To resolve the problem, either enable Dimension (`matrix_dimension_enabled: true`) or switch Etherpad to standalone mode (`matrix_etherpad_mode: standalone`) and have it served on its own domain (`{{ matrix_server_fqn_etherpad }}`). + when: matrix_etherpad_enabled | bool and matrix_etherpad_mode == 'dimension' and not matrix_dimension_enabled | default(False) | bool From 805b70bfa3f521ff486e3191108e0798fc6676ba Mon Sep 17 00:00:00 2001 From: Slavi Pantaleev Date: Sat, 5 Nov 2022 11:47:47 +0200 Subject: [PATCH 5/5] Announce standalone Etherpad --- CHANGELOG.md | 15 +++++++ docs/configuring-playbook-etherpad.md | 42 +++++++++++-------- .../custom/matrix-etherpad/defaults/main.yml | 2 +- 3 files changed, 40 insertions(+), 19 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9bd06a8c..bd38e1a9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,18 @@ +# 2022-11-05 + +## (Backward Compatibility Break) A new default standalone mode for Etherpad + +Until now, [Etherpad](https://etherpad.org/) (which [the playbook could install for you](docs/configuring-playbook-etherpad.md)) required the [Dimension integration manager](docs/configuring-playbook-dimension.md) to also be installed, because Etherpad was hosted on the Dimension domain (at `dimension.DOMAIN/etherpad`). + +From now on, Etherpad can be installed in `standalone` mode on `etherpad.DOMAIN` and used even without Dimension. This is much more versatile, so the playbook now defaults to this new mode (`matrix_etherpad_mode: standalone`). + +If you've already got both Etherpad and Dimension in use you could: + +- **either** keep hosting Etherpad under the Dimension domain by adding `matrix_etherpad_mode: dimension` to your `vars.yml` file. All your existing room widgets will continue working at the same URLs and no other changes will be necessary. + +- **or**, you could change to hosting Etherpad separately on `etherpad.DOMAIN`. You will need to [configure a DNS record](docs/configuring-dns.md) for this new domain. You will also need to reconfigure Dimension to use the new pad URLs (`https://etherpad.DOMAIN/...`) going forward (refer to our [configuring Etherpad documentation](docs/configuring-playbook-etherpad.md)). All your existing room widgets (which still use `https://dimension.DOMAIN/etherpad/...`) will break as Etherpad is not hosted there anymore. You will need to re-add them or to consider not using `standalone` mode + + # 2022-11-04 ## The playbook now uses external roles for some things diff --git a/docs/configuring-playbook-etherpad.md b/docs/configuring-playbook-etherpad.md index 4c5df6fa..2ea423ef 100644 --- a/docs/configuring-playbook-etherpad.md +++ b/docs/configuring-playbook-etherpad.md @@ -1,14 +1,20 @@ # 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) or used as standalone web app +[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) or used as standalone web app. 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 -The `etherpad.` DNS record must be created. See [Configuring your DNS server](configuring-dns.md) on how to set up DNS record correctly. +Etherpad can be installed in 2 modes: + +- (default) `standalone` mode (`matrix_etherpad_mode: standalone`) - Etherpad will be hosted on `etherpad.` (`matrix_server_fqn_etherpad`), so the DNS record for this domian must be created. See [Configuring your DNS server](configuring-dns.md) on how to set up the `etherpad` DNS record correctly + +- `dimension` mode (`matrix_etherpad_mode: dimension`) - Etherpad will be hosted on `dimension./etherpad` (`matrix_server_fqn_dimension`). This requires that you **first** configure the **Dimension integrations manager** as described in [the playbook documentation](configuring-playbook-dimension.md) + +We recomend that you go with the default (`standalone`) mode, which makes Etherpad independent and allows it to be used with or without Dimension. -You may enable and configure the **Dimension integrations manager** as described in [the playbook documentation](configuring-playbook-dimension.md) to integrate etherpad with Dimension. ## Installing @@ -16,18 +22,17 @@ You may enable and configure the **Dimension integrations manager** as described ```yaml matrix_etherpad_enabled: true -``` - -## Etherpad Admin access (optional) -Etherpad comes with a admin web-UI which is disabled by default. You can enable it by setting a username and password in your configuration file (`inventory/host_vars/matrix./vars.yml`): +# Uncomment below if you'd like to install Etherpad on the Dimension domain (not recommended) +# matrix_etherpad_mode: dimension -```yaml -matrix_etherpad_admin_username: admin -matrix_etherpad_admin_password: some-password +# Uncomment below to enable the admin web UI +# matrix_etherpad_admin_username: admin +# matrix_etherpad_admin_password: some-password ``` -The admin web-UI should then be available on: `https://dimension./etherpad/admin` +If enabled, the admin web-UI should then be available on `https://etherpad./admin` (or `https://dimension./etherpad/admin`, if `matrix_etherpad_mode: dimension`) + ## Managing / Deleting old pads @@ -35,19 +40,20 @@ If you want to manage and remove old unused pads from Etherpad, you will first n Then from the plugin manager page (`https://etherpad./admin/plugins` or `https://dimension./etherpad/admin/plugins`), install the `adminpads2` plugin. Once installed, you should have a "Manage pads" section in the Admin web-UI. + ## Set Dimension default to the self-hosted Etherpad (optional) -If you decided to install [Dimension integration manager](configuring-playbook-dimension.md) alongside with 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 and add the following to your vars.yml: +If you decided to install [Dimension integration manager](configuring-playbook-dimension.md) alongside 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. -```yaml -matrix_etherpad_mode: dimension -``` ### 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./etherpad/p/$roomId_$padName?showChat=false` +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. Examples: +- `https://etherpad./p/$roomId_$padName?showChat=false` (for the default - `matrix_etherpad_mode: standalone`) + +- `https://dimension./etherpad/p/$roomId_$padName?showChat=false` (for `matrix_etherpad_mode: dimension`) + ### Known issues diff --git a/roles/custom/matrix-etherpad/defaults/main.yml b/roles/custom/matrix-etherpad/defaults/main.yml index 2a8d24e8..505c9c4b 100644 --- a/roles/custom/matrix-etherpad/defaults/main.yml +++ b/roles/custom/matrix-etherpad/defaults/main.yml @@ -32,7 +32,7 @@ matrix_etherpad_container_http_host_bind_port: '' # A list of extra arguments to pass to the container matrix_etherpad_container_extra_arguments: [] -# Used for dimension only +# Used only when `matrix_etherpad_mode: dimension` matrix_etherpad_public_endpoint: '/etherpad' # By default, the Etherpad app can be accessed on etherpad subdomain