Skip to content

Update etherpad setup #50

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
dyedwiper merged 10 commits into from
Mar 3, 2025
Merged

Update etherpad setup #50

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
ae3c580
Add AUTHENTICATION_METHOD to settings.env
dyedwiper Feb 19, 2025
1e3b670
Change port binding
dyedwiper Feb 19, 2025
088d338
Update link to dof_app_deploy
dyedwiper Feb 19, 2025
4f11df9
Update etherpad version
dyedwiper Feb 19, 2025
ede7bbb
Add instructions on host resolution and port mapping
dyedwiper Feb 19, 2025
9bc8fc4
Add config values to local setup
dyedwiper Feb 19, 2025
acd4e35
Fix typo
dyedwiper Feb 19, 2025
3756585
Fix some language and formatting
dyedwiper Feb 20, 2025
1ad8c9f
Add more info on config values
dyedwiper Feb 20, 2025
1ccbd96
Merge branch 'main' into update-etherpad-setup
dyedwiper Mar 3, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/services/etherpad/How it works.md
View file
Open in desktop
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
Open in desktop
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.