Announce standalone Etherpad

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

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.<your-domain>` 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.<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.
 
-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.<your-domain>/vars.yml`):
+# Uncomment below if you'd like to install Etherpad on the Dimension domain (not recommended)
+# matrix_etherpad_mode: dimension
 
-```yaml
+# Uncomment below to enable the admin web UI
-matrix_etherpad_admin_username: admin
+# matrix_etherpad_admin_username: admin
-matrix_etherpad_admin_password: some-password
+# matrix_etherpad_admin_password: some-password
 ```
 
-The admin web-UI should then be available on: `https://dimension.<your-domain>/etherpad/admin`
+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`)
+
 
 ## 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.<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.
 
+
 ## Set Dimension default to the self-hosted Etherpad (optional)
 
-If you decided to install [Dimension integration manager](configuring-playbook-dimension.md) alongside with Etherpad,
+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 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:
+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.
+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:
-Example: `https://dimension.<your-domain>/etherpad/p/$roomId_$padName?showChat=false`
+- `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
 

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