:title: Etherpad

.. _etherpad:

Etherpad
########

Etherpad (previously known as "etherpad-lite") is installed on
etherpad.opendev.org to facilitate real-time collaboration on
documents.  It is used extensively during OpenStack Developer
Summits.

At a Glance
===========

:Hosts:
  * https://etherpad.opendev.org
:Ansible:
  * https://opendev.org/opendev/system-config
  * :git_file:`playbooks/roles/etherpad`
  * :git_file:`playbooks/service-etherpad.yaml`
  * :git_file:`inventory/service/group_vars/etherpad.yaml`
:Projects:
  * https://etherpad.org/
  * https://github.com/ether/etherpad-lite
:Bugs:
  * https://storyboard.openstack.org/#!/project/748
  * https://github.com/ether/etherpad-lite/issues

Overview
========

Apache is configured as a reverse proxy and there is a MySQL database
backend.

Manual Administrative Tasks
===========================

The following sections describe tasks that individuals with root
access may need to perform on rare occasions.

All interaction with the Etherpad admin API requires retrieving a bearer
token for authorization and authentication to the API. The secret used
to authenticate when requesting a token is found in the Etherpad
settings.json file under the ``client_secret`` key::

  grep '"client_secret":' /etc/etherpad/settings.json | \
    sed -e 's/\s\+"client_secret": "\(.*\)",/\1/'

With this secret we can make a request to get a token::

  curl --data grant_type=client_credentials \
       --data client_id=api_admin \
       --data client_secret="SECRETHERE" \
       http://localhost:9001/oidc/token

This will return a Bearer token that is valid for one hour. You will need
this token to perform the actions described below.

Deleting a Pad
--------------

On occasion it may be necessary to delete a pad, so as to redact
sensitive or illegal data posted to it (the revision history it keeps
makes this harder than just clearing the current contents through a
browser). This is fairly easily accomplished via the `HTTP API`_::

  curl -H "Authorization: Bearer TOKENFROMABOVEPROCESS" \
    "http://localhost:9001/api/1/deletePad?padID=XXXXXXXXXX" ; echo

...where XXXXXXXXXX is the pad's name as it appears at the end of its
URL (the trailing echo is just because the API response doesn't end with
a newline and so your next appended shell prompt makes it harder to
read). If all goes well, you should receive a response like::

  {"code":0,"message":"ok","data":null}

Browse to the original pad's URL and you should now see the fresh
welcome message boilerplate for a new pad. Check the pad's history and
note that it has no authors and no prior revisions.

.. _HTTP API: https://github.com/ether/etherpad-lite/wiki/HTTP-API

Restoring a Pad
---------------

It also happens that the content of a pad gets overwritten with the
wrong content, one common example is someone using a translation tool
on it, not being aware that this changes the document for everyone
instead of just locally. Via the revision slider you can identify the
last good version and then restore it via the API::

  curl -H "Authorization: Bearer TOKENFROMABOVEPROCESS" \
    "http://localhost:9001/api/1.2.11/restoreRevision?padID=XXXXXXXXXX&rev=NNN" \
    ; echo