Merge pull request #2229 from etkecc/make-etherpad-great-again

standalone etherpad
This commit is contained in:
Slavi Pantaleev 2022-11-05 11:54:51 +02:00 committed by GitHub
commit 13b63eabf0
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
12 changed files with 205 additions and 49 deletions

View file

@ -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

View file

@ -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.<your-domain>` |
| [Sygnal](configuring-playbook-sygnal.md) push notification gateway | CNAME | `sygnal` | - | - | - | `matrix.<your-domain>` |
| [ntfy](configuring-playbook-ntfy.md) push notifications server | CNAME | `ntfy` | - | - | - | `matrix.<your-domain>` |
| [Etherpad](configuring-playbook-etherpad.md) collaborative text editor | CNAME | `etherpad` | - | - | - | `matrix.<your-domain>` |
| [Hydrogen](configuring-playbook-client-hydrogen.md) web client | CNAME | `hydrogen` | - | - | - | `matrix.<your-domain>` |
| [Cinny](configuring-playbook-client-cinny.md) web client | CNAME | `cinny` | - | - | - | `matrix.<your-domain>` |
| [Buscarron](configuring-playbook-bot-buscarron.md) helpdesk bot | CNAME | `buscarron` | - | - | - | `matrix.<your-domain>` |
@ -68,6 +69,8 @@ The `sygnal.<your-domain>` subdomain may be necessary, because this playbook cou
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 `etherpad.<your-domain>` 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.<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.

View file

@ -1,12 +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)
[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)
Etherpad can be installed in 2 modes:
- (default) `standalone` mode (`matrix_etherpad_mode: standalone`) - Etherpad will be hosted on `etherpad.<your-domain>` (`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.<your-domain>/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.
## Installing
@ -14,35 +22,40 @@ For the self-hosted Etherpad instance to be available to your users, you must fi
```yaml
matrix_etherpad_enabled: true
# Uncomment below if you'd like to install Etherpad on the Dimension domain (not recommended)
# matrix_etherpad_mode: dimension
# Uncomment below to enable the admin web UI
# matrix_etherpad_admin_username: admin
# matrix_etherpad_admin_password: some-password
```
## Set Dimension default to the self-hosted Etherpad
If enabled, the admin web-UI should then be available on `https://etherpad.<your-domain>/admin` (or `https://dimension.<your-domain>/etherpad/admin`, if `matrix_etherpad_mode: dimension`)
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`
### 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.<your-domain>/vars.yml`):
```yaml
matrix_etherpad_admin_username: admin
matrix_etherpad_admin_password: some-password
```
The admin web-UI should then be available on: `https://dimension.<your-domain>/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.<your-domain>/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.<your-domain>/admin/plugins` or `https://dimension.<your-domain>/etherpad/admin/plugins`), install the `adminpads2` plugin. Once installed, you should have a "Manage pads" section in the Admin web-UI.
## Known issues
## Set Dimension default to the self-hosted Etherpad (optional)
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.
### 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. Examples:
- `https://etherpad.<your-domain>/p/$roomId_$padName?showChat=false` (for the default - `matrix_etherpad_mode: standalone`)
- `https://dimension.<your-domain>/etherpad/p/$roomId_$padName?showChat=false` (for `matrix_etherpad_mode: dimension`)
### 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`.

View file

@ -1526,6 +1526,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_etherpad_mode == 'dimension' else 'https://' + matrix_server_fqn_etherpad + '/' }}"
matrix_etherpad_systemd_required_services_list: |
{{
['docker.service']
@ -1750,6 +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 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 }}"
@ -1856,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 [])
}}
@ -1877,6 +1880,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 and matrix_etherpad_mode == 'standalone') else [])
+
([matrix_server_fqn_bot_go_neb] if matrix_bot_go_neb_enabled else [])
+
([matrix_server_fqn_jitsi] if matrix_jitsi_enabled else [])

View file

@ -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 }}"

View file

@ -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
@ -28,10 +32,11 @@ matrix_etherpad_container_http_host_bind_port: ''
# A list of extra arguments to pass to the container
matrix_etherpad_container_extra_arguments: []
# Used only when `matrix_etherpad_mode: dimension`
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.
#

View file

@ -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_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"

View file

@ -4,6 +4,12 @@
tags:
- always
- 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_install.yml"
when: run_setup | bool and matrix_etherpad_enabled | bool
tags:
@ -15,9 +21,3 @@
tags:
- setup-all
- setup-etherpad
- ansible.builtin.import_tasks: "{{ role_path }}/tasks/validate_config.yml"
when: run_setup | bool and matrix_etherpad_enabled | bool
tags:
- setup-all
- setup-etherpad

View file

@ -1,13 +1,13 @@
---
- 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: >-
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

View file

@ -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: []

View file

@ -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"

View file

@ -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 %}