Merge pull request #804 from pushytoxin/matrix-etherpad

Self-hosted Etherpad
This commit is contained in:
Slavi Pantaleev 2021-01-31 09:55:46 +02:00 committed by GitHub
commit 889b299bc2
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
18 changed files with 496 additions and 0 deletions

View File

@ -1,3 +1,12 @@
# 2021-01-31
## Etherpad support
Thanks to [@pushytoxin](https://github.com/pushytoxin), the playbook can now install the [Etherpad](https://etherpad.org) realtime collaborative text editor. It can be used in a [Jitsi](https://jitsi.org/) audio/video call or integrated as a widget into Matrix chat rooms via the [Dimension](https://dimension.t2bot.io) integration manager.
To get it installed, follow [our Etherpad docs page](docs/configuring-playbook-etherpad.md).
# 2021-01-22
## (Breaking Change) Postgres changes that require manual intervention

View File

@ -81,6 +81,8 @@ Using this playbook, you can get the following services configured on your serve
- (optional) [Dimension](https://github.com/turt2live/matrix-dimension), an open source integrations manager for matrix clients - see [docs/configuring-playbook-dimension.md](docs/configuring-playbook-dimension.md) for setup documentation
- (optional) [Etherpad](https://etherpad.org), an open source collaborative text editor - see [docs/configuring-playbook-etherpad.md](docs/configuring-playbook-etherpad.md) for setup documentation
- (optional) [Jitsi](https://jitsi.org/), an open source video-conferencing platform - see [docs/configuring-playbook-jitsi.md](docs/configuring-playbook-jitsi.md) for setup documentation
- (optional) [matrix-reminder-bot](https://github.com/anoadragon453/matrix-reminder-bot) for scheduling one-off & recurring reminders and alarms - see [docs/configuring-playbook-bot-matrix-reminder-bot.md](docs/configuring-playbook-bot-matrix-reminder-bot.md) for setup documentation

View File

@ -0,0 +1,26 @@
# 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)
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)
## Installing
[Etherpad](https://etherpad.org) installation is disabled by default. You can enable it in your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
```yaml
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.<your-domain>/etherpad/p/$roomId_$padName?showChat=false`

View File

@ -32,6 +32,8 @@ These services are not part of our default installation, but can be enabled by [
- [ewoutp/goofys](https://hub.docker.com/r/ewoutp/goofys/) - the [Goofys](https://github.com/kahing/goofys) Amazon [S3](https://aws.amazon.com/s3/) file-system-mounting program (optional)
- [etherpad/etherpad](https://hub.docker.com/r/etherpad/etherpad/) - the [Etherpad](https://etherpad.org) realtime collaborative text editor that can be used in a Jitsi audio/video call or integrated as a widget into Matrix chat rooms via the Dimension integration manager (optional)
- [devture/email2matrix](https://hub.docker.com/r/devture/email2matrix/) - the [Email2Matrix](https://github.com/devture/email2matrix) email server, which can relay email messages to Matrix rooms (optional)
- [devture/matrix-corporal](https://hub.docker.com/r/devture/matrix-corporal/) - [Matrix Corporal](https://github.com/devture/matrix-corporal): reconciliator and gateway for a managed Matrix server (optional)

View File

@ -757,7 +757,30 @@ matrix_dimension_database_password: "{{ matrix_synapse_macaroon_secret_key | pas
#
######################################################################
######################################################################
#
# matrix-etherpad
#
######################################################################
matrix_etherpad_enabled: false
matrix_etherpad_systemd_required_services_list: |
{{
['docker.service']
+
(['matrix-postgres.service'] if matrix_postgres_enabled else [])
}}
# Postgres is the default, except if not using `matrix_postgres` (internal postgres)
matrix_etherpad_database_engine: "{{ 'postgres' if matrix_postgres_enabled else 'sqlite' }}"
matrix_etherpad_database_password: "{{ matrix_synapse_macaroon_secret_key | password_hash('sha512', 'etherpad.db') | to_uuid }}"
######################################################################
#
# /matrix-etherpad
#
######################################################################
######################################################################
#
@ -820,6 +843,13 @@ matrix_jitsi_web_stun_servers: |
else [ 'stun:meet-jit-si-turnrelay.jitsi.net:443']
}}
# If the self-hosted Etherpad instance is available, it will also show up in Jitsi conferences,
# unless explicitly disabled by setting `matrix_jitsi_etherpad_enabled` to false.
# Falls back to the scalar.vector.im etherpad in case someone sets `matrix_jitsi_etherpad_enabled` to true,
# while also setting `matrix_etherpad_enabled` to false.
matrix_jitsi_etherpad_enabled: "{{ matrix_etherpad_enabled }}"
matrix_jitsi_etherpad_base: "{{ matrix_etherpad_base_url if matrix_etherpad_enabled else 'https://scalar.vector.im/etherpad' }}"
######################################################################
#
# /matrix-jitsi
@ -1146,6 +1176,12 @@ matrix_postgres_additional_databases: |
'username': matrix_dimension_database_username,
'password': matrix_dimension_database_password,
}] if (matrix_dimension_enabled and matrix_dimension_database_engine == 'postgres' and matrix_dimension_database_hostname == 'matrix-postgres') else [])
+
([{
'name': matrix_etherpad_database_name,
'username': matrix_etherpad_database_username,
'password': matrix_etherpad_database_password,
}] if (matrix_etherpad_enabled and matrix_etherpad_database_engine == 'postgres' and matrix_etherpad_database_hostname == 'matrix-postgres') else [])
}}
matrix_postgres_import_roles_to_ignore: |

View File

@ -0,0 +1,93 @@
matrix_etherpad_enabled: false
matrix_etherpad_base_path: "{{ matrix_base_data_path }}/etherpad"
matrix_etherpad_docker_image: "docker.io/etherpad/etherpad:1.8.7"
matrix_etherpad_docker_image_force_pull: "{{ matrix_etherpad_docker_image.endswith(':latest') }}"
# List of systemd services that matrix-etherpad.service depends on.
matrix_etherpad_systemd_required_services_list: ['docker.service']
# List of systemd services that matrix-etherpad.service wants
matrix_etherpad_systemd_wanted_services_list: []
# Container user has to be able to write to the source file directories until this bug is fixed:
# https://github.com/ether/etherpad-lite/issues/2683
matrix_etherpad_user_uid: '5001'
matrix_etherpad_user_gid: '5001'
# Controls whether the matrix-etherpad container exposes its HTTP port (tcp/9001 in the container).
#
# Takes an "<ip>:<port>" or "<port>" value (e.g. "127.0.0.1:9001"), or empty string to not expose.
matrix_etherpad_container_http_host_bind_port: '9001'
# A list of extra arguments to pass to the container
matrix_etherpad_container_extra_arguments: []
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 }}"
# Database-related configuration fields.
#
# Etherpad recommends using a dedicated database, and supports Sqlite only for development
#
# To use Postgres:
# - change the engine (`matrix_etherpad_database_engine: 'postgres'`)
# - adjust your database credentials via the `matrix_etherpad_postgres_*` variables
matrix_etherpad_database_engine: 'sqlite'
matrix_etherpad_sqlite_database_path_local: "{{ matrix_etherpad_base_path }}/etherpad.db"
matrix_etherpad_sqlite_database_path_in_container: "/data/etherpad.db"
matrix_etherpad_database_username: 'matrix_etherpad'
matrix_etherpad_database_password: 'some-password'
matrix_etherpad_database_hostname: 'matrix-postgres'
matrix_etherpad_database_port: 5432
matrix_etherpad_database_name: 'matrix_etherpad'
matrix_etherpad_database_connection_string: 'postgres://{{ matrix_etherpad_database_username }}:{{ matrix_etherpad_database_password }}@{{ matrix_etherpad_database_hostname }}:{{ matrix_etherpad_database_port }}/{{ matrix_etherpad_database_name }}'
# Variables configuring the etherpad
matrix_etherpad_title: 'Etherpad'
matrix_etherpad_default_pad_text: |
Welcome to Etherpad!
This pad text is synchronized as you type, so that everyone viewing this page sees the same text. This allows you to collaborate seamlessly on documents!
Get involved with Etherpad at https://etherpad.org
# Default Etherpad 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_etherpad_configuration_extension_json`)
# or completely replace this variable with your own template.
matrix_etherpad_configuration_default: "{{ lookup('template', 'templates/settings.json.j2') }}"
# Your custom JSON configuration for Etherpad goes here.
# This configuration extends the default starting configuration (`matrix_etherpad_configuration_json`).
#
# 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_etherpad_configuration_json`.
#
# Example configuration extension follows:
#
# matrix_etherpad_configuration_extension_json: |
# {
# "loadTest": true,
# "commitRateLimiting": {
# "duration": 1,
# "points": 10
# }
# }
#
matrix_etherpad_configuration_extension_json: '{}'
matrix_etherpad_configuration_extension: "{{ matrix_etherpad_configuration_extension_json|from_json if matrix_etherpad_configuration_extension_json|from_json is mapping else {} }}"
# Holds the final Etherpad configuration (a combination of the default and its extension).
# You most likely don't need to touch this variable. Instead, see `matrix_etherpad_configuration_json`.
matrix_etherpad_configuration: "{{ matrix_etherpad_configuration_default|combine(matrix_etherpad_configuration_extension, recursive=True) }}"

View File

@ -0,0 +1,62 @@
- set_fact:
matrix_systemd_services_list: "{{ matrix_systemd_services_list + ['matrix-etherpad.service'] }}"
when: matrix_etherpad_enabled|bool
- block:
- name: Fail if matrix-nginx-proxy role already executed
fail:
msg: >-
Trying to append Etherpad's reverse-proxying configuration to matrix-nginx-proxy,
but it's pointless since the matrix-nginx-proxy role had already executed.
To fix this, please change the order of roles in your plabook,
so that the matrix-nginx-proxy role would run after the matrix-etherpad role.
when: matrix_nginx_proxy_role_executed|default(False)|bool
- name: Generate Etherpad proxying configuration for matrix-nginx-proxy
set_fact:
matrix_etherpad_matrix_nginx_proxy_configuration: |
rewrite ^{{ matrix_etherpad_public_endpoint }}$ $scheme://$server_name{{ matrix_etherpad_public_endpoint }}/ permanent;
location {{ matrix_etherpad_public_endpoint }}/ {
{% if matrix_nginx_proxy_enabled|default(False) %}
{# Use the embedded DNS resolver in Docker containers to discover the service #}
resolver 127.0.0.11 valid=5s;
proxy_pass http://matrix-etherpad:9001/;
{# 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 $scheme; # 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 %}
}
- name: Register Etherpad proxying configuration with matrix-nginx-proxy
set_fact:
matrix_nginx_proxy_proxy_dimension_additional_server_configuration_blocks: |
{{
matrix_nginx_proxy_proxy_dimension_additional_server_configuration_blocks|default([])
+
[matrix_etherpad_matrix_nginx_proxy_configuration]
}}
tags:
- always
when: matrix_etherpad_enabled|bool
- name: Warn about reverse-proxying if matrix-nginx-proxy not used
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 matrix_nginx_proxy_enabled is not defined"

View File

@ -0,0 +1,21 @@
- import_tasks: "{{ role_path }}/tasks/init.yml"
tags:
- always
- import_tasks: "{{ role_path }}/tasks/setup_install.yml"
when: run_setup|bool and matrix_etherpad_enabled|bool
tags:
- setup-all
- setup-etherpad
- import_tasks: "{{ role_path }}/tasks/setup_uninstall.yml"
when: run_setup|bool and not matrix_etherpad_enabled|bool
tags:
- setup-all
- setup-etherpad
- import_tasks: "{{ role_path }}/tasks/validate_config.yml"
when: run_setup|bool and matrix_etherpad_enabled|bool
tags:
- setup-all
- setup-etherpad

View File

@ -0,0 +1,36 @@
---
- name: Ensure Etherpad base path exists
file:
path: "{{ matrix_etherpad_base_path }}"
state: directory
mode: 0770
owner: "{{ matrix_etherpad_user_uid }}"
group: "{{ matrix_etherpad_user_gid }}"
- name: Ensure Etherpad config installed
copy:
content: "{{ matrix_etherpad_configuration|to_nice_json }}"
dest: "{{ matrix_etherpad_base_path }}/settings.json"
mode: 0640
owner: "{{ matrix_etherpad_user_uid }}"
group: "{{ matrix_etherpad_user_gid }}"
- name: Ensure Etherpad image is pulled
docker_image:
name: "{{ matrix_etherpad_docker_image }}"
source: "{{ 'pull' if ansible_version.major > 2 or ansible_version.minor > 7 else omit }}"
force_source: "{{ matrix_etherpad_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_etherpad_docker_image_force_pull }}"
- name: Ensure matrix-etherpad.service installed
template:
src: "{{ role_path }}/templates/systemd/matrix-etherpad.service.j2"
dest: "{{ matrix_systemd_path }}/matrix-etherpad.service"
mode: 0644
register: matrix_etherpad_systemd_service_result
- name: Ensure systemd reloaded after matrix-etherpad.service installation
service:
daemon_reload: yes
when: "matrix_etherpad_systemd_service_result.changed|bool"

View File

@ -0,0 +1,35 @@
---
- name: Check existence of matrix-etherpad service
stat:
path: "{{ matrix_systemd_path }}/matrix-etherpad.service"
register: matrix_etherpad_service_stat
- name: Ensure matrix-etherpad is stopped
service:
name: matrix-etherpad
state: stopped
daemon_reload: yes
register: stopping_result
when: "matrix_etherpad_service_stat.stat.exists|bool"
- name: Ensure matrix-etherpad.service doesn't exist
file:
path: "{{ matrix_systemd_path }}/matrix-etherpad.service"
state: absent
when: "matrix_etherpad_service_stat.stat.exists|bool"
- name: Ensure systemd reloaded after matrix-etherpad.service removal
service:
daemon_reload: yes
when: "matrix_etherpad_service_stat.stat.exists|bool"
- name: Ensure Etherpad base directory doesn't exist
file:
path: "{{ matrix_etherpad_base_path }}"
state: absent
- name: Ensure Etherpad Docker image doesn't exist
docker_image:
name: "{{ matrix_etherpad_docker_image }}"
state: absent

View File

@ -0,0 +1,5 @@
- name: Fail if Etherpad is enabled without the Dimension integrations manager
fail:
msg: >-
To integrate Etherpad notes with Matrix rooms you need to set "matrix_dimension_enabled" to true
when: "not matrix_dimension_enabled|bool"

View File

@ -0,0 +1,106 @@
{
"title": {{ matrix_etherpad_title|to_json }},
"favicon": "favicon.ico",
"skinName": "colibris",
"skinVariants": "super-light-toolbar super-light-editor light-background",
"ip": "::",
"port": 9001,
"showSettingsInAdminPage": true,
"dbType": {{ matrix_etherpad_database_engine|to_json }},
"dbSettings": {
{% if matrix_etherpad_database_engine == 'sqlite' %}
"filename": {{ matrix_etherpad_sqlite_database_path_in_container|to_json }}
{% elif matrix_etherpad_database_engine == 'postgres' %}
"database": {{ matrix_etherpad_database_name|to_json }},
"host": {{ matrix_etherpad_database_hostname|to_json }},
"password": {{ matrix_etherpad_database_password|to_json }},
"port": {{ matrix_etherpad_database_port|to_json }},
"user": {{ matrix_etherpad_database_username|to_json }}
{% endif %}
},
"defaultPadText" : {{ matrix_etherpad_default_pad_text|to_json }},
"suppressErrorsInPadText": false,
"requireSession": false,
"editOnly": false,
"minify": true,
"maxAge": 21600,
"abiword": null,
"soffice": null,
"tidyHtml": null,
"allowUnknownFileEnds": true,
"requireAuthentication": false,
"requireAuthorization": false,
"trustProxy": true,
"cookie": {
"sameSite": "Lax"
},
"disableIPlogging": true,
"automaticReconnectionTimeout": 0,
"scrollWhenFocusLineIsOutOfViewport": {
"percentage": {
"editionAboveViewport": 0,
"editionBelowViewport": 0
},
"duration": 0,
"scrollWhenCaretIsInTheLastLineOfViewport": false,
"percentageToScrollWhenUserPressesArrowUp": 0
},
"socketTransportProtocols" : ["xhr-polling", "jsonp-polling", "htmlfile"],
"loadTest": false,
"importExportRateLimiting": {
"windowMs": 90000,
"max": 10
},
"importMaxFileSize": 52428800,
"commitRateLimiting": {
"duration": 1,
"points": 10
},
"exposeVersion": false,
"padOptions": {
"noColors": false,
"showControls": true,
"showChat": false,
"showLineNumbers": true,
"useMonospaceFont": false,
"userName": false,
"userColor": false,
"rtl": false,
"alwaysShowChat": false,
"chatAndUsers": false,
"lang": "en-gb"
},
"padShortcutEnabled" : {
"altF9": true,
"altC": true,
"cmdShift2": true,
"delete": true,
"return": true,
"esc": true,
"cmdS": true,
"tab": true,
"cmdZ": true,
"cmdY": true,
"cmdI": true,
"cmdB": true,
"cmdU": true,
"cmd5": true,
"cmdShiftL": true,
"cmdShiftN": true,
"cmdShift1": true,
"cmdShiftC": true,
"cmdH": true,
"ctrlHome": true,
"pageUp": true,
"pageDown": true
},
"loglevel": "INFO",
"logconfig" :
{ "appenders": [
{ "type": "console",
"layout": {"type": "messagePassThrough"}
}
]
},
"customLocaleStrings": {}
}

View File

@ -0,0 +1,49 @@
#jinja2: lstrip_blocks: "True"
[Unit]
Description=Matrix Etherpad
{% for service in matrix_etherpad_systemd_required_services_list %}
Requires={{ service }}
After={{ service }}
{% endfor %}
{% for service in matrix_etherpad_systemd_wanted_services_list %}
Wants={{ service }}
{% endfor %}
DefaultDependencies=no
[Service]
Type=simple
Environment="HOME={{ matrix_systemd_unit_home_path }}"
ExecStartPre=-{{ matrix_host_command_docker }} kill matrix-etherpad
ExecStartPre=-{{ matrix_host_command_docker }} rm matrix-etherpad
# Fixup database ownership if it got changed somehow (during a server migration, etc.)
{% if matrix_etherpad_database_engine == 'sqlite' %}
ExecStartPre=-{{ matrix_host_command_chown }} {{ matrix_etherpad_user_uid }} {{ matrix_etherpad_sqlite_database_path_local }}
{% endif %}
ExecStart={{ matrix_host_command_docker }} run --rm --name matrix-etherpad \
--log-driver=none \
--user={{ matrix_etherpad_user_uid }}:{{ matrix_etherpad_user_gid }} \
--cap-drop=ALL \
--network={{ matrix_docker_network }} \
{% if matrix_etherpad_container_http_host_bind_port %}
-p {{ matrix_etherpad_container_http_host_bind_port }}:9001 \
{% endif %}
--mount type=bind,src={{ matrix_etherpad_base_path }},dst=/data \
{% for arg in matrix_etherpad_container_extra_arguments %}
{{ arg }} \
{% endfor %}
{{ matrix_etherpad_docker_image }} \
node --experimental-worker /opt/etherpad-lite/node_modules/ep_etherpad-lite/node/server.js \
--settings /data/settings.json --credentials /data/credentials.json \
--sessionkey /data/sessionkey.json --apikey /data/apijey.json
ExecStop=-{{ matrix_host_command_docker }} kill matrix-etherpad
ExecStop=-{{ matrix_host_command_docker }} rm matrix-etherpad
Restart=always
RestartSec=30
SyslogIdentifier=matrix-etherpad
[Install]
WantedBy=multi-user.target

View File

@ -67,6 +67,9 @@ matrix_jitsi_web_public_url: "https://{{ matrix_server_fqn_jitsi }}"
# Addresses need to be prefixed with one of `stun:`, `turn:` or `turns:`.
matrix_jitsi_web_stun_servers: ['stun:meet-jit-si-turnrelay.jitsi.net:443']
# Controls whether Etherpad will be available within Jitsi
matrix_jitsi_etherpad_enabled: false
# Controls whether the matrix-jitsi-web container exposes its HTTP port (tcp/80 in the container).
#
# Takes an "<ip>:<port>" or "<port>" value (e.g. "127.0.0.1:12080"), or empty string to not expose.

View File

@ -11,5 +11,8 @@ config.p2p.stunServers = [
];
{% endif %}
{% if matrix_jitsi_etherpad_enabled %}
config.etherpad_base = {{ (matrix_jitsi_etherpad_base + '/p/') |to_json }}
{% endif %}
{{ matrix_jitsi_web_custom_config_extension }}

View File

@ -37,4 +37,6 @@ RESOLUTION_WIDTH_MIN={{ matrix_jitsi_web_config_resolution_width_min }}
START_AUDIO_MUTED={{ matrix_jitsi_web_config_start_audio_muted_after_nth_participant }}
START_VIDEO_MUTED={{ matrix_jitsi_web_config_start_video_muted_after_nth_participant }}
ETHERPAD_URL_BASE={{ (matrix_jitsi_etherpad_base + '/') if matrix_jitsi_etherpad_enabled else ''}}
{{ matrix_jitsi_web_environment_variables_extension }}

View File

@ -45,6 +45,11 @@ http {
keepalive_timeout 65;
#gzip on;
{# Map directive needed for proxied WebSocket upgrades #}
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
include /etc/nginx/conf.d/*.conf;
}

View File

@ -33,6 +33,7 @@
- matrix-jitsi
- matrix-ma1sd
- matrix-dimension
- matrix-etherpad
- matrix-email2matrix
- matrix-nginx-proxy
- matrix-coturn