From 0ca707bc61ad690ccd9fc2980e7d8037b10b4607 Mon Sep 17 00:00:00 2001 From: Heiko Pohl Date: Wed, 28 Oct 2026 15:18:18 +0100 Subject: [PATCH 1/3] Add guest feature in admin doku --- docs/admin/configuration/guest-feature.md | 253 ++++++++++++++++++++++ docs/admin/configuration/index.md | 1 + 2 files changed, 254 insertions(+) create mode 100644 docs/admin/configuration/guest-feature.md diff --git a/docs/admin/configuration/guest-feature.md b/docs/admin/configuration/guest-feature.md new file mode 100644 index 00000000..5e61273d --- /dev/null +++ b/docs/admin/configuration/guest-feature.md @@ -0,0 +1,253 @@ +--- +sidebar_position: 160 +id: guest-feature +title: Guest-Feature +description: Set up guest-feature in OpenCloud +draft: false +--- + +# Set Up the Guest Feature + +The Guest Feature allows users to share files and folders with external people by email address. The invited guest receives an email with a personal link and can access the shared content in the web browser without an OpenCloud account. + +This guide explains how to enable the Guest Feature in a deployment based on the `opencloud-compose` deployment example. + +:::note +The Guest Feature is disabled by default. It requires OpenCloud version 9.0.0 or later and a working email configuration. +::: + +## How the Guest Feature Works + +The Guest Feature is provided by the `auth-guest` service. + +- When a user shares a file or folder with an external email address, the `auth-guest` service creates a one-time invitation link. +- The `notifications` service sends the invitation link to the guest by email. +- When the guest opens the link, OpenCloud verifies it and creates a guest session in the browser. +- The guest can access only the shared file or folder, with the permissions assigned by the sharing user. + +| Setting | Default | +| ------------------------------- | ----------------------------------------- | +| Validity of the invitation link | 30 minutes, single use (not configurable) | +| Lifetime of a guest session | 24 hours (`AUTH_GUEST_JWT_TTL`) | + +## Prerequisites + +- A running OpenCloud deployment based on `opencloud-compose`. +- OpenCloud version 9.0.0 or later. +- Access to an SMTP mailbox that OpenCloud can use to send emails. + +All commands in this guide are run in the root directory of the `opencloud-compose` deployment. + +## Check the OpenCloud Version + +Check whether your OpenCloud image contains the `auth-guest` service: + +```bash +docker compose exec opencloud opencloud help | grep -i guest +``` + +If the output shows `auth-guest`, continue with the next step. + +If there is no output, update OpenCloud. Set the image tag in your `.env` file, for example: + +```env +OC_DOCKER_TAG=9.0.0 +``` + +Then update the deployment: + +```bash +docker compose pull opencloud +docker compose up -d +``` + +:::caution +Create a backup before you update OpenCloud. +::: + +## Get the Service Account Credentials + +The `auth-guest` service uses the OpenCloud service account. Without it, the service does not start. + +Read the service account credentials from your existing OpenCloud configuration: + +```bash +docker compose exec opencloud cat /etc/opencloud/opencloud.yaml | grep -m1 -A2 "service_account:" +``` + +The output looks similar to this: + +```yaml +service_account: + service_account_id: 1234abcd-... + service_account_secret: ... +``` + +You need both values in the next step. + +:::important +Treat the service account secret like a password. Do not share it. +::: + +## Enable the Guest Feature + +The Guest Feature settings must be passed to the OpenCloud container. Adding the variables to the `.env` file alone is not sufficient, because the `opencloud-compose` files do not forward them to the container. + +Use a separate Compose file for the Guest Feature instead. + +### Create the Compose File + +Create the folder `custom` and the file `custom/guest.yml`: + +```bash +mkdir -p custom +nano custom/guest.yml +``` + +Add the following content and replace the placeholders with the values from the previous step: + +```yaml +services: + opencloud: + environment: + OC_ENABLE_GUEST_LINKS: 'true' + AUTH_GUEST_SERVICE_ACCOUNT_ID: 'YOUR-SERVICE-ACCOUNT-ID' + AUTH_GUEST_SERVICE_ACCOUNT_SECRET: 'YOUR-SERVICE-ACCOUNT-SECRET' +``` + +:::caution +Docker Compose interprets the `$` character as the start of a variable. If the secret contains a `$`, write it as `$$`. Otherwise Docker Compose shows a warning such as `The "XY" variable is not set` and passes an incorrect secret to the container. +::: + +### Add the File to `COMPOSE_FILE` + +Add `custom/guest.yml` to the end of the `COMPOSE_FILE` variable in your `.env` file, for example: + +```env +COMPOSE_FILE=docker-compose.yml:weboffice/collabora.yml:traefik/opencloud.yml:traefik/collabora.yml:radicale/radicale.yml:custom/guest.yml +``` + +:::note +Make sure that the `.env` file contains only one active `COMPOSE_FILE` line. If there are several lines, only the last one is used. +::: + +## Configure Email Delivery + +Guests receive their invitation link by email. Configure the SMTP settings and enable the `notifications` service in your `.env` file: + +```env +SMTP_HOST=smtp.example.com +SMTP_PORT=587 +SMTP_SENDER=OpenCloud +SMTP_USERNAME=noreply@example.com +SMTP_PASSWORD=YOUR-PASSWORD +SMTP_TRANSPORT_ENCRYPTION=starttls +SMTP_INSECURE=false +SMTP_AUTHENTICATION=auto +START_ADDITIONAL_SERVICES=notifications +``` + +- `SMTP_SENDER` must usually match the mailbox that sends the email. Otherwise the mail server may reject the message. +- If `START_ADDITIONAL_SERVICES` already contains other services, add `notifications` separated by a comma. +- Use port `587` with `starttls` or port `465` with `ssltls`, depending on your mail provider. + +For more information, see [Mail Notifications](./mail-notifications.md). + +:::tip +Some hosting providers block outgoing connections on port `465`. If emails are not sent, check which port is reachable from your server: + +```bash +nc -vz -w 5 smtp.example.com 465 +nc -vz -w 5 smtp.example.com 587 +``` + +::: + +## Restart OpenCloud + +Apply the changes: + +```bash +docker compose up -d +``` + +## Verify the Configuration + +Check that the OpenCloud container is running: + +```bash +docker compose ps opencloud +``` + +The status must be `Up`. If the status is `Restarting`, see [Troubleshooting](#troubleshooting). + +Check that the Guest Feature is enabled: + +```bash +docker compose exec opencloud env | grep GUEST +``` + +The output must contain `OC_ENABLE_GUEST_LINKS=true`. + +Check that the email settings are active: + +```bash +docker compose exec opencloud env | grep -E "SMTP_HOST|ADD_RUN_SERVICES" +``` + +The output must contain your SMTP server and `notifications`. + +Finally, test the Guest Feature in the web interface: share a folder with an external email address, select the entry marked **(Guest)**, and click **Share**. The guest should receive an invitation email. + +## Optional Settings + +You can adjust the behavior of the Guest Feature with additional environment variables in `custom/guest.yml`. + +| Variable | Default | Description | +| --------------------------------- | ------- | ------------------------------------------------------------------------------------- | +| `AUTH_GUEST_JWT_TTL` | `24h` | Lifetime of a guest session. | +| `AUTH_GUEST_PIN_AND_NONCE_TTL` | `30m` | Lifetime of the one-time PIN used to renew guest access. | +| `AUTH_GUEST_BACKOFF_MAX_ATTEMPTS` | `5` | Number of failed PIN attempts before the PIN is invalidated. | +| `AUTH_GUEST_QUOTA_COOLDOWN` | `1m` | Minimum time between two renewals without a valid session for the same share. | +| `AUTH_GUEST_QUOTA_DAILY_CAP` | `50` | Maximum number of renewals without a valid session per share within the quota window. | + +For a complete list of settings, see the [auth-guest environment variables](../../dev/server/services/auth-guest/env-vars.mdx) in the developer documentation. + +## Troubleshooting + +### The OpenCloud Container Keeps Restarting + +Check the logs: + +```bash +docker compose logs --tail=40 opencloud +``` + +If the log contains `guestlinks: service_account_id must not be empty`, the service account credentials are missing. Add `AUTH_GUEST_SERVICE_ACCOUNT_ID` and `AUTH_GUEST_SERVICE_ACCOUNT_SECRET` to `custom/guest.yml` as described in [Enable the Guest Feature](#enable-the-guest-feature). + +### Sharing with a Guest Fails + +If users see the message `Failed to add share` when they share with a guest: + +- Check that the OpenCloud image contains the `auth-guest` service, see [Check the OpenCloud Version](#check-the-opencloud-version). +- Check that `OC_ENABLE_GUEST_LINKS=true` is set inside the container: + + ```bash + docker compose exec opencloud env | grep GUEST + ``` + + If there is no output, the variable is not passed to the container. Make sure that `custom/guest.yml` is part of `COMPOSE_FILE`. + +### Guests Do Not Receive an Email + +Check the log of the `notifications` service: + +```bash +docker compose logs opencloud | grep '"service":"notifications"' | tail -10 +``` + +- **No output:** The `notifications` service is not running. Set `START_ADDITIONAL_SERVICES=notifications` in your `.env` file. +- **`SMTP Connection timed out`:** OpenCloud cannot reach the mail server. Your hosting provider may block the configured port. Use port `587` with `starttls` instead of port `465`. +- **Authentication errors:** Check `SMTP_USERNAME`, `SMTP_PASSWORD`, and `SMTP_SENDER`. + +Invitations created while email delivery was not working are not sent again. Remove the guest share and invite the guest again. diff --git a/docs/admin/configuration/index.md b/docs/admin/configuration/index.md index 5278456d..1cfd074b 100644 --- a/docs/admin/configuration/index.md +++ b/docs/admin/configuration/index.md @@ -26,4 +26,5 @@ Use these guides to tune OpenCloud behavior, integrations, and default settings. - [Logging](./logging.md) - Configure logging in OpenCloud - [n8n](./n8n.md) - Automate OpenCloud workflows with n8n - [Announcement Banner](./announcement-banner.md) - Notify all users with a global banner +- [Guest Feature](./guest-feature.md) - Allow users to share with external guests by email address - [Open Cloud Mesh (OCM)](./ocm.md) - Configure OCM federation between OpenCloud and trusted OCM-compatible systems From 065fa9b6f9c13a75319507b2d2dd7ed13b210cf2 Mon Sep 17 00:00:00 2001 From: Anja Barz Date: Thu, 29 Oct 2026 08:35:10 +0100 Subject: [PATCH 2/3] remove the upgrade and smtp part, because we have this already documented and linked to it --- docs/admin/configuration/guest-feature.md | 100 ++++++---------------- 1 file changed, 27 insertions(+), 73 deletions(-) diff --git a/docs/admin/configuration/guest-feature.md b/docs/admin/configuration/guest-feature.md index 5e61273d..9d06c284 100644 --- a/docs/admin/configuration/guest-feature.md +++ b/docs/admin/configuration/guest-feature.md @@ -1,8 +1,8 @@ --- sidebar_position: 160 id: guest-feature -title: Guest-Feature -description: Set up guest-feature in OpenCloud +title: Guest Feature +description: Set up the Guest Feature in OpenCloud draft: false --- @@ -34,36 +34,17 @@ The Guest Feature is provided by the `auth-guest` service. - A running OpenCloud deployment based on `opencloud-compose`. - OpenCloud version 9.0.0 or later. -- Access to an SMTP mailbox that OpenCloud can use to send emails. +- A working SMTP configuration for sending invitation emails. -All commands in this guide are run in the root directory of the `opencloud-compose` deployment. - -## Check the OpenCloud Version - -Check whether your OpenCloud image contains the `auth-guest` service: +If you are running an older OpenCloud version, follow the [Standard Upgrade Guide](../maintenance/upgrade/upgrade-guide.md) before enabling the Guest Feature. -```bash -docker compose exec opencloud opencloud help | grep -i guest -``` - -If the output shows `auth-guest`, continue with the next step. - -If there is no output, update OpenCloud. Set the image tag in your `.env` file, for example: - -```env -OC_DOCKER_TAG=9.0.0 -``` - -Then update the deployment: +:::important +Before upgrading, check whether a version-specific upgrade guide is available for your target version. These guides may contain additional migration steps, configuration changes, or breaking changes that must be considered. +::: -```bash -docker compose pull opencloud -docker compose up -d -``` +To configure email delivery, follow the [Mail Notifications](./mail-notifications.md) guide. Make sure that the `notifications` service is enabled. -:::caution -Create a backup before you update OpenCloud. -::: +All commands in this guide are run in the root directory of the `opencloud-compose` deployment. ## Get the Service Account Credentials @@ -121,48 +102,18 @@ Docker Compose interprets the `$` character as the start of a variable. If the s ### Add the File to `COMPOSE_FILE` -Add `custom/guest.yml` to the end of the `COMPOSE_FILE` variable in your `.env` file, for example: +Add `custom/guest.yml` to the end of the existing `COMPOSE_FILE` variable in your `.env` file, for example: ```env COMPOSE_FILE=docker-compose.yml:weboffice/collabora.yml:traefik/opencloud.yml:traefik/collabora.yml:radicale/radicale.yml:custom/guest.yml ``` +Keep all files that are already part of your deployment. + :::note Make sure that the `.env` file contains only one active `COMPOSE_FILE` line. If there are several lines, only the last one is used. ::: -## Configure Email Delivery - -Guests receive their invitation link by email. Configure the SMTP settings and enable the `notifications` service in your `.env` file: - -```env -SMTP_HOST=smtp.example.com -SMTP_PORT=587 -SMTP_SENDER=OpenCloud -SMTP_USERNAME=noreply@example.com -SMTP_PASSWORD=YOUR-PASSWORD -SMTP_TRANSPORT_ENCRYPTION=starttls -SMTP_INSECURE=false -SMTP_AUTHENTICATION=auto -START_ADDITIONAL_SERVICES=notifications -``` - -- `SMTP_SENDER` must usually match the mailbox that sends the email. Otherwise the mail server may reject the message. -- If `START_ADDITIONAL_SERVICES` already contains other services, add `notifications` separated by a comma. -- Use port `587` with `starttls` or port `465` with `ssltls`, depending on your mail provider. - -For more information, see [Mail Notifications](./mail-notifications.md). - -:::tip -Some hosting providers block outgoing connections on port `465`. If emails are not sent, check which port is reachable from your server: - -```bash -nc -vz -w 5 smtp.example.com 465 -nc -vz -w 5 smtp.example.com 587 -``` - -::: - ## Restart OpenCloud Apply the changes: @@ -184,20 +135,25 @@ The status must be `Up`. If the status is `Restarting`, see [Troubleshooting](#t Check that the Guest Feature is enabled: ```bash -docker compose exec opencloud env | grep GUEST +docker compose exec opencloud printenv OC_ENABLE_GUEST_LINKS ``` -The output must contain `OC_ENABLE_GUEST_LINKS=true`. +The output must be `true`. -Check that the email settings are active: +Check that the `notifications` service is enabled: ```bash -docker compose exec opencloud env | grep -E "SMTP_HOST|ADD_RUN_SERVICES" +docker compose exec opencloud printenv OC_ADD_RUN_SERVICES ``` -The output must contain your SMTP server and `notifications`. +The output must contain `notifications`. + +Finally, test the Guest Feature in the web interface: -Finally, test the Guest Feature in the web interface: share a folder with an external email address, select the entry marked **(Guest)**, and click **Share**. The guest should receive an invitation email. +1. Share a file or folder with an external email address. +2. Select the recipient marked `(Guest)`. +3. Click `Share`. +4. Verify that the guest receives an invitation email and can access the shared content. ## Optional Settings @@ -229,11 +185,11 @@ If the log contains `guestlinks: service_account_id must not be empty`, the serv If users see the message `Failed to add share` when they share with a guest: -- Check that the OpenCloud image contains the `auth-guest` service, see [Check the OpenCloud Version](#check-the-opencloud-version). -- Check that `OC_ENABLE_GUEST_LINKS=true` is set inside the container: +- Make sure that you are running OpenCloud version 9.0.0 or later. +- Verify that `OC_ENABLE_GUEST_LINKS` is set to `true` inside the container: ```bash - docker compose exec opencloud env | grep GUEST + docker compose exec opencloud printenv OC_ENABLE_GUEST_LINKS ``` If there is no output, the variable is not passed to the container. Make sure that `custom/guest.yml` is part of `COMPOSE_FILE`. @@ -246,8 +202,6 @@ Check the log of the `notifications` service: docker compose logs opencloud | grep '"service":"notifications"' | tail -10 ``` -- **No output:** The `notifications` service is not running. Set `START_ADDITIONAL_SERVICES=notifications` in your `.env` file. -- **`SMTP Connection timed out`:** OpenCloud cannot reach the mail server. Your hosting provider may block the configured port. Use port `587` with `starttls` instead of port `465`. -- **Authentication errors:** Check `SMTP_USERNAME`, `SMTP_PASSWORD`, and `SMTP_SENDER`. +Make sure that the `notifications` service is enabled and that your SMTP configuration is working. See [Mail Notifications](./mail-notifications.md) for configuration details and troubleshooting. Invitations created while email delivery was not working are not sent again. Remove the guest share and invite the guest again. From dd998586086fa93f8634b2cdfc70331fc0e6924c Mon Sep 17 00:00:00 2001 From: Heiko Pohl Date: Mon, 2 Nov 2026 11:27:31 +0100 Subject: [PATCH 3/3] changes --- docs/admin/configuration/guest-feature.md | 37 ++++++----------------- 1 file changed, 10 insertions(+), 27 deletions(-) diff --git a/docs/admin/configuration/guest-feature.md b/docs/admin/configuration/guest-feature.md index 9d06c284..606dffd6 100644 --- a/docs/admin/configuration/guest-feature.md +++ b/docs/admin/configuration/guest-feature.md @@ -32,11 +32,11 @@ The Guest Feature is provided by the `auth-guest` service. ## Prerequisites -- A running OpenCloud deployment based on `opencloud-compose`. +- A running OpenCloud deployment based on [`opencloud-compose`](https://github.com/opencloud-eu/opencloud-compose). - OpenCloud version 9.0.0 or later. - A working SMTP configuration for sending invitation emails. -If you are running an older OpenCloud version, follow the [Standard Upgrade Guide](../maintenance/upgrade/upgrade-guide.md) before enabling the Guest Feature. +If you are running an older OpenCloud version, follow the [Standard Upgrade Guide](../maintenance/upgrade/upgrade.md) and the [Upgrade 9.x.x](../maintenance/upgrade/upgrade-9.x.x.md) guide before enabling the Guest Feature. :::important Before upgrading, check whether a version-specific upgrade guide is available for your target version. These guides may contain additional migration steps, configuration changes, or breaking changes that must be considered. @@ -46,29 +46,18 @@ To configure email delivery, follow the [Mail Notifications](./mail-notification All commands in this guide are run in the root directory of the `opencloud-compose` deployment. -## Get the Service Account Credentials +## Check the Service Account Configuration -The `auth-guest` service uses the OpenCloud service account. Without it, the service does not start. +The `auth-guest` service requires a service account. Without it, the service does not start and the OpenCloud container keeps restarting. -Read the service account credentials from your existing OpenCloud configuration: +Check whether your OpenCloud configuration contains the service account settings for the `auth-guest` service: ```bash -docker compose exec opencloud cat /etc/opencloud/opencloud.yaml | grep -m1 -A2 "service_account:" +docker compose exec opencloud grep -A3 "auth_guest:" /etc/opencloud/opencloud.yaml ``` -The output looks similar to this: - -```yaml -service_account: - service_account_id: 1234abcd-... - service_account_secret: ... -``` - -You need both values in the next step. - -:::important -Treat the service account secret like a password. Do not share it. -::: +- **New installations of OpenCloud 9.0.0 or later:** The output shows the `service_account` settings. They are created automatically during the initial setup. No further action is required. +- **Installations upgraded from an earlier version:** If there is no output, migrate the configuration as described in the [Upgrade 9.x.x](../maintenance/upgrade/upgrade-9.x.x.md#guest-links) guide before you continue. ## Enable the Guest Feature @@ -85,21 +74,15 @@ mkdir -p custom nano custom/guest.yml ``` -Add the following content and replace the placeholders with the values from the previous step: +Add the following content: ```yaml services: opencloud: environment: OC_ENABLE_GUEST_LINKS: 'true' - AUTH_GUEST_SERVICE_ACCOUNT_ID: 'YOUR-SERVICE-ACCOUNT-ID' - AUTH_GUEST_SERVICE_ACCOUNT_SECRET: 'YOUR-SERVICE-ACCOUNT-SECRET' ``` -:::caution -Docker Compose interprets the `$` character as the start of a variable. If the secret contains a `$`, write it as `$$`. Otherwise Docker Compose shows a warning such as `The "XY" variable is not set` and passes an incorrect secret to the container. -::: - ### Add the File to `COMPOSE_FILE` Add `custom/guest.yml` to the end of the existing `COMPOSE_FILE` variable in your `.env` file, for example: @@ -179,7 +162,7 @@ Check the logs: docker compose logs --tail=40 opencloud ``` -If the log contains `guestlinks: service_account_id must not be empty`, the service account credentials are missing. Add `AUTH_GUEST_SERVICE_ACCOUNT_ID` and `AUTH_GUEST_SERVICE_ACCOUNT_SECRET` to `custom/guest.yml` as described in [Enable the Guest Feature](#enable-the-guest-feature). +If the log contains `guestlinks: service_account_id must not be empty`, the service account settings for the `auth-guest` service are missing in the OpenCloud configuration. Migrate the configuration as described in [Check the Service Account Configuration](#check-the-service-account-configuration). ### Sharing with a Guest Fails