b2607979ab
This updates changes how Etherpad is built and how authentication is managed for API requests. This ends up changing a lot of our tooling around etherpad but etherpad itself (other than the auth changes) doesn't seem to change much. In response to this I update our admin docs on common api tasks to use the new process. Then update our testinfra testing as well to cover that to ensure it all continues to work properly after this change. Note the Dockerfile updates are all adapted from upstream. I'm actually not fond of the decisions they have made in this image build, but being in sync is probably more important than fixing the multistage builds and being different. This change jumps us from v1.9.7 to 2.0.3 (covers releases 2.0.0, 2.0.1, and 2.0.2 too). A changelog can be found here: https://github.com/ether/etherpad-lite/blob/v2.0.3/CHANGELOG.md Change-Id: Ia7c4f26d893b4fc4a178262e1a6b9f3fa80d2a5c
96 lines
3.1 KiB
ReStructuredText
96 lines
3.1 KiB
ReStructuredText
: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
|