matrix-docker-ansible-deploy/docs/configuring-playbook-etherpad.md

Setting up Etherpad (optional)

The playbook can install and configure Etherpad for you.

Etherpad is an open source collaborative text editor. It can not only be integrated with Element clients (Element Web/Desktop, Android and iOS) as a widget, but also be used as standalone web app.

When enabled together with the Jitsi audio/video conferencing system (see our docs on Jitsi), it will be made available as an option during the conferences.

This Ansible role for Etherpad is developed and maintained by MASH (mother-of-all-self-hosting) project.

Adjusting DNS records

By default, this playbook installs Etherpad on the etherpad. subdomain (etherpad.example.com) and requires you to create a CNAME record for etherpad, which targets matrix.example.com.

When setting, replace example.com with your own.

Adjusting the playbook configuration

To enable Etherpad, add the following configuration to your inventory/host_vars/matrix.example.com/vars.yml file:

########################################################################
#                                                                      #
# etherpad                                                             #
#                                                                      #
########################################################################

etherpad_enabled: true

########################################################################
#                                                                      #
# /etherpad                                                            #
#                                                                      #
########################################################################

As the most of the necessary settings for the role have been taken care of by the playbook, you can enable Etherpad on your Matrix server with this minimum configuration.

For details about configuring Etherpad per your preference, you can check them via:

• the role's document on the MASH (mother-of-all-self-hosting) project
• roles/galaxy/etherpad/docs/configuring-etherpad.md locally, if you have fetched the Ansible roles

Create admin user (optional)

You probably might want to enable authentication to disallow anonymous access to your Etherpad.

It is possible to enable HTTP basic authentication by creating an admin user with etherpad_admin_username and etherpad_admin_password variables. The admin user account is also used by plugins for authentication and authorization.

See this section on the role's document for details about how to create the admin user.

Adjusting the Etherpad URL (optional)

By tweaking the etherpad_hostname and etherpad_path_prefix variables, you can easily make the service available at a different hostname and/or path than the default one.

Example additional configuration for your vars.yml file:

# Switch to the domain used for Matrix services (`matrix.example.com`),
# so we won't need to add additional DNS records for Etherpad.
etherpad_hostname: "{{ matrix_server_fqn_matrix }}"

# Expose under the /etherpad subpath
etherpad_path_prefix: /etherpad

After changing the domain, you may need to adjust your DNS records to point the Etherpad domain to the Matrix server.

If you've decided to reuse the matrix. domain, you won't need to do any extra DNS configuration.

Installing

After configuring the playbook and potentially adjusting your DNS records, run the playbook with playbook tags as below:

ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start

Notes:

• The ensure-matrix-users-created playbook tag makes the playbook automatically create the Etherpad admin user (etherpad_admin_username).

• The shortcut commands with the just program are also available: just install-all or just setup-all

  just install-all is useful for maintaining your setup quickly (2x-5x faster than just setup-all) when its components remain unchanged. If you adjust your vars.yml to remove other components, you'd need to run just setup-all, or these components will still remain installed.

Usage

By default, the Etherpad UI should be available at https://etherpad.example.com, while the admin UI (if enabled) should then be available at https://etherpad.example.com/admin.

If you've decided on another hostname or path-prefix (e.g. https://matrix.example.com/etherpad), adjust these URLs accordingly before using it.

💡 For more information about usage, take a look at this section on the role's document.

Integrating a Etherpad widget in a room

Note: this is how it works in Element Web. It might work quite similar with other clients:

To integrate a standalone Etherpad in a room, create your pad by visiting https://etherpad.example.com. When the pad opens, copy the URL and send a command like this to the room: /addwidget URL. You will then find your integrated Etherpad within the right sidebar in the Widgets section.

Troubleshooting

See this section on the role's document for details.