From 2ea415bc85a676f8c38ac842dc1910cd74cee2c2 Mon Sep 17 00:00:00 2001
From: Pascal Bleser <p.bleser@opencloud.eu>
Date: Thu, 11 Sep 2025 11:23:21 +0200
Subject: [PATCH] docs(groupware): add configuration instructions to
 DEVELOPER.md

---
 services/groupware/DEVELOPER.md | 91 ++++++++++++++++++++++++++++++---
 1 file changed, 84 insertions(+), 7 deletions(-)

diff --git a/services/groupware/DEVELOPER.md b/services/groupware/DEVELOPER.md
index 5774f7066..d91c72b29 100644
--- a/services/groupware/DEVELOPER.md
+++ b/services/groupware/DEVELOPER.md
@@ -29,6 +29,60 @@ echo 'export PATH="$PATH:$HOME/src/opencloud/bin"' >> ~/.bashrc
 
 # Running
 
+Since we require having a Stalwart container running at the very least, the preferred way of running OpenCloud and its adjacent services for developing the Groupware component is by using the `opencloud_full` Docker Compose setup.
+
+## Configuration
+
+### Compose
+
+It first needs to be tuned a little, and for that, edit `deployments/examples/opencloud_full/.env`, making the following changes:
+
+* add the `groupware` service to `START_ADDITIONAL_SERVICES`:
+```diff
+-START_ADDITIONAL_SERVICES="notifications"
++START_ADDITIONAL_SERVICES="notifications,groupware"
+```
+
+* enable the OpenLDAP container:
+```diff
+-#LDAP=:ldap.yml
++LDAP=:ldap.yml
+```
+
+* enable the Keycloak container:
+```diff
+-#KEYCLOAK=:keycloak.yml
++KEYCLOAK=:keycloak.yml
+```
+
+* enable the Stalwart container:
+```diff
+-#STALWART=:stalwart.yml
++STALWART=:stalwart.yml
+```
+
+* optionally disable the Collabora container
+```diff
+-COLLABORA=:collabora.yml
++#COLLABORA=:collabora.yml
+```
+
+* optionally disable UI containers
+```diff
+-UNZIP=:web_extensions/unzip.yml
+-DRAWIO=:web_extensions/drawio.yml
+-JSONVIEWER=:web_extensions/jsonviewer.yml
+-PROGRESSBARS=:web_extensions/progressbars.yml
+-EXTERNALSITES=:web_extensions/externalsites.yml
++#UNZIP=:web_extensions/unzip.yml
++#DRAWIO=:web_extensions/drawio.yml
++#JSONVIEWER=:web_extensions/jsonviewer.yml
++#PROGRESSBARS=:web_extensions/progressbars.yml
++#EXTERNALSITES=:web_extensions/externalsites.yml
+```
+
+## Running
+
 Either run everything from the Docker Compose `opencloud_full` setup:
 
 
@@ -46,25 +100,48 @@ docker stop opencloud_full-opencloud-1
 
 and then use the Launcher `OpenCloud server with external services` in VSCode.
 
-To do the latter on a more permanent basis, comment the following line in `deployments/examples/opencloud_full/.env`:
+## Keycloak Configuration
 
+Now that Keycloak is running, we also need to add a new `groupware` client to the Keycloak `OpenCloud` realm in order to be able to use our command-line scripts and other test components.
 
-```yaml
-#OPENCLOUD=:opencloud.yml
+To do so, use your preferred web browser and
+* head over to <https://keycloak.opencloud.test/>
+* authenticate as `admin` with password `admin` (those credentials are defined in the `.env` file mentioned above, see `KEYCLOAK_ADMIN_USER` and `KEYCLOAK_ADMIN_PASSWORD`)
+* select the `OpenCloud` realm in the drop-down list in the top left corner (the realm is defined in the `.env` file, see `KEYCLOAK_REALM`)
+* then select the "Clients" menu item on the left
+* in the "Clients list" tab, push the "Create client" button:
+  * Client type: `OpenID Connect`
+  * Client ID: `groupware`
+* click the "Next" button:
+  * Client authentication: Off
+  * Authorization: Off
+  * Authentication flow: make sure "Direct access grants" is checked
+* click the "Next" button and leave the fields there empty to stick to the defaults
+* click "Save"
+
+To check whether it works correctly:
+```sh
+curl -ks -D- -X POST "https://keycloak.opencloud.test/realms/openCloud/protocol/openid-connect/token" -d username=alan -d password=demo -d grant_type=password -d client_id=groupware -d scope=openid
+```
+should provide you with a JSON response that contains an `access_token`.
+
+If it is not set up correctly, it should give you this instead:
+```json
+{"error":"invalid_client","error_description":"Invalid client or Invalid client credentials"}
 ```
 
 ## Feeding an Inbox
 
-Once a Stalwart container is running (using the Docker Compose setup as explained above), use [`imap-filler`](https://github.com/opencloud-eu/imap-filler/):
-
+Once a [Stalwart](https://stalw.art/) container is running (using the Docker Compose setup as explained above), use [`imap-filler`](https://github.com/opencloud-eu/imap-filler/) to populate the inbox folder via IMAP APPEND:
 
 ```bash
 cd ~/src/opencloud/
 git clone git@github.com:opencloud-eu/imap-filler.git
 cd ./imap-filler
-EMPTY=true SENDERS=3 \
+EMPTY=true \
 USERNAME=alan PASSWORD=demo \
-URL=localhost:993 FOLDER=Inbox COUNT=20 \
+URL=localhost:993 FOLDER=Inbox \
+SENDERS=3 COUNT=20 \
 go run .
 ```