Skip to content

Commit

Permalink
Update etherpad setup documentation (#50)
Browse files Browse the repository at this point in the history
  • Loading branch information
@dyedwiper
dyedwiper authored Mar 3, 2025
1 parent 00ae7fe commit 1e24e3d
Show file tree
Hide file tree
Showing 2 changed files with 108 additions and 85 deletions.
2 changes: 1 addition & 1 deletion docs/services/etherpad/How it works.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@
- ETHERPAD__URI - Uri of etherpad api for all calls like create, delete etc. Used as base path for api client in nest and feathers backend.

- ETHERPAD__PAD_URI - URI to etherpad client api. Used in backend in collaborative text editor and lesson to build return url. Used in legacy client to build url.
- ETHERPAD_OLD_PAD_URI - Used in feathers backend to restrict access to old etherpad urls to lesson context. Only defined in default.schema.json and not in dof-app-deploy
- ETHERPAD__OLD_PAD_URI - Used in feathers backend to restrict access to old etherpad urls to lesson context. Only defined in default.schema.json and not in dof-app-deploy
- ETHERPAD__PAD_PATH - Path to etherpad client api. Used in legacy client to set path on cookie.

- ETHERPAD__NEW_DOMAIN - Etherpad Domain. Used in legacy client to validate url
Expand Down
191 changes: 107 additions & 84 deletions docs/services/etherpad/Local setup.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,13 +9,13 @@ Create a directory called sc-etherpad and then enter it, in Unix-like systems y

`mkdir sc-etherpad && cd sc-etherpad`

2. Create a new file called APIKEY.txt in it, with the following content:
2. Create a new file called `APIKEY.txt` in it, with the following content:

`381d67e6347d235ac9446da3ea10a82efd6f8ae09fa2e90efeda80f82feeb4fd`

We'll use this file to set a fixed Etherpad's API key on the Etherpad server's start.

3. Create also a file called settings.env with the following content:
3. Create also a file called `settings.env` with the following content:

```
REQUIRE_SESSION="true"
Expand All @@ -24,99 +24,122 @@ Create a directory called sc-etherpad and then enter it, in Unix-like systems y
DEFAULT_PAD_TEXT="Schreib etwas!\n\nDieses Etherpad wird synchronisiert, während du tippst, so dass alle Betrachter jederzeit den selben Text sehen. So könnt ihr auf einfache Weise gemeinsam an Dokumenten arbeiten."
DB_TYPE=mongodb
DB_URL=mongodb://host.docker.internal:27017/etherpad
AUTHENTICATION_METHOD=apikey
```
We'll use this file to provide all the needed environment variables to the Etherpad's server.
Please note the last line, that contains the MongoDB connection string:
Please note the line that contains the MongoDB connection string:
`DB_URL=mongodb://host.docker.internal:27017/etherpad`
Here we're using the host.docker.internal hostname which should make it possible for the Etherpad's container to connect to the host's local network and should work out of the box e.g. on macOS. But please modify it accordingly to your needs and your Docker's network configuration. An alternative configuaration would be to use `DB_URL=mongodb://localhost:27017/etherpad` and than add `--network="host"` to the following docker run command.
Here we're using the `host.docker.internal` hostname which should make it possible for the Etherpad's container to connect to the host's local network and should work out of the box e.g. on macOS. On WSL2 it might not work out of the box and need some extra work, see e.g. this [stackoverflow thread](https://stackoverflow.com/questions/63898430/how-can-i-access-a-service-running-on-wsl2-from-inside-a-docker-container).
An alternative configuaration would be to use `DB_URL=mongodb://localhost:27017/etherpad` and then add `--network="host"` to the following docker run command. `--network="host"` removes the port mapping though. You can change the port Etherpad is listening on by adding `PORT=9002` (or the port number you need) to settings.env.
4. Next, start the Etherpad's container:
```
docker run -d \
-p 9001:9001 \
-p 9002:9001 \
--env-file ./settings.env \
-v ./APIKEY.txt:/opt/etherpad-lite/APIKEY.txt \
--name sc-etherpad \
docker.io/etherpad/etherpad:2.0.0
docker.io/etherpad/etherpad:2.2.7
```
Please note we're using the docker.io/etherpad/etherpad:2.0.0 image in the command above which might be not the one that is being used anytime in the future when you read this article. To make sure you're using the current version (the one that is currently being used in the SchulCloud platform), please refer to the https://github.com/hpi-schul-cloud/dof_app_deploy/blob/main/ansible/group_vars/infra/dof_etherpad.yml file.
Now we should have the Etherpad service running locally on port 9001, we can verify it's working properly e.g. by fetching the current Etherpad's API version:
```
~ curl -v http://127.0.0.1:9001/api
* Trying 127.0.0.1:9001...
* Connected to 127.0.0.1 (127.0.0.1) port 9001
> GET /api HTTP/1.1
> Host: 127.0.0.1:9001
> User-Agent: curl/8.4.0
> Accept: */*
>
< HTTP/1.1 200 OK
< X-Powered-By: Express
< X-UA-Compatible: IE=Edge,chrome=1
< Referrer-Policy: same-origin
< Content-Type: application/json; charset=utf-8
< Content-Length: 26
< ETag: W/"1a-2HmNLqF3wPt+KQRlEmGwH4O+xu4"
< Date: Fri, 29 Mar 2024 13:27:00 GMT
< Connection: keep-alive
< Keep-Alive: timeout=5
<
* Connection #0 to host 127.0.0.1 left intact
{"currentVersion":"1.3.0"}
```
We can also verify that the API key has been set successfully, let's use the example API call from the Etherpad's documentation ( https://etherpad.org/doc/v2.0.0/#_example_1 ):
```
~ curl -v http://127.0.0.1:9001/api/1/createAuthorIfNotExistsFor\?apikey\=381d67e6347d235ac9446da3ea10a82efd6f8ae09fa2e90efeda80f82feeb4fd\&name\=Michael\&authorMapper\=7
* Trying 127.0.0.1:9001...
* Connected to 127.0.0.1 (127.0.0.1) port 9001
> GET /api/1/createAuthorIfNotExistsFor?apikey=381d67e6347d235ac9446da3ea10a82efd6f8ae09fa2e90efeda80f82feeb4fd&name=Michael&authorMapper=7 HTTP/1.1
> Host: 127.0.0.1:9001
> User-Agent: curl/8.4.0
> Accept: */*
>
< HTTP/1.1 200 OK
< X-Powered-By: Express
< X-UA-Compatible: IE=Edge,chrome=1
< Referrer-Policy: same-origin
< Content-Type: application/json; charset=utf-8
< Content-Length: 66
< ETag: W/"42-bg92QA1xRFO6QmkNRbNXhfsFBUM"
< Date: Fri, 29 Mar 2024 13:40:05 GMT
< Connection: keep-alive
< Keep-Alive: timeout=5
<
* Connection #0 to host 127.0.0.1 left intact
{"code":0,"message":"ok","data":{"authorID":"a.7BgkAuzbHXR1G8Cv"}}
```
In case of an unsuccessful result (e.g. improperly set or invalid API key) we would receive the following response:
```
~ curl -v http://127.0.0.1:9001/api/1/createAuthorIfNotExistsFor\?apikey\=secret\&name\=Michael\&authorMapper\=7
* Trying 127.0.0.1:9001...
* Connected to 127.0.0.1 (127.0.0.1) port 9001
> GET /api/1/createAuthorIfNotExistsFor?apikey=secret&name=Michael&authorMapper=7 HTTP/1.1
> Host: 127.0.0.1:9001
> User-Agent: curl/8.4.0
> Accept: */*
>
< HTTP/1.1 401 Unauthorized
< X-Powered-By: Express
< X-UA-Compatible: IE=Edge,chrome=1
< Referrer-Policy: same-origin
< Content-Type: application/json; charset=utf-8
< Content-Length: 54
< ETag: W/"36-dbJd0O+vdNi3zPpwRXE+1EGLTho"
< Date: Fri, 29 Mar 2024 13:39:44 GMT
< Connection: keep-alive
< Keep-Alive: timeout=5
<
* Connection #0 to host 127.0.0.1 left intact
{"code":4,"message":"no or wrong API Key","data":null}
```
We're using the docker.io/etherpad/etherpad:2.2.7 image in the command above. To make sure you're using the version that is currently used in the SchulCloud platform, please refer to https://github.com/hpi-schul-cloud/dof_app_deploy/blob/main/ansible/roles/dof_etherpad/defaults/main.yml.
The bound port on the host (here 9002) is arbitrary, though port 9001 is used by MinIO in our default project setup and thus we use a different one here.
5. Now we should have the Etherpad service running locally on port 9002, we can verify it's working properly e.g. by fetching the current Etherpad's API version:
```
~ curl -v http://127.0.0.1:9002/api
* Trying 127.0.0.1:9002...
* Connected to 127.0.0.1 (127.0.0.1) port 9002
> GET /api HTTP/1.1
> Host: 127.0.0.1:9002
> User-Agent: curl/8.4.0
> Accept: */*
>
< HTTP/1.1 200 OK
< X-Powered-By: Express
< X-UA-Compatible: IE=Edge,chrome=1
< Referrer-Policy: same-origin
< Content-Type: application/json; charset=utf-8
< Content-Length: 26
< ETag: W/"1a-2HmNLqF3wPt+KQRlEmGwH4O+xu4"
< Date: Fri, 29 Mar 2024 13:27:00 GMT
< Connection: keep-alive
< Keep-Alive: timeout=5
<
* Connection #0 to host 127.0.0.1 left intact
{"currentVersion":"1.3.0"}
```
We can also verify that the API key has been set successfully, let's use the example API call from the Etherpad's documentation ( https://etherpad.org/doc/v2.2.7/#_example_1 ):
```
~ curl -v http://127.0.0.1:9002/api/1/createAuthorIfNotExistsFor\?apikey\=381d67e6347d235ac9446da3ea10a82efd6f8ae09fa2e90efeda80f82feeb4fd\&name\=Michael\&authorMapper\=7
* Trying 127.0.0.1:9002...
* Connected to 127.0.0.1 (127.0.0.1) port 9002
> GET /api/1/createAuthorIfNotExistsFor?apikey=381d67e6347d235ac9446da3ea10a82efd6f8ae09fa2e90efeda80f82feeb4fd&name=Michael&authorMapper=7 HTTP/1.1
> Host: 127.0.0.1:9002
> User-Agent: curl/8.4.0
> Accept: */*
>
< HTTP/1.1 200 OK
< X-Powered-By: Express
< X-UA-Compatible: IE=Edge,chrome=1
< Referrer-Policy: same-origin
< Content-Type: application/json; charset=utf-8
< Content-Length: 66
< ETag: W/"42-bg92QA1xRFO6QmkNRbNXhfsFBUM"
< Date: Fri, 29 Mar 2024 13:40:05 GMT
< Connection: keep-alive
< Keep-Alive: timeout=5
<
* Connection #0 to host 127.0.0.1 left intact
{"code":0,"message":"ok","data":{"authorID":"a.7BgkAuzbHXR1G8Cv"}}
```
In case of an unsuccessful result (e.g. improperly set or invalid API key) we would receive the following response:
```
~ curl -v http://127.0.0.1:9002/api/1/createAuthorIfNotExistsFor\?apikey\=secret\&name\=Michael\&authorMapper\=7
* Trying 127.0.0.1:9002...
* Connected to 127.0.0.1 (127.0.0.1) port 9002
> GET /api/1/createAuthorIfNotExistsFor?apikey=secret&name=Michael&authorMapper=7 HTTP/1.1
> Host: 127.0.0.1:9002
> User-Agent: curl/8.4.0
> Accept: */*
>
< HTTP/1.1 401 Unauthorized
< X-Powered-By: Express
< X-UA-Compatible: IE=Edge,chrome=1
< Referrer-Policy: same-origin
< Content-Type: application/json; charset=utf-8
< Content-Length: 54
< ETag: W/"36-dbJd0O+vdNi3zPpwRXE+1EGLTho"
< Date: Fri, 29 Mar 2024 13:39:44 GMT
< Connection: keep-alive
< Keep-Alive: timeout=5
<
* Connection #0 to host 127.0.0.1 left intact
{"code":4,"message":"no or wrong API Key","data":null}
```
6. Set the following config values in the server:
| Key | Value |
| --- | --- |
| ETHERPAD__API_KEY | 381d67e6347d235ac9446da3ea10a82efd6f8ae09fa2e90efeda80f82feeb4fd |
| ETHERPAD__URI | http://localhost:9002/api/1 |
| ETHERPAD__PAD_URI | http://localhost:9002/p |
Set the following config values in the client:
| Key | Value |
| --- | --- |
| ETHERPAD__PAD_URI | http://localhost:9002/p |
| ETHERPAD__PAD_PATH | /p |
| ETHERPAD__NEW_DOMAIN | localhost |
For the other config values the defaults in `default.schema.json` should work.
7. Now you should be able to create and use Etherpads in boards and topics.

0 comments on commit 1e24e3d

Please sign in to comment.