From aa2da8372bcdb91dbc5a5c31e5ffc5fc30fd4088 Mon Sep 17 00:00:00 2001 From: Thomas Schweiger Date: Fri, 14 Nov 2025 12:24:01 +0100 Subject: [PATCH 1/3] fix: add missing service README.md files with basic description --- services/app-provider/README.md | 21 +++++++++++++ services/groups/README.md | 29 ++++++++++++++++++ services/sharing/README.md | 43 +++++++++++++++++++++++++++ services/storage-publiclink/README.md | 40 +++++++++++++++++++++++++ services/storage-shares/README.md | 36 ++++++++++++++++++++++ services/users/README.md | 29 ++++++++++++++++++ 6 files changed, 198 insertions(+) create mode 100644 services/app-provider/README.md create mode 100644 services/groups/README.md create mode 100644 services/sharing/README.md create mode 100644 services/storage-publiclink/README.md create mode 100644 services/storage-shares/README.md create mode 100644 services/users/README.md diff --git a/services/app-provider/README.md b/services/app-provider/README.md new file mode 100644 index 000000000..4d68bd31e --- /dev/null +++ b/services/app-provider/README.md @@ -0,0 +1,21 @@ +# App Provider + +The `app-provider` service provides the CS3 App Provider API for OpenCloud. It is responsible for managing and serving applications that can open files based on their MIME types. + +The service works in conjunction with the `app-registry` service, which maintains the registry of available applications and their supported MIME types. When a client requests to open a file with a specific application, the `app-provider` service handles the request and coordinates with the application to provide the appropriate interface. + +## Integration + +The `app-provider` service integrates with: +- `app-registry` - For discovering which applications are available for specific MIME types +- `frontend` - The frontend service forwards app provider requests (default endpoint `/app`) to this service +- `gateway` - Routes requests to the app provider service + +## Configuration + +The service can be configured via environment variables. Key configuration options include: +- `APP_PROVIDER_EXTERNAL_ADDR` - External address where the gateway service can reach the app provider + +## Scalability + +The app-provider service can be scaled horizontally as it primarily acts as a coordinator between applications and the OpenCloud storage layer. diff --git a/services/groups/README.md b/services/groups/README.md new file mode 100644 index 000000000..7d496a7ff --- /dev/null +++ b/services/groups/README.md @@ -0,0 +1,29 @@ +# Groups + +The `groups` service provides the CS3 Groups API for OpenCloud. It is responsible for managing group information and memberships within the OpenCloud instance. + +This service implements the CS3 identity group provider interface, allowing other services to query and manage groups. It works as a backend provider for the `graph` service when using the CS3 backend mode. + +## Backend Integration + +The groups service can work with different storage backends: +- LDAP integration through the graph service +- Direct CS3 API implementation + +When using the `graph` service with the CS3 backend (`GRAPH_IDENTITY_BACKEND=cs3`), the graph service queries group information through this service. + +## API + +The service provides CS3 gRPC APIs for: +- Listing groups +- Getting group information +- Finding groups by name or ID +- Managing group memberships + +## Usage + +The groups service is primarily used internally by other OpenCloud services rather than being accessed directly by clients. The `frontend` and `ocs` services translate HTTP API requests into CS3 API calls to this service. + +## Scalability + +Since the groups service queries backend systems (like LDAP through the configured identity backend), it can be scaled horizontally without additional configuration when using stateless backends. diff --git a/services/sharing/README.md b/services/sharing/README.md new file mode 100644 index 000000000..328b0b3fc --- /dev/null +++ b/services/sharing/README.md @@ -0,0 +1,43 @@ +# Sharing + +The `sharing` service provides the CS3 Sharing API for OpenCloud. It manages user shares and public link shares, implementing the core sharing functionality. + +## Overview + +The sharing service handles: +- User-to-user shares (share a file or folder with another user) +- Public link shares (share via a public URL) +- Share permissions and roles +- Share lifecycle management (create, update, delete) + +This service works in conjunction with the storage providers (`storage-shares` and `storage-publiclink`) to persist and manage share information. + +## Integration + +The sharing service integrates with: +- `frontend` and `ocs` - Provide HTTP APIs that translate to CS3 sharing calls +- `storage-shares` - Stores and manages received shares +- `storage-publiclink` - Manages public link shares +- `gateway` - Routes sharing requests +- `graph` - Provides LibreGraph API for sharing with roles + +## Share Types + +The service supports different types of shares: +- **User shares** - Share resources with specific users +- **Group shares** - Share resources with groups +- **Public link shares** - Create public URLs for sharing +- **Federated shares** - Share with users on other OpenCloud instances (via `ocm` service) + +## Configuration + +Share behavior can be configured via environment variables: +- Password enforcement for public shares +- Auto-acceptance of shares +- Share permissions and restrictions + +See the `frontend` service README for more details on share-related configuration options. + +## Scalability + +The sharing service depends on the configured storage backends for share metadata. Scalability characteristics depend on the chosen storage backend configuration. diff --git a/services/storage-publiclink/README.md b/services/storage-publiclink/README.md new file mode 100644 index 000000000..d6640894a --- /dev/null +++ b/services/storage-publiclink/README.md @@ -0,0 +1,40 @@ +# Storage PublicLink + +The `storage-publiclink` service provides storage backend functionality for public link shares in OpenCloud. It implements the CS3 storage provider interface specifically for managing public link shared resources. + +## Overview + +This service is part of the storage services family and is responsible for: +- Storing metadata about public link shares +- Providing access to publicly shared resources +- Managing public link tokens and permissions +- Handling anonymous access to shared content + +## Integration + +The storage-publiclink service integrates with: +- `sharing` service - Creates and manages public link shares +- `gateway` service - Routes requests to publicly shared resources +- `frontend` and `ocdav` - Provide HTTP/WebDAV access to public links +- Storage drivers - Accesses the actual file content + +## Storage Registry + +The service is registered in the gateway's storage registry with: +- Provider ID: `7993447f-687f-490d-875c-ac95e89a62a4` +- Mount point: `/public` +- Space types: `grant` and `mountpoint` + +See the `gateway` README for more details on storage registry configuration. + +## Access Control + +Public link shares can be configured with: +- Password protection +- Expiration dates +- Read-only or read-write permissions +- Download limits + +## Scalability + +The storage-publiclink service can be scaled horizontally. When running multiple instances, ensure that the storage backend configuration is identical across all instances. diff --git a/services/storage-shares/README.md b/services/storage-shares/README.md new file mode 100644 index 000000000..1527c9a44 --- /dev/null +++ b/services/storage-shares/README.md @@ -0,0 +1,36 @@ +# Storage Shares + +The `storage-shares` service provides storage backend functionality for user and group shares in OpenCloud. It implements the CS3 storage provider interface specifically for managing shared resources. + +## Overview + +This service is part of the storage services family and is responsible for: +- Storing metadata about user and group shares +- Providing a virtual view of received shares +- Managing share mountpoints +- Handling access to resources shared by other users + +## Integration + +The storage-shares service integrates with: +- `sharing` service - Creates and manages shares +- `gateway` service - Routes requests to shared resources +- `storage-users` service - Accesses the underlying file content +- `frontend` and `ocdav` - Provide HTTP/WebDAV access to shares + +## Virtual Shares Folder + +The service provides a virtual "Shares" folder for each user where all received shares are mounted. This allows users to access all files and folders that have been shared with them in a centralized location. + +## Storage Registry + +The service is registered in the gateway's storage registry with: +- Provider ID: `a0ca6a90-a365-4782-871e-d44447bbc668` +- Mount point: `/users/{{.CurrentUser.Id.OpaqueId}}/Shares` +- Space types: `virtual`, `grant`, and `mountpoint` + +See the `gateway` README for more details on storage registry configuration. + +## Scalability + +The storage-shares service can be scaled horizontally. When running multiple instances, ensure that the share metadata storage configuration is identical across all instances. diff --git a/services/users/README.md b/services/users/README.md new file mode 100644 index 000000000..04ec3a1ec --- /dev/null +++ b/services/users/README.md @@ -0,0 +1,29 @@ +# Users + +The `users` service provides the CS3 Users API for OpenCloud. It is responsible for managing user information and authentication within the OpenCloud instance. + +This service implements the CS3 identity user provider interface, allowing other services to query and manage user accounts. It works as a backend provider for the `graph` service when using the CS3 backend mode. + +## Backend Integration + +The users service can work with different storage backends: +- LDAP integration through the graph service +- Direct CS3 API implementation + +When using the `graph` service with the CS3 backend (`GRAPH_IDENTITY_BACKEND=cs3`), the graph service queries user information through this service. + +## API + +The service provides CS3 gRPC APIs for: +- Listing users +- Getting user information +- Finding users by username, email, or ID +- User authentication and validation + +## Usage + +The users service is primarily used internally by other OpenCloud services rather than being accessed directly by clients. The `frontend`, `ocs`, and `graph` services translate HTTP API requests into CS3 API calls to this service. + +## Scalability + +Since the users service queries backend systems (like LDAP through the configured identity backend), it can be scaled horizontally without additional configuration when using stateless backends. From 4de25fdb5e8c24aa65ac71a2304863ef105d8fc3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=B6rn=20Friedrich=20Dreyer?= Date: Mon, 17 Nov 2025 10:41:17 +0100 Subject: [PATCH 2/3] Apply suggestions from code review --- services/app-provider/README.md | 2 +- services/groups/README.md | 2 +- services/storage-publiclink/README.md | 9 +++------ services/storage-shares/README.md | 9 +++------ services/users/README.md | 2 +- 5 files changed, 9 insertions(+), 15 deletions(-) diff --git a/services/app-provider/README.md b/services/app-provider/README.md index 4d68bd31e..26354be49 100644 --- a/services/app-provider/README.md +++ b/services/app-provider/README.md @@ -18,4 +18,4 @@ The service can be configured via environment variables. Key configuration optio ## Scalability -The app-provider service can be scaled horizontally as it primarily acts as a coordinator between applications and the OpenCloud storage layer. +The app-provider service can be scaled horizontally as it primarily acts as a coordinator between applications and the OpenCloud backend services. diff --git a/services/groups/README.md b/services/groups/README.md index 7d496a7ff..7f22e1180 100644 --- a/services/groups/README.md +++ b/services/groups/README.md @@ -22,7 +22,7 @@ The service provides CS3 gRPC APIs for: ## Usage -The groups service is primarily used internally by other OpenCloud services rather than being accessed directly by clients. The `frontend` and `ocs` services translate HTTP API requests into CS3 API calls to this service. +The groups service is only used internally by other OpenCloud services and not being accessed directly by clients. The `frontend` and `ocs` services translate HTTP API requests into CS3 API calls to this service. ## Scalability diff --git a/services/storage-publiclink/README.md b/services/storage-publiclink/README.md index d6640894a..8728743bb 100644 --- a/services/storage-publiclink/README.md +++ b/services/storage-publiclink/README.md @@ -1,20 +1,17 @@ # Storage PublicLink -The `storage-publiclink` service provides storage backend functionality for public link shares in OpenCloud. It implements the CS3 storage provider interface specifically for managing public link shared resources. +The `storage-publiclink` service provides storage backend functionality for public link shares in OpenCloud. It implements the CS3 storage provider interface specifically for working with public link shared resources. ## Overview This service is part of the storage services family and is responsible for: -- Storing metadata about public link shares - Providing access to publicly shared resources -- Managing public link tokens and permissions - Handling anonymous access to shared content ## Integration The storage-publiclink service integrates with: -- `sharing` service - Creates and manages public link shares -- `gateway` service - Routes requests to publicly shared resources +- `sharing` service - Manages and persists public link shares - `frontend` and `ocdav` - Provide HTTP/WebDAV access to public links - Storage drivers - Accesses the actual file content @@ -37,4 +34,4 @@ Public link shares can be configured with: ## Scalability -The storage-publiclink service can be scaled horizontally. When running multiple instances, ensure that the storage backend configuration is identical across all instances. +The storage-publiclink service can be scaled horizontally. diff --git a/services/storage-shares/README.md b/services/storage-shares/README.md index 1527c9a44..5686b5a9e 100644 --- a/services/storage-shares/README.md +++ b/services/storage-shares/README.md @@ -1,20 +1,17 @@ # Storage Shares -The `storage-shares` service provides storage backend functionality for user and group shares in OpenCloud. It implements the CS3 storage provider interface specifically for managing shared resources. +The `storage-shares` service provides storage backend functionality for user and group shares in OpenCloud. It implements the CS3 storage provider interface specifically for working with shared resources. ## Overview This service is part of the storage services family and is responsible for: -- Storing metadata about user and group shares - Providing a virtual view of received shares -- Managing share mountpoints - Handling access to resources shared by other users ## Integration The storage-shares service integrates with: -- `sharing` service - Creates and manages shares -- `gateway` service - Routes requests to shared resources +- `sharing` service - Manages and persists shares - `storage-users` service - Accesses the underlying file content - `frontend` and `ocdav` - Provide HTTP/WebDAV access to shares @@ -33,4 +30,4 @@ See the `gateway` README for more details on storage registry configuration. ## Scalability -The storage-shares service can be scaled horizontally. When running multiple instances, ensure that the share metadata storage configuration is identical across all instances. +The storage-shares service can be scaled horizontally. diff --git a/services/users/README.md b/services/users/README.md index 04ec3a1ec..4d06667f5 100644 --- a/services/users/README.md +++ b/services/users/README.md @@ -22,7 +22,7 @@ The service provides CS3 gRPC APIs for: ## Usage -The users service is primarily used internally by other OpenCloud services rather than being accessed directly by clients. The `frontend`, `ocs`, and `graph` services translate HTTP API requests into CS3 API calls to this service. +The users service is only used internally by other OpenCloud services and not being accessed directly by clients. The `frontend`, `ocs`, and `graph` services translate HTTP API requests into CS3 API calls to this service. ## Scalability From 54a38e37c6b5f5d4c43ce9115680fcd492cfd6f6 Mon Sep 17 00:00:00 2001 From: Michael Barz Date: Mon, 17 Nov 2025 10:43:44 +0100 Subject: [PATCH 3/3] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Jörn Friedrich Dreyer --- services/app-provider/README.md | 1 - services/sharing/README.md | 1 - services/users/README.md | 1 - 3 files changed, 3 deletions(-) diff --git a/services/app-provider/README.md b/services/app-provider/README.md index 26354be49..63540fbbc 100644 --- a/services/app-provider/README.md +++ b/services/app-provider/README.md @@ -9,7 +9,6 @@ The service works in conjunction with the `app-registry` service, which maintain The `app-provider` service integrates with: - `app-registry` - For discovering which applications are available for specific MIME types - `frontend` - The frontend service forwards app provider requests (default endpoint `/app`) to this service -- `gateway` - Routes requests to the app provider service ## Configuration diff --git a/services/sharing/README.md b/services/sharing/README.md index 328b0b3fc..161c9ec02 100644 --- a/services/sharing/README.md +++ b/services/sharing/README.md @@ -18,7 +18,6 @@ The sharing service integrates with: - `frontend` and `ocs` - Provide HTTP APIs that translate to CS3 sharing calls - `storage-shares` - Stores and manages received shares - `storage-publiclink` - Manages public link shares -- `gateway` - Routes sharing requests - `graph` - Provides LibreGraph API for sharing with roles ## Share Types diff --git a/services/users/README.md b/services/users/README.md index 4d06667f5..020ee537b 100644 --- a/services/users/README.md +++ b/services/users/README.md @@ -18,7 +18,6 @@ The service provides CS3 gRPC APIs for: - Listing users - Getting user information - Finding users by username, email, or ID -- User authentication and validation ## Usage