diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 91939fdb..c788429c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,19 +5,19 @@ SPDX-License-Identifier: Apache-2.0 # Read me first -Please read the [project's overall CONTRIBUTING.md](https://gitlab.opencode.de/bmi/opendesk/info/-/blob/main/CONTRIBUTING.md) first. +Please read the [project's entire CONTRIBUTING.md](https://gitlab.opencode.de/bmi/opendesk/info/-/blob/main/CONTRIBUTING.md) first. # How to contribute? Please also read the [project's workflow documentation](./docs/workflow.md) for more details on standards like commit -messages and branching. +messages and branching convention. ## Helm vs. Operators vs. Manifests Due to DVS requirements: - we have to use [Helm charts](https://helm.sh/) (that can consist of Manifests). -- we should avoid stand alone Manifests. +- we should avoid stand-alone Manifests. - we do not use Operators and CRDs. In order to align the Helm files from various sources into the unified deployment of openDesk we make use of @@ -25,13 +25,12 @@ In order to align the Helm files from various sources into the unified deploymen ## Tooling -We should not introduce a new tool without sharing the purpose with the team and let the team decide if the tool should -be used. +New tools should not be introduced without first discussing it with the team. A proposal is fine, but let the team decide if the tool should +be used or not. We should avoid adding unnecessary complexity. ## In doubt? Ask! -We are always happy about contributions, but also like to discuss technical approaches to solve a problem to ensure -a contribution fits the openDesk platform strategy or clarify that specific topics might be must ahead on our own -roadmap. So when in doubt please [open an issue](https://gitlab.opencode.de/bmi/opendesk/deployment/sovereign-workplace/-/issues/new) and start a discussion. +We are always happy to receive contributions, but we also like to discuss technical approaches in order to solve a problem. This helps to ensure +a contribution fits the openDesk platform strategy and roadmap, and potentially avoids otherwise wasted time. So when in doubt please [open an issue](https://gitlab.opencode.de/bmi/opendesk/deployment/sovereign-workplace/-/issues/new) and start a discussion. diff --git a/README-EE.md b/README-EE.md index dcb9ddf3..6807904e 100644 --- a/README-EE.md +++ b/README-EE.md @@ -15,13 +15,13 @@ SPDX-License-Identifier: Apache-2.0 openDesk Enterprise Edition is recommended for production use. It receives support and patches from ZenDiS and the suppliers of the components due to the included product subscriptions. -The document refers to openDesk Community Edition as "oD CE" and for the openDesk Enterprise Edition it is "oD EE". +This document refers to the openDesk Community Edition as "oD CE" and the openDesk Enterprise Edition as "oD EE". -Please contact [ZenDiS](mailto:opendesk@zendis.de) to get openDesk Enterprise, either as SaaS offering or for you on-premise installation. +Please contact [ZenDiS](mailto:opendesk@zendis.de) to get openDesk Enterprise, either as a SaaS offering or for you on-premise installation. # Components -The following components using the same codebase and artifacts for their Enterprise and Community offering: +The following components are using the same codebase and artifacts for their Enterprise and Community offering: - Cryptpad - Jitsi - Nubus @@ -31,15 +31,15 @@ The following components using the same codebase and artifacts for their Enterpr The following components have - at least partially - Enterprise specific artifacts: - Collabora: Collabora Online image version `...3` will be used once available, at the same time the Collabora Development Edition image will be updated to `...2` for oD CE. -- Element: Some artifacts providing additional functionality are only available in oD EE. For the shared artifacts we keep the ones in oD CE and oD EE in sync. -- Nextcloud: Specific enterprise image based on the NC Enterprise package is build based on the same release version as used in oD CE. -- OX AppSuite: oD CE and EE are using the same release version, in EE an enterprise-built container of the AppSuite's Core-Middleware is being integrated. +- Element: Some artifacts providing additional functionality are only available in oD EE. For the shared artifacts, we keep the ones in oD CE and oD EE in sync. +- Nextcloud: An enterprise image based on the NC Enterprise package is built, which uses the same release version as the one used in oD CE. +- OX AppSuite: oD CE and EE use the same release version, in EE however, an enterprise-built container of the AppSuite's Core-Middleware is integrated. - OX Dovecot Pro 3: Dovecot Pro provides support for S3 storage and this feature is used by default. -If you want to check in detail which artifacts are specific to openDesk Enterprise and thereby may contain non open source code, please check the `repository:` +If you want to check in detail which artifacts are specific to openDesk Enterprise and thereby may contain proprietary code, please check the `repository:` values in the image ([1](./helmfile/environments/default/images.yaml.gotmpl) / [2](./helmfile/environments/default-enterprise-overrides/images.yaml.gotmpl)) and chart ([1](./helmfile/environments/default/charts.yaml.gotmpl) / [2](./helmfile/environments/default-enterprise-overrides/charts.yaml.gotmpl)) definitions. -When a repository path starts with `/zendis` the artifact is only available in an openDesk Enterprise deployment. +When a repository path starts with `/zendis`, the artifact is only available in an openDesk Enterprise deployment. # Enabling the Enterprise deployment @@ -59,7 +59,7 @@ OPENDESK_ENTERPRISE=true With openDesk EE you get access to the related artifact registry owned by ZenDiS. -Three steps are required to access the registry - for step #1 and #2 you can set some variables. You can to define a `` freely, like `enterprise-secret`, as long as it consistent in step #1 and #3. +Three steps are required to access the registry - for step #1 and #2 you can set some variables. Below, you can define `` freely, like `enterprise-secret`, as long as it consistent in step #1 and #3. ```shell NAMESPACE= @@ -68,7 +68,7 @@ YOUR_ENTERPRISE_REGISTRY_USERNAME= YOUR_ENTERPRISE_REGISTRY_PASSWORD= ``` -1. Add your registry credentials as secret to the namespace you want to deploy openDesk to. Do not forget to create the namespace if it does not exist yet (`kubectl create namespace ${NAMESPACE}`). +1. Add your registry credentials as a secret to the namespace you want to deploy openDesk to. Do not forget to create the namespace if it does not exist yet (`kubectl create namespace ${NAMESPACE}`). ```shell kubectl create secret --namespace "${NAMESPACE}" \ diff --git a/README.md b/README.md index 17f7a248..981fb276 100644 --- a/README.md +++ b/README.md @@ -25,10 +25,10 @@ SPDX-License-Identifier: Apache-2.0 # Overview -openDesk is a Kubernetes based, open-source and cloud-native digital workplace suite provided by the +openDesk is a Kubernetes-based, open-source and cloud-native digital workplace suite provided by the *Zentrum für Digitale Souveränität der Öffentlichen Verwaltung (ZenDiS) GmbH*. -For production use, [openDesk Enterprise Edition](./README-EE.md) is recommended. +For production use, the [openDesk Enterprise Edition](./README-EE.md) is recommended. openDesk currently features the following functional main components: @@ -45,7 +45,7 @@ openDesk currently features the following functional main components: | Videoconferencing | Jitsi | [2.0.9955](https://github.com/jitsi/jitsi-meet/releases/tag/stable%2Fjitsi-meet_9955) | [For the most recent release](https://jitsi.github.io/handbook/docs/category/user-guide/) | | Weboffice | Collabora | [24.04.12.4](https://www.collaboraoffice.com/code-24-04-release-notes/) | Online documentation available from within the installed application; [Additional resources](https://sdk.collaboraonline.com/) | -While not all components are perfectly shaped for the execution inside containers, one of the project's objectives is to +While not all components are perfectly designed for the execution inside containers, one of the project's objectives is to align the applications with best practices regarding container design and operations. This documentation aims to give you all that is needed to set up your own instance of the openDesk. @@ -81,19 +81,19 @@ You would like to install openDesk in your own infrastructure? # Architecture -More information on openDesk's architecture can be found in our [architecture docs](./docs/architecture.md). +More information on openDesk's architecture can be found in our [architecture documentation](./docs/architecture.md). # Testing -openDesk is continously tested to ensure a high quality. Read how we test in openDesk in our [test concept](./docs/testing.md). +openDesk is continuously tested to ensure it meets high quality standards. Read how we test in openDesk in our [testing concept](./docs/testing.md). # Permissions -Find out more about the permission system in the[roles & permissions concept](./docs/permissions.md) +Find out more about the permission system in the [roles & permissions concept](./docs/permissions.md) # Releases -All technical releases are created using [Semantic Versioning](https://semver.org/lang/de/). +All technical releases are created using [Semantic Versioning](https://semver.org/). Gitlab provides an [overview on the releases](https://gitlab.opencode.de/bmi/opendesk/deployment/opendesk/-/releases) diff --git a/docs/architecture.md b/docs/architecture.md index e8f12152..8762d40d 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -44,7 +44,7 @@ openDesk is designed as a [Kubernetes](https://kubernetes.io) deployment. It consists of a set of [Helm charts](https://helm.sh/) orchestrated by [Helmfile](https://github.com/helmfile/helmfile). -openDesk includes the functional applications, like file management, chat, and email. Other services such +openDesk includes functional applications, like file management, chat, and email. Other services such as databases and object storage are included for evaluation purposes only. In production, you must provide these services yourself. @@ -73,12 +73,12 @@ flowchart TD openDesk includes a portal that allows navigation to the respective application. The portal is part of the Identity and Access Management (IAM) application shipped with openDesk: *Nubus*. Nubus includes OpenLDAP for storing users, groups, and permissions, and Keycloak for single sign-on with LDAP user federation -configured to the aforementioned OpenLDAP. +configured to use the aforementioned OpenLDAP. When the user is authenticated by Keycloak, the portal shows the applications the user is permitted to access. -The user can now access applications and use the corresponding functionality without the need to authenticate to -applications again. This is implemented using the OpenID Connect (OIDC) protocol. +The user can now access applications and use the corresponding functionality without the need to authenticate +again. This is implemented using the OpenID Connect (OIDC) protocol. # Nubus (IAM) @@ -111,11 +111,11 @@ In openDesk, Nubus serves the following purposes: 6. Frontend Integration Authentication - A specialized component - the Intercom Service - acts according to the Backend-for-Frontend pattern when it comes to certain integration use cases requiring the frontend of one application to call the API of another service that also has the need for user authentication. See [Component integration](#component-integration) for more details. + A specialized component - the Intercom Service - acts according to the Backend-for-Frontend pattern when it comes to certain integration use cases, for example, ones that require the frontend of one application to call the API of another service, that also has the need for user authentication. See [Component integration](#component-integration) for more details. 7. Portal - Nubus provides a Portal component for users to access the connected applications, that also includes a self service e.g. for password reset. + Nubus provides a Portal component for users to access the connected applications. This component also includes self-service possibilities e.g. for password resetting. For additional information, refer to the [Nubus for Kubernetes Architecture Manual](https://docs.software-univention.de/nubus-kubernetes-architecture/latest/en/index.html). @@ -197,16 +197,16 @@ For more information, see the [Keycloak Documentation](https://www.keycloak.org/ ## Keycloak Extensions -Part of Nubus are the [Keycloak Extensions](https://docs.software-univention.de/nubus-kubernetes-operation/1.0/en/configuration/keycloak-extensions.html) used for +Part of Nubus are the [Keycloak Extensions](https://docs.software-univention.de/nubus-kubernetes-operation/1.0/en/configuration/keycloak-extensions.html) which are used for: -- Login brute force protection: Blocking authentication requests upon too much failed attempts from a device or IP. The available [CAPTCHA](https://en.wikipedia.org/wiki/CAPTCHA) option is deactivated in openDesk. -- New device notification: Sending the use an email after successful login from a new device. +- Login brute force protection: Blocking authentication requests upon too many failed attempts from a device or IP. _The available [CAPTCHA](https://en.wikipedia.org/wiki/CAPTCHA) option is deactivated in openDesk._ +- New device notification: Sending the user an email after successful login from a new device. -To address these use cases the Keycloak Extensions act as a proxy to Keycloak. +To address these use cases, the Keycloak Extensions act as a proxy to Keycloak. ## OpenLDAP -[OpenLDAP](https://www.openldap.org) is an open-source implementation of the Lightweight Directory Access Protocol (LDAP) that provides a central repository for user and group information. In openDesk, OpenLDAP is used as the user directory to store user and group data and manage access control policies across the applications. +[OpenLDAP](https://www.openldap.org) is an open-source implementation of the Lightweight Directory Access Protocol (LDAP) that provides a central repository for user and group information. In openDesk, OpenLDAP is used as the user directory to store user and group data, and also manages access control policies across the applications. # Authorization @@ -214,21 +214,21 @@ To address these use cases the Keycloak Extensions act as a proxy to Keycloak. LDAP group synchronization ensures that user group memberships are consistent across the applications in openDesk that make use of the IAM group information. Nubus uses OpenLDAP to store and manage user groups, which are synchronized with integrated applications to enforce access control policies. -Beside Keycloak LDAP groups are available to the following applications, none of the application supports nested groups. It means that users must be direct members of a group, as members of sub groups are ignored. -- Files / Nextcloud: Reads all groups that are enabled for Nextcloud twice a day based on the setting `background_sync_interval` in the `user_ldap` app. -- Knowledge Management / XWiki: Reads all groups that are enabled for XWiki use, this is done nightly based the jobs `LDAP Group Import Job` and `Mapped groups daily updater` that admin users can access in `/bin/view/Scheduler`. -- Project Management / OpenProject: Reads all groups that are enabled for OpenProject [hourly](https://www.openproject.org/docs/system-admin-guide/authentication/ldap-connections/ldap-group-synchronization/#create-a-synchronized-group). -- Webmail / OX AppSuite: Requires a webmail user to be part of a group before the group is actively provisioned to OX AppSuite. +Keycloak LDAP groups are available to the following applications, however, none of the applications support nested groups. This means that users must be direct members of a group, as members of subgroups will be ignored. +- Files / Nextcloud: Reads all groups that are enabled for Nextcloud, twice a day. Determined by the setting `background_sync_interval` in the `user_ldap` app. +- Knowledge Management / XWiki: Reads all groups that are enabled for XWiki use, once daily during the night. Based on the jobs `LDAP Group Import Job` and `Mapped groups daily updater` that are accessible to admin users in `/bin/view/Scheduler`. +- Project Management / OpenProject: Reads all groups that are enabled for OpenProject, [hourly](https://www.openproject.org/docs/system-admin-guide/authentication/ldap-connections/ldap-group-synchronization/#create-a-synchronized-group). +- Webmail / OX AppSuite: Requires a webmail user to be a part of a group before the group is actively provisioned to OX AppSuite. # Provisioning Part of the already mentioned Nubus IAM is a [provisioning service](https://docs.software-univention.de/nubus-kubernetes-architecture/0.5/en/components/provisioning-service.html). -Beside the Nubus internal user of the provisioning service the OX AppSuite is currently the only openDesk application that is getting data actively provisioned in contrast to scenarios where applications fetch the required information from the LDAP. +Besides the Nubus internal user of the provisioning service, the OX AppSuite is currently the only openDesk application that is getting data actively provisioned to it. This is in contrast to the norm, where applications fetch the required information from the LDAP themselves. ## OX Connector -As the OX AppSuite is using an application specific format to get e.g. users provisioned, there is also a specific connector component that links to provisioning service to the OX AppSuite, it is called the [OX Connector](https://docs.software-univention.de/manual/5.0/de/mail/ox-connector.html). +As the OX AppSuite is using an application specific format to get e.g. users provisioned, there is also a specific connector component that links the provisioning service to the OX AppSuite, it is called the [OX Connector](https://docs.software-univention.de/manual/5.0/de/mail/ox-connector.html). The [OX SOAP API](https://oxpedia.org/wiki/index.php?title=Open-Xchange_Provisioning_using_SOAP) is used by the OX Connector to synchronize information about the follow OX AppSuite objects: - Contexts @@ -243,14 +243,14 @@ To find out more, see [Roles & Permissions](./docs/permissions.md). [System for Cross-domain Identity Management](https://scim.cloud) (SCIM) is an open standard for automating the exchange of user identity information between identity domains or IT systems. SCIM is designed to make user provisioning and management easier by providing a standardized way to manage user identities in cloud-based applications and services. -In openDesk, SCIM will be used in the future to automate the process of creating, updating, and deactivating user accounts across the applications. This ensures that user data is consistent and up-to-date across all applications, reducing the administrative overhead and potential for errors. +In openDesk, SCIM will be used in the future to automate the process of creating, updating, and deactivating user accounts across the applications. This ensures that user data is consistent across all applications, reducing the administrative overhead and potential for errors. > **Note:**
> SCIM support is planned in openDesk for 2025. # Component integration -Important, especially from the end user perspective are the functional integrations between the different openDesk applications. +Important, especially from the end user perspective, are the functional integrations between the different openDesk applications. ```mermaid flowchart TD @@ -276,19 +276,19 @@ Details can be found in the upstream documentation that is linked in the respect ## Intercom Service / Silent Login The Intercom Service is deployed in the context of Nubus. Its role is to enable cross-application integration -based on the user's browser interaction as handling authentication when the frontend of an application has to call -the API from another application is often a challenge. +based on the user's browser interaction, as handling authentication when the frontend of an application has to call +the API from another application is often challenging. To establish a session with the Intercom Service, applications can use the silent login feature within an iframe. Currently, only OX AppSuite and Element are using the frontend-based integration. -**Links** +**Links:** - [Intercom Service upstream documentation](https://docs.software-univention.de/intercom-service/latest/index.html). ## Central Contacts -OX App Suite is managing contacts in openDesk. Therefore, Nextcloud's PHP backend is using the OX AppSuite's middleware Contacts API to +OX App Suite is responsible for managing contacts in openDesk. Therefore, Nextcloud's PHP backend is using the OX AppSuite's middleware Contacts API to - create a new contact in the user's contacts folder when a file is shared with an unknown email address. - retrieve contacts from the user's contacts folder to support search-as-you-type when starting to share a file. @@ -302,7 +302,7 @@ Central navigation is based on an API endpoint in the Nubus portal that returns a given user. The response from the API endpoint is used in the openDesk applications to render the central navigation. The API can be called by -- frontend services through the Intercom Service's `/navigation.json` endpoint or +- frontend services through the Intercom Service's `/navigation.json` endpoint. - backend services directly at the portal's `/univention/portal/navigation.json` endpoint. The central navigation expects the API caller to present a shared secret for authentication and the username for whom the portal @@ -316,7 +316,7 @@ curl 'https://portal./univention/portal/navigation.json?base=https%3A//p ## Filepicker -The Nextcloud Filepicker is integrated into the OX AppSuite, supporting the following use cases against the respective openDesk instance's Nextcloud: +The Nextcloud Filepicker is integrated into the OX AppSuite, supporting the following use cases within the respective openDesk instance's Nextcloud: - Attach files from Nextcloud to emails. - Create and add links to Nextcloud files into emails. - Save attachments from emails into Nextcloud. @@ -324,10 +324,10 @@ The Nextcloud Filepicker is integrated into the OX AppSuite, supporting the foll The Filepicker uses frontend and backend-based integration: - For frontend-based integration, the OX AppSuite frontend uses the Intercom Service. -- Backend-based integration is coming from OX AppSuite middleware. The middleware communicates directly with Nextcloud -when adding a file to an email or storing a file into Nextcloud to avoid passing these files through the user's browser. +- Backend-based integration is coming from the OX AppSuite middleware. The middleware communicates directly with Nextcloud +when attaching a file to an email or storing a file in Nextcloud to avoid passing these files through the user's browser. -**Links** +**Links:** - [OX AppSuite Nextcloud Integration upstream documentation](https://gitlab.open-xchange.com/extensions/nextcloud-integration/-/tree/main/documentation). ## Newsfeed @@ -391,7 +391,7 @@ In openDesk, Collabora is used for editing Office documents such as rich texts, ## CryptPad Online (Diagrams) -[CryptPad](https://cryptpad.org/) is a collaborative editor framework supporting end-to-end encryption.. +[CryptPad](https://cryptpad.org/) is a collaborative editor framework supporting end-to-end encryption. In openDesk, CryptPad is for editing diagrams.net documents. @@ -417,7 +417,7 @@ In openDesk, Jitsi is used for video conferencing and online meetings. It integr [Nubus](https://www.univention.com/products/nubus/) is a unified Identity & Access Management, providing you with full control and digital sovereignty over your IAM processes and data. -In openDesk Nubus is providing the management for user, groups and other IAM stored objects, as well as the portal, the Identity provider for Single Sign-On and federation scenarios and the +In openDesk, Nubus provides the management required for users, groups and other IAM objects, as well as the portal, the Identity provider for Single Sign-On and federation scenarios. ## OpenProject (Project management) @@ -435,7 +435,7 @@ In openDesk, OX App Suite is used for email, calendar, address book and personal # Application specific user accounts -While the IAM managed users centrally, some applications come with local accounts for administrative purposes. +While the IAM manages users centrally, some applications come with local accounts for administrative purposes: | Application | Account name | Purpose | Password | | ------------ | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | diff --git a/docs/architecture/apis.md b/docs/architecture/apis.md index 2673457c..00fa8837 100644 --- a/docs/architecture/apis.md +++ b/docs/architecture/apis.md @@ -5,7 +5,7 @@ SPDX-License-Identifier: Apache-2.0

openDesk APIs

-This chapter presents APIs available in openDesk grouped by applications. +This chapter presents APIs available in openDesk, grouped by application. * [IAM - Nubus](#iam---nubus) @@ -88,19 +88,19 @@ This chapter presents APIs available in openDesk grouped by applications. ## UMC store API -| Name | UMC store API (also named UMC JavaScript API or Dojo/UMC JavaScript API) | -| ------------------------------ | --------------------------------------------------------------------------------------------------------- | -| Purpose | Encapsulate and ease the access to module data from JavaScript | -| Versioning | | -| Authentication | | -| In openDesk provided by | Nubus UMC | -| Transport protocol | | -| Usage within component | | -| Usage within openDesk | | -| Usage for external integration | | -| Parallel access | Allowed | -| Message protocol | | -| Supported standards | | +| Name | UMC store API (also named UMC JavaScript API or Dojo/UMC JavaScript API) | +| ------------------------------ |----------------------------------------------------------------------------------------------------------| +| Purpose | Encapsulate and ease the access to JavaScript module data | +| Versioning | | +| Authentication | | +| In openDesk provided by | Nubus UMC | +| Transport protocol | | +| Usage within component | | +| Usage within openDesk | | +| Usage for external integration | | +| Parallel access | Allowed | +| Message protocol | | +| Supported standards | | | Documentation | https://docs.software-univention.de/developer-reference/5.0/en/umc/local-system-module.html#umc-store-api | ## IntercomService (ICS) API @@ -113,7 +113,7 @@ This chapter presents APIs available in openDesk grouped by applications. | In openDesk provided by | Nubus UMC | | Transport protocol | HTTP(S) | | Usage within component | | -| Usage within openDesk | The ICS implements the BFF pattern for various openDesk inter-component integrations, see also [components.md](https://gitlab.opencode.de/bmi/opendesk/deployment/opendesk/-/blob/develop/docs/components.md#component-integration) | +| Usage within openDesk | The ICS implements the BFF pattern for various openDesk inter-component integrations, see [components.md](https://gitlab.opencode.de/bmi/opendesk/deployment/opendesk/-/blob/develop/docs/components.md#component-integration) | | Usage for external integration | | | Parallel access | Allowed | | Message protocol | Depends on the integration use case. | @@ -129,7 +129,7 @@ This chapter presents APIs available in openDesk grouped by applications. | Authentication | | | In openDesk provided by | Univention Event Processing | | Transport protocol | | -| Usage within component | The listener mechanism is used to dispatch events from the LDAP to the Nubus provisioning service. It should be replaced by another approach in the future. | +| Usage within component | The listener mechanism is used to dispatch events from the LDAP to the Nubus provisioning service. It should be replaced with another approach in the future. | | Usage within openDesk | The ICS implements the BFF pattern for various openDesk inter-component integrations, see also [components.md](https://gitlab.opencode.de/bmi/opendesk/deployment/opendesk/-/blob/develop/docs/components.md#component-integration) | | Usage for external integration | | | Parallel access | Allowed | @@ -144,8 +144,8 @@ More details on the Nubus provisioning service can be found here: https://docs.s ![Composition of UMC component with APIs highlighted](./apis_images/IAM-udm.png) | Name | UDM Simple API | -| ------------------------------ | ----------------------------------------------------------------- | -| Purpose | Allows to use capability and objects directly in Python programs. | +| ------------------------------ |-------------------------------------------------------------------| +| Purpose | Allows use of capability and objects directly in Python programs. | | Versioning | | | Authentication | | | In openDesk provided by | Univention Directory Manager | @@ -167,7 +167,7 @@ More details on the Nubus provisioning service can be found here: https://docs.s | Authentication | Basic Auth | | In openDesk provided by | Univention Directory Manager | | Transport protocol | HTTP(S) | -| Usage within component | The Nubus bootstrapping makes use of the API. | +| Usage within component | The Nubus bootstrapping process makes use of the API. | | Usage within openDesk | | | Usage for external integration | The [openDesk User Importer](https://gitlab.opencode.de/bmi/opendesk/components/platform-development/images/user-import) utilizes the API. | | Parallel access | Allowed | @@ -186,7 +186,7 @@ More details on the Nubus provisioning service can be found here: https://docs.s | Authentication | | | In openDesk provided by | Nubus | | Transport protocol | | -| Usage within component | The Nubus bootstrapping makes use of the API. | +| Usage within component | The Nubus bootstrapping process makes use of the API. | | Usage within openDesk | | | Usage for external integration | | | Parallel access | Allowed | @@ -196,20 +196,20 @@ More details on the Nubus provisioning service can be found here: https://docs.s ## LDAP -| Name | LDAP | -| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | -| Purpose | Read access to Nubus LDAP | -| Versioning | n/a | -| Authentication | LDAP user auth | -| In openDesk provided by | Nubus openLDAP | -| Transport protocol | LDAP | -| Usage within component | Data backend for Nubus | -| Usage within openDesk | Used by multiple application to access user/group data, e.g. Nextcloud Server, OpenProject, OX AppSuite backend, XWiki | -| Usage for external integration | No recommended | -| Parallel access | Allowed | -| Message protocol | LDAP | -| Supported standards | LDAP | -| Documentation | https://docs.software-univention.de/manual/5.0/en/domain-ldap/ldap-directory.html | +| Name | LDAP | +| ------------------------------ |-------------------------------------------------------------------------------------------------------------------------| +| Purpose | Read access to Nubus LDAP | +| Versioning | n/a | +| Authentication | LDAP user auth | +| In openDesk provided by | Nubus openLDAP | +| Transport protocol | LDAP | +| Usage within component | Data backend for Nubus | +| Usage within openDesk | Used by multiple applications to access user/group data, e.g. Nextcloud Server, OpenProject, OX AppSuite backend, XWiki | +| Usage for external integration | Not recommended | +| Parallel access | Allowed | +| Message protocol | LDAP | +| Supported standards | LDAP | +| Documentation | https://docs.software-univention.de/manual/5.0/en/domain-ldap/ldap-directory.html | ## Nubus Provisioning Service (**TBD**) @@ -221,24 +221,24 @@ To be delivered. # Groupware - OX AppSuite / OX Dovecot -![OX AppSuite APIs overview](./apis_images/Groupware-apis.png) +![OX AppSuite APIs overview](./apis_images/Groupware-api.png) ![Use of OX AppSuite APIs by other components](./apis_images/Groupware-api-usage.png) ## Usage of APIs within openDesk -Following are APIs used by the Groupware application: +The following are the APIs used by the Groupware application: | Used by | Accessed component | Service | Purpose | Message format | | ------------------------------ | ------------------ | ------------------ | ----------------------------------------------------------- | -------------------------------- | | AppSuite Middleware | Keycloak | Authentication | Single sign-on / sign-out | OIDC | | Dovecot | Keycloak | Authentication | Authenticate user | OIDC | -| AppSuite Frontend (in Browser) | Intercom Service | Silent Login | Stablish Intercom Service session | | +| AppSuite Frontend (in Browser) | Intercom Service | Silent Login | Establish Intercom Service session | | | AppSuite Frontend (in Browser) | Intercom Service | Central Navigation | Retrieve content for openDesk Navigation drop-down | JSON | | AppSuite Frontend (in Browser) | Intercom Service | Element Bot | Manage (CUD) meetings in Element | Custom JSON (based on iCalender) | | AppSuite Frontend (in Browser) | Intercom Service | Filepicker | Read/write contents from/to Nextcloud or create share links | WebDAV & Nextcloud API | | AppSuite Middleware | Nextcloud | Filepicker | Read/write files from/to Nextcloud | WebDAV & Nextcloud API | -| AppSuite Middleware | Element Bot | Element Bot | Update/delete meetings in Element | Custom JSON (based on iCalender) | +| AppSuite Middleware | Element Bot | Element Bot | Update/delete meetings in Element | Custom JSON (based on iCalender) | | AppSuite Middleware | LDAP | Address book | Search for global contacts and retrieve contact details | LDAP | | Dovecot | LDAP | Data retrieval | Retrieve necessary user details to handle mailboxes | LDAP | @@ -249,13 +249,13 @@ Following are APIs used by the Groupware application: | Name | HTTP API | | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Purpose | Login, accessing email, contacts, calendar, tasks, configs, email filtering, task automation, workflow automation, etc – most of the AppSuite's functionality that is available to the user through the Web-UI. | -| Versioning | No API-specific versioning. The version can be considered identical with OX App Suite version, which is contained in URL of online documentation of API. | +| Versioning | No API-specific versioning. The version can be considered identical to the OX App Suite version, which is contained in the URL of the online API documentation. | | Authentication | | | In openDesk provided by | OX AppSuite Middleware | | Transport protocol | HTTP(S) | | Usage within component | Used by OX Web-UI (Frontend) | -| Usage within openDesk | - Nextcloud used the SearchAPI to synchronize contacts
- Nordeck Meeting bot synchronizes OX meeting changes applied in Element. | -| Usage for external integration | Not used at the moment, but recommended way to integrate with OX AppSuite. | +| Usage within openDesk | - Nextcloud uses the SearchAPI to synchronize contacts
- Nordeck Meeting bot synchronizes OX meeting changes applied in Element. | +| Usage for external integration | Not used at the moment, but is the recommended way to integrate with OX AppSuite. | | Parallel access | Allowed | | Message protocol | JSON based, AppSuite specific format | | Supported standards | iCal, defined by RFC, fully implemented | @@ -283,26 +283,26 @@ Following are APIs used by the Groupware application: ## REST API -| Name | REST API | -| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Purpose | Delivers services in following functional groups:
- *Admin*: Interface for provisioning and other administrative operations
- *Advertisement*: The advertisement module
- *Health*: The health-check module
- *InternetFreeBusy*: Servlet for requesting free busy data
- *Metrics*: The metrics module
- *Preliminary*: This module contains preliminary endpoints which can change in the future
- *Push*: The push module
- *Userfeedback*: The user feedback module | -| Versioning | No API-specific versioning. The version can be considered identical with OX App Suite version, which is contained in URL of online documentation of API. | -| Authentication | Basic Auth | -| In openDesk provided by | OX AppSuite Middleware | -| Transport protocol | HTTP(S) | -| Usage within component | Push module is used by OX Frontend. | -| Usage within openDesk | none | -| Usage for external integration | none | -| Parallel access | Allowed | -| Message protocol | - Email Body RFC 822 is used by Push
- Prometheus format is used by Metrics API
- API iCal format is used by InternetFreeBusy | -| Supported standards | SOAP | -| Documentation | https://documentation.open-xchange.com/components/middleware/rest/8/index.html | +| Name | REST API | +| ------------------------------ |-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Purpose | Delivers services in the following functional groups:
- *Admin*: Interface for provisioning and other administrative operations
- *Advertisement*: The advertisement module
- *Health*: The health-check module
- *InternetFreeBusy*: Servlet for requesting free busy data
- *Metrics*: The metrics module
- *Preliminary*: This module contains preliminary endpoints which may change in the future
- *Push*: The push module
- *Userfeedback*: The user feedback module | +| Versioning | No API-specific versioning. The version can be considered identical to the OX App Suite version, which is contained in the URL of the online API documentation. | +| Authentication | Basic Auth | +| In openDesk provided by | OX AppSuite Middleware | +| Transport protocol | HTTP(S) | +| Usage within component | Push module is used by OX Frontend. | +| Usage within openDesk | none | +| Usage for external integration | none | +| Parallel access | Allowed | +| Message protocol | - Email Body RFC 822 is used by Push
- Prometheus format is used by Metrics API
- API iCal format is used by InternetFreeBusy | +| Supported standards | SOAP | +| Documentation | https://documentation.open-xchange.com/components/middleware/rest/8/index.html | ## CardDAV | Name | CardDAV | | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Purpose | Designed for rich clients. Synchronization of contact entries in both directions (i.e. as a server and as a client); vCard import and export are available via OX HTTP API | -| Versioning | Yes, API version is specific to the version of underlying protocol | +| Versioning | Yes, API version is specific to the version of the underlying protocol | | Authentication | | | In openDesk provided by | OX AppSuite Middleware | | Transport protocol | HTTP(S) | @@ -319,7 +319,7 @@ Following are APIs used by the Groupware application: | Name | CalDAV | | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Purpose | Designed for rich clients. Synchronization of contact entries in both directions (i.e. as a server and as a client); vCard import and export are available via OX HTTP API | -| Versioning | Yes, API version is specific to the version of underlying protocol | +| Versioning | Yes, API version is specific to the version of the underlying protocol | | Authentication | | | In openDesk provided by | OX AppSuite Middleware | | Transport protocol | HTTP(S) | @@ -333,37 +333,37 @@ Following are APIs used by the Groupware application: ## IMAP -| Name | IMAP | -| ------------------------------ | ------------------------------------------------------------------ | -| Purpose | Used for retrieval of emails, designed for rich clients | -| Versioning | Yes, API version is specific to the version of underlying protocol | -| Authentication | | -| In openDesk provided by | OX Dovecot | -| Transport protocol | TCP | -| Usage within component | Used by OX AppSuite middleware to read/write mail and folders | -| Usage within openDesk | none | -| Usage for external integration | Can be used by local IMAP clients (e.g. Thunderbird) | -| Parallel access | Allowed | -| Message protocol | RFC 9051 | -| Supported standards | IMAP | -| Documentation | https://www.rfc-editor.org/rfc/rfc9051 | +| Name | IMAP | +| ------------------------------ |--------------------------------------------------------------------------------------| +| Purpose | Used for retrieval of emails, designed for rich clients | +| Versioning | Yes, API version is specific to the version of the underlying protocol | +| Authentication | | +| In openDesk provided by | OX Dovecot | +| Transport protocol | TCP | +| Usage within component | Used by OX AppSuite middleware to read/write mail and folders | +| Usage within openDesk | none | +| Usage for external integration | Can be used by local IMAP clients (e.g. Thunderbird) | +| Parallel access | Allowed | +| Message protocol | RFC 9051 | +| Supported standards | IMAP | +| Documentation | https://www.rfc-editor.org/rfc/rfc9051 | ## POP3 -| Name | POP3 | -| ------------------------------ | ------------------------------------------------------------------ | -| Purpose | Used for retrieval of emails, designed for rich clients | -| Versioning | Yes, API version is specific to the version of underlying protocol | -| Authentication | | -| In openDesk provided by | OX Dovecot | -| Transport protocol | TCP | -| Usage within component | none | -| Usage within openDesk | none | -| Usage for external integration | Can be used by local POP3 clients (e.g. Thunderbird) | -| Parallel access | Allowed | -| Message protocol | RFC 1939 | -| Supported standards | IMAP | -| Documentation | https://www.rfc-editor.org/rfc/rfc1939 | +| Name | POP3 | +| ------------------------------ |------------------------------------------------------------------------| +| Purpose | Used for retrieval of emails, designed for rich clients | +| Versioning | Yes, API version is specific to the version of the underlying protocol | +| Authentication | | +| In openDesk provided by | OX Dovecot | +| Transport protocol | TCP | +| Usage within component | none | +| Usage within openDesk | none | +| Usage for external integration | Can be used by local POP3 clients (e.g. Thunderbird) | +| Parallel access | Allowed | +| Message protocol | RFC 1939 | +| Supported standards | IMAP | +| Documentation | https://www.rfc-editor.org/rfc/rfc1939 | # Files - Nextcloud @@ -371,7 +371,7 @@ Following are APIs used by the Groupware application: ## Usage of APIs within openDesk -Following are APIs used by the Files application: +The following are the APIs used by the Files application: | Used by | Accessed component | Service | Purpose | Message format | | ---------------- | ---------------------- | ---------------------- | -------------------------------------------------- | -------------- | @@ -385,12 +385,12 @@ Following are APIs used by the Files application: | Name | OCS API | | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Purpose | Obtain and/or manage user status, user preferences, shares, sharees, recommendations. API is likely to be extended to other use cases in the future. Nextcloud apps can extend the functionality of OCS API by providing new endpoints | -| Versioning | Identical with component release version | +| Versioning | Identical to component release version | | Authentication | Basic Auth or by passing a set of valid session cookies | | In openDesk provided by | Nextcloud Server | | Transport protocol | HTTP(S) | | Usage within component | none | -| Usage within openDesk | Filepicker is using the API to create share links. | +| Usage within openDesk | Filepicker uses the API to create share links. | | Usage for external integration | none | | Parallel access | Allowed | | Message protocol | Requests in JSON, responses in JSON or XML | @@ -417,49 +417,49 @@ Following are APIs used by the Files application: ## Activity API -| Name | Activity API | -| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | -| Purpose | Allows to obtain the list of actions initiated or involving a specific user (files created, shared, deleted etc and other activities reported by apps) | -| Versioning | Identical with component release version | -| Authentication | See linked documentation (which also names the version), address via URL path, e.g. `/ocs/v2.php/apps/activity/api/v2` | -| In openDesk provided by | Nextcloud Server | -| Transport protocol | HTTP(S) | -| Usage within component | none | -| Usage within openDesk | none | -| Usage for external integration | none | -| Parallel access | Allowed | -| Message protocol | Requests in JSON, responses in JSON or XML | -| Supported standards | | -| Documentation | https://github.com/nextcloud/activity/blob/master/docs/endpoint-v2.md | +| Name | Activity API | +| ------------------------------ |----------------------------------------------------------------------------------------------------------------------------------------------------| +| Purpose | Obtaining the list of actions initiated by or involving a specific user (files created, shared, deleted etc and other activities reported by apps) | +| Versioning | Identical to component release version | +| Authentication | See linked documentation (which also names the version), address via URL path, e.g. `/ocs/v2.php/apps/activity/api/v2` | +| In openDesk provided by | Nextcloud Server | +| Transport protocol | HTTP(S) | +| Usage within component | none | +| Usage within openDesk | none | +| Usage for external integration | none | +| Parallel access | Allowed | +| Message protocol | Requests in JSON, responses in JSON or XML | +| Supported standards | | +| Documentation | https://github.com/nextcloud/activity/blob/master/docs/endpoint-v2.md | ## Remote wipe API -| Name | Remote wipe API | -| ------------------------------ | ------------------------------------------------------------------------------------------- | -| Purpose | Used to wipe storage remotely (e.g. on a lost device) | -| Versioning | Identical with component release version | -| Authentication | Login flow token | -| In openDesk provided by | Nextcloud Server | -| Transport protocol | HTTP(S) | -| Usage within component | none | -| Usage within openDesk | none | -| Usage for external integration | none | -| Parallel access | Allowed | -| Message protocol | JSON | -| Supported standards | | +| Name | Remote wipe API | +| ------------------------------ |--------------------------------------------------------------------------------------------| +| Purpose | Used to wipe storage remotely (e.g. on a lost device) | +| Versioning | Identical to component release version | +| Authentication | Login flow token | +| In openDesk provided by | Nextcloud Server | +| Transport protocol | HTTP(S) | +| Usage within component | none | +| Usage within openDesk | none | +| Usage for external integration | none | +| Parallel access | Allowed | +| Message protocol | JSON | +| Supported standards | | | Documentation | https://docs.nextcloud.com/server/latest/developer_manual/client_apis/RemoteWipe/index.html | ## WebDAV | Name | WebDAV | -| ------------------------------ | --------------------------------------------------------------------------------------- | -| Purpose | Accessing files and folders, conducting search | -| Versioning | Identical with component release version | +| ------------------------------ |-----------------------------------------------------------------------------------------| +| Purpose | Accessing files and folders, conducting searches | +| Versioning | Identical to component release version | | Authentication | Basic Auth or by passing a set of valid session cookies | | In openDesk provided by | Nextcloud Server | | Transport protocol | HTTP(S) | | Usage within component | none | -| Usage within openDesk | Used by OX AppSuite to put/retrieve files (attachments) | +| Usage within openDesk | Used by OX AppSuite to get/put files (attachments) | | Usage for external integration | none | | Parallel access | Allowed | | Message protocol | Requests in JSON, responses in JSON or XML | @@ -472,7 +472,7 @@ CalDAV and CardDAV APIs are available in Nextcloud, but as openDesk uses OX AppS # Weboffice - Collabora -Following are APIs used by the Weboffice application: +The following are the APIs used by the Weboffice application: | Used by | Accessed component | Service | Purpose | Message format | | --------- | ------------------ | ----------------- | ------------------------------------------- | -------------- | @@ -496,20 +496,20 @@ sequenceDiagram ## PostMessage API -| Name | PostMessage API | -| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | -| Purpose | Interact with parent frame when Collabora browser part is enclosed in one, mostly based on WOPI specification with few extensions/modifications | -| Versioning | N/A | -| Authentication | CSP rules protect unauthorized communication. In practice editor is embedded in an iframe and can communicate only with the iframe's parent. | -| In openDesk provided by | Collabora | -| Transport protocol | HTTP | -| Usage within component | N/A | -| Usage within openDesk | Query number of users in a document, query supported export formats, manage sessions, manage actions like save, insert image, print etc. | -| Usage for external integration | In openDesk Collabora Online is integrated with Nextcloud but other integrations exist and are possible, see the documentation. | -| Parallel access | Allowed | -| Message protocol | JSON | -| Supported standards | [WOPI](https://learn.microsoft.com/en-us/openspecs/office_protocols/ms-wopi/6a8bb410-68ad-47e4-9dc3-6cf29c6b046b) | -| Documentation | https://sdk.collaboraonline.com/docs/postmessage_api.html | +| Name | PostMessage API | +| ------------------------------ |---------------------------------------------------------------------------------------------------------------------------------------------------| +| Purpose | Interact with parent frame when Collabora browser part is enclosed in one, mostly based on WOPI specification with few extensions/modifications | +| Versioning | N/A | +| Authentication | CSP rules protect unauthorized communication. In practice, the editor is embedded in an iframe and can communicate only with the iframe's parent. | +| In openDesk provided by | Collabora | +| Transport protocol | HTTP | +| Usage within component | N/A | +| Usage within openDesk | Query the number of users in a document, query supported export formats, manage sessions, manage actions like save, insert image, print etc. | +| Usage for external integration | In openDesk Collabora Online is integrated with Nextcloud but other integrations exist and are possible, see the documentation. | +| Parallel access | Allowed | +| Message protocol | JSON | +| Supported standards | [WOPI](https://learn.microsoft.com/en-us/openspecs/office_protocols/ms-wopi/6a8bb410-68ad-47e4-9dc3-6cf29c6b046b) | +| Documentation | https://sdk.collaboraonline.com/docs/postmessage_api.html | ## Conversion API @@ -524,13 +524,13 @@ sequenceDiagram | Usage within openDesk | To generate thumbnails in Nextcloud for supported document types. | | Usage for external integration | It is possible to set up Collabora Online as a general document converter service. | | Parallel access | Allowed | -| Message protocol | text based, see the documentation | +| Message protocol | Text based, see the documentation | | Supported standards | N/A | | Documentation | https://sdk.collaboraonline.com/docs/conversion_api.html | # Project management - OpenProject -Following are APIs used by the Project management application: +The following are the APIs used by the Project management application: | Used by | Accessed component | Service | Purpose | Message format | | --------------- | ------------------ | ------------------ | -------------------------------------------------- | -------------- | @@ -567,50 +567,50 @@ Following are APIs used by the Project management application: *How does it work? (What do users need to know about architecture an internal components?)* - HAL is a standard to define resources with embedding and links between them -- HAL contains action links depending on the user’s permissions, allows to derive allowed actions from object keys in json +- HAL contains action links depending on the user’s permissions, allows permitted actions to be derived from object keys in json -*What knowledge prerequisites for the developer before using the API?* +*What knowledge should the developer have before using the API?* - Knowledge of REST - (Optional) Knowledge of HAL standard -*Any extensions or APIs in development or in planning users should know about?* +*Are there any extensions or APIs in (or planned for) development that users should know about?* - Signaling to receive only selected attributes/nested resources from the API for performance improvements ## BCF API -| Name | BCF API | -| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Purpose | Implementation of subset of [BCF](https://en.wikipedia.org/wiki/BIM_Collaboration_Format) standard for [BIM](https://en.wikipedia.org/wiki/Building_information_modeling) projects | -| Versioning | URL based versioning scheme, e.g. `/api/bcf/2.1` | -| Authentication | OAuth2 | -| In openDesk provided by | OpenProject | -| Transport protocol | HTTP(S) | -| Usage within component | none | -| Usage within openDesk | none | -| Usage for external integration | none | -| Parallel access | Allowed | -| Message protocol | JSON | -| Supported standards | [BCF 2.1](https://github.com/buildingSMART/BCF-API/blob/release_2_1/README.md) | -| Documentation | https://www.openproject.org/docs/api/bcf-rest-api/ | +| Name | BCF API | +| ------------------------------ |--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Purpose | Implementation of a subset of [BCF](https://en.wikipedia.org/wiki/BIM_Collaboration_Format) standard for [BIM](https://en.wikipedia.org/wiki/Building_information_modeling) projects | +| Versioning | URL based versioning scheme, e.g. `/api/bcf/2.1` | +| Authentication | OAuth2 | +| In openDesk provided by | OpenProject | +| Transport protocol | HTTP(S) | +| Usage within component | none | +| Usage within openDesk | none | +| Usage for external integration | none | +| Parallel access | Allowed | +| Message protocol | JSON | +| Supported standards | [BCF 2.1](https://github.com/buildingSMART/BCF-API/blob/release_2_1/README.md) | +| Documentation | https://www.openproject.org/docs/api/bcf-rest-api/ | # Video Conferencing - Jitsi ## IFrame API -| Name | IFrame API | -| ------------------------------ | ---------------------------------------------------------------------- | -| Purpose | Embed Jitsi video conferencing features into existing application/site | -| Versioning | Identical to the Jitsi release version | -| Authentication | Optional (JWT-based authentication in openDesk context) | -| In openDesk provided by | Jitsi-Web | -| Transport protocol | HTTP(S) | -| Usage within component | none | -| Usage within openDesk | Used by Element (Chat Web-UI) | -| Usage for external integration | none | -| Parallel access | Allowed | -| Message protocol | | -| Supported standards | | -| Documentation | https://jitsi.github.io/handbook/docs/dev-guide/dev-guide-iframe/ | +| Name | IFrame API | +| ------------------------------ |--------------------------------------------------------------------------| +| Purpose | Embed Jitsi video conferencing features into existing applications/sites | +| Versioning | Identical to the Jitsi release version | +| Authentication | Optional (JWT-based authentication in openDesk context) | +| In openDesk provided by | Jitsi-Web | +| Transport protocol | HTTP(S) | +| Usage within component | none | +| Usage within openDesk | Used by Element (Chat Web-UI) | +| Usage for external integration | none | +| Parallel access | Allowed | +| Message protocol | | +| Supported standards | | +| Documentation | https://jitsi.github.io/handbook/docs/dev-guide/dev-guide-iframe/ | ## lib-jitsi-meet API @@ -704,7 +704,7 @@ classDiagram JitsiVideoConference *-- JitsiMeetReactSdk ``` -Following are APIs used by the Chat application: +The following are the APIs used by the Chat application: | Used by | Accessed component | Service | Purpose | Message format | | --------------- | ------------------ | ------------------ | -------------------------------------------------- | -------------- | @@ -748,8 +748,8 @@ Following are APIs used by the Chat application: ## Matrix Server-Server API | Name | Matrix Server-Server API | -| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | -| Purpose | Communication between Matrix server (also known as FederationAPIs) | +| ------------------------------ |----------------------------------------------------------------------------------------------------------------------------------------------| +| Purpose | Communication between Matrix servers (also known as FederationAPIs) | | Versioning | URL based with version bumps on breaking changes (e.g. `/_matrix/federation/v2`) | | Authentication | HTTP-Authorization header with Bearer token | | In openDesk provided by | Synapse | @@ -866,7 +866,7 @@ Following are APIs used by the Chat application: # Knowledge management - XWiki -Following are APIs used by the Knowledge management application: +The following are the APIs used by the Knowledge management application: | Used by | Accessed component | Service | Purpose | Message format | | ------- | ------------------ | ------------------ | -------------------------------------------------- | -------------- | @@ -877,8 +877,8 @@ Following are APIs used by the Knowledge management application: ## REST API | Name | REST API | -| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Purpose | Perform low level action, e.g. interact with XWiki stored data | +| ------------------------------ |------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Purpose | Perform low-level actions, e.g. interact with XWiki stored data | | Versioning | | | Authentication | Anonymous or username/password on each request (stateless) | | In openDesk provided by | XWiki | @@ -897,7 +897,7 @@ Following are APIs used by the Knowledge management application: | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Purpose | Feature-rich API to access any module, use any functionality, modify existing functionality; allows definition of new REST API endpoints - API scope is identical to Java API | | Versioning | | -| Authentication | Executed in context of (authenticated) user or anonymous - permissions (scripting rights, programming rights) of that context apply | +| Authentication | Performed in the context of an (authenticated) user or anonymously - permissions (scripting rights, programming rights) of that context apply | | In openDesk provided by | XWiki | | Transport protocol | | | Usage within component | | @@ -914,7 +914,7 @@ Following are APIs used by the Knowledge management application: | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Purpose | Feature-rich API to access any module, use any functionality, modify existing functionality; allows definition of new REST API endpoints - API scope is identical to Scripting API | | Versioning | | -| Authentication | Executed in context of (authenticated) user or anonymous - but without the permission check (in opposite to the Scripting API) | +| Authentication | Performed in the context of an (authenticated) user or anonymously - but without the permission check (in contrast to the Scripting API) | | In openDesk provided by | XWiki | | Transport protocol | | | Usage within component | | @@ -931,7 +931,7 @@ Following are APIs used by the Knowledge management application: | ------------------------------ | -------------------------------------------------------------------------------------------- | | Purpose | Include dynamic components in XWiki/web pages | | Versioning | | -| Authentication | Executed in context of (authenticated) user or anonymous | +| Authentication | Performed in the context of an (authenticated) user or anonymously | | In openDesk provided by | Jitsi | | Transport protocol | | | Usage within component | | diff --git a/docs/ci.md b/docs/ci.md index d3d58b4b..b7772a25 100644 --- a/docs/ci.md +++ b/docs/ci.md @@ -16,7 +16,7 @@ This page covers openDesk deployment automation via Gitlab CI. The project includes a `.gitlab-ci.yml` that allows you to execute the deployment from a GitLab instance of your choice. -When starting the pipeline through the GitLab UI, you will be queried for some variables plus the following ones: +When starting the pipeline through the GitLab UI, you will be queried for some variables, including the following: - `DOMAIN`: The primary domain for your deployment, making the openDesk services available, e.g., as `https://portal.DOMAIN`. - `MAIL_DOMAIN` (optional): The domain for the users' email addresses; it defaults to `DOMAIN`. @@ -24,7 +24,7 @@ When starting the pipeline through the GitLab UI, you will be queried for some v - `NAMESPACE`: Namespace of your K8s cluster openDesk will be installed. - `MASTER_PASSWORD_WEB_VAR`: Overwrites value of `MASTER_PASSWORD`. -You might want to set credential variables in the GitLab project at `Settings` > `CI/CD` > `Variables`. +You might want to set credential variables in the GitLab project at `Settings` > `CI/CD` > `Variables`, the values of which can then be hidden from output logs. # Tests @@ -32,8 +32,8 @@ The GitLab CI pipeline contains a job named `run-tests` that can trigger a test For the trigger to work, the variable `TESTS_PROJECT_URL` has to be set on this GitLab project's CI variables, which can be found at `Settings` -> `CI/CD` -> `Variables`. The variable should have this format: `/api/v4/projects/`. -To select the current test set, use the variable `TESTS_TESTSET`. Default: `Smoke`. +To select the current test suite, use the variable `TESTS_TESTSET`. Default: `Smoke`. If the branch of the test pipeline is not `main`, this can be set with the `.gitlab-ci.yml` variable `TESTS_BRANCH` while creating a new pipeline. -The variable `testprofile` within the job is set to `Namespace`, which tells the e2e tests to use environment-specific settings that will be read from the cluster and namespace-specific file to be found in the project internal `opendesk-env` repository. +The variable `testprofile` within the job is set to `Namespace`, which tells the e2e tests to use environment-specific settings that will be read from the cluster and namespace-specific file which is found in the project internal `opendesk-env` repository. diff --git a/docs/data-storage.md b/docs/data-storage.md index b74c5d3c..b8adfe1e 100644 --- a/docs/data-storage.md +++ b/docs/data-storage.md @@ -18,7 +18,7 @@ following subsection. The provided diagram shows all relevant openDesk applications on the left and their utilized data storages on the right. For more detailed information about each -application refer to the table show in Section [Details](#details) +application refer to the table in [Details](#details). ```mermaid --- diff --git a/docs/debugging.md b/docs/debugging.md index c8a94e7b..618c0c4b 100644 --- a/docs/debugging.md +++ b/docs/debugging.md @@ -24,7 +24,7 @@ SPDX-License-Identifier: Apache-2.0 # Disclaimer -This document collects information on how to deal with debugging an openDesk deployment. +This document collects information on how to go about debugging an openDesk deployment. It will be extended over time as we deal with debugging cases. @@ -38,7 +38,7 @@ environments, you should use them thoughtfully and carefully if needed. # Enable debugging -Check the openDesk [`debug.yaml.gotmpl`](../helmfile/environments/default/debug.yaml.gotmpl) and set for your deployment +Check the openDesk [`debug.yaml.gotmpl`](../helmfile/environments/default/debug.yaml.gotmpl) and configure it for your deployment ``` debug: enabled: true @@ -47,13 +47,13 @@ debug: This will result in: - setting most component's log level to debug - making the Keycloak admin console available by default at `https://id./admin/` -- configured the ingress for `http://minio-console.` +- ingress for `http://minio-console.` being configured > **Note**
> When enabling debug mode and updating your deployment, you must manually delete all jobs before updating. In debug mode, we keep the jobs, and some job fields are immutable, leading to a deployment failure. > **Note**
-> All containers should write their log output to STDOUT; if you find (valuable) logs inside a container, please let us know! +> All containers should write their log output to STDOUT; if you find (valuable) logs inside a container which were not in STDOUT, please let us know! # Adding containers to a pod for debugging purposes @@ -63,13 +63,13 @@ This can be a challenge the more security-hardened the container images are beca Adding a container to a Pod can ease the pain. -Below are some wrap-up notes on debugging openDesk by adding debug containers. Of course, there are many more detailed resources out there. +Below are some brief notes on debugging openDesk by adding debug containers. Of course, there are many more detailed resources out there. ## Adding a container to a pod/deployment - Dev/Test only You can add a container by editing and updating an existing deployment, which is quite comfortable with tools like [Lens](https://k8slens.dev/). -- Select the container you want to make use of as a debugging container; in the example below, it is `registry.opencode.de/bmi/opendesk/components/platform-development/images/opendesk-debugging-image:latest`. +- Select the container you want to use as a debugging container; in the example below, it is `registry.opencode.de/bmi/opendesk/components/platform-development/images/opendesk-debugging-image:latest`. - Ensure the `shareProcessNamespace` option is enabled for the Pod. - Reference the selected container within the `containers` array of the deployment. - If you want to access another container's filesystem, ensure both containers' user/group settings match. @@ -98,29 +98,29 @@ The following example can be used to debug the `openDesk-Nextcloud-PHP` containe ``` - After the deployment has been reloaded, open the shell of the debugging container. -- When you've succeeded, you will see the processes of both/all containers in the Pod when doing a `ps aux`. +- When you've succeeded, you will see the processes of both/all containers in the Pod when executing `ps aux`. - To access other containers' filesystems, select the PID of a process from the other container and do a `cd /proc//root`. ## Temporary/ephemeral containers -An interesting read we picked most of the details below from: https://iximiuz.com/en/posts/kubernetes-ephemeral-containers/ +An interesting read from which we picked most of the details below from: https://iximiuz.com/en/posts/kubernetes-ephemeral-containers/ Sometimes, you do not want to add a container permanently to your existing deployment. In that case, you could use [ephemeral containers](https://kubernetes.io/docs/concepts/workloads/pods/ephemeral-containers/). -For the commands further down this section, we set some environment variables first: +For the commands further down this section, we need to set some environment variables first: - `NAMESPACE`: The namespace in which the Pod you want to inspect is running. -- `DEPLOYMENT_NAME`: The deployment's name responsible for spawning the Pod you want to inspect within the pre-mentioned namespace. -- `POD_NAME`: The name of the Pod you want to inspect within the pre-mentioned namespace. -- `EPH_CONTAINER_NAME`: Choose the name for the container, and "debugging" seems obvious. +- `DEPLOYMENT_NAME`: The deployment's name responsible for spawning the Pod you want to inspect within the aforementioned namespace. +- `POD_NAME`: The name of the Pod you want to inspect within the aforementioned namespace. +- `EPH_CONTAINER_NAME`: The name of your debugging container, "debugging" seems obvious. - `DEBUG_IMAGE`: The image you want to use for debugging purposes. e.g. ```shell -export EPH_CONTAINER_NAME=debugging export NAMESPACE=my_test_deployment export DEPLOYMENT_NAME=opendesk-nextcloud-php export POD_NAME=opendesk-nextcloud-php-6686d47cfb-7642f +export EPH_CONTAINER_NAME=debugging export DEBUG_IMAGE=registry.opencode.de/bmi/opendesk/components/platform-development/images/opendesk-debugging-image:latest ``` @@ -147,7 +147,7 @@ kubectl -n ${NAMESPACE} attach -it -c ${EPH_CONTAINER_NAME} ${POD_NAME} ## Helmfile -When refactoring the Helmfile structure you want to ensure that there are not unintended mistakes by e.g. `diff` +When refactoring the Helmfile structure, you want to ensure that there are no unintended edits by executing e.g. `diff` and comparing the output of Helmfile from before and after the change by calling: ```shell @@ -156,9 +156,9 @@ helmfile template -e dev >output_to_compare.yaml ## MariaDB -When using the openDesk bundled MariaDB, you can explore the database(s) using the MariaDB interactive terminal from the Pod's command line: `mariadb -u root -p`. On the password prompt, provide the value for `MARIADB_ROOT_PASSWORD` found in the Pod's environment. +When using the openDesk bundled MariaDB, you can explore the database(s) using the MariaDB interactive terminal from the Pod's command line: `mariadb -u root -p`. On the password prompt, provide the value for `MARIADB_ROOT_PASSWORD` which can be found in the Pod's environment. -While you will find all the details for the CLI tool in [the online documentation](https://mariadb.com/kb/en/mariadb-command-line-client/), some quick commands are: +While you will find all the details for the CLI tool in the [MariaDB documentation](https://mariadb.com/kb/en/mariadb-command-line-client/), some commonly used commands are: - `help`: Get help on the psql command set - `show databases`: Lists all databases @@ -190,7 +190,7 @@ end Using the openDesk bundled PostgreSQL, you can explore database(s) using the PostgreSQL interactive terminal from the Pod's command line: `psql -U postgres`. -While you will find all details in the [psql subsection](https://www.postgresql.org/docs/current/app-psql.html)) of the PostgreSQL documentation, some quick commands are: +While you will find all details about the cli tool `psql` in the [PostgreSQL documentation](https://www.postgresql.org/docs/current/app-psql.html)), some commonly used commands are: - `\?`: Get help on the psql command set - `\l`: Lists all databases @@ -202,10 +202,9 @@ While you will find all details in the [psql subsection](https://www.postgresql. ### Setting the log level -Keycloak is the gateway to integrate other authentication management systems or applications. It can be desired to -avoid enabling debug mode for the whole platform when you just need to look into Keycloak. +Keycloak is the gateway to integrate other authentication management systems or applications. It is undesirable to enable debug mode for the whole platform if you just need to look into Keycloak. -That can easily be achieved in two steps: +Enabling debugging mode for Keycloak can easily be achieved in two steps: 1. Updating the value for `KC_LOG_LEVEL` in the related configmap `ums-keycloak`. ```shell @@ -217,7 +216,7 @@ kubectl patch -n ${NAMESPACE} configmap ${CONFIGMAP_NAME} --type merge -p '{"dat 2. Restart the Keycloak Pod(s). > **Note**
-> As the `ums-keycloak-extensions-handler` is performing frequent (one per second) requests to Keycloak for retrieval of the Keycloak event history, you might want to stop/remove the deployment while debugging/analysing Keycloak to not get your debug output spammed by these requests. +> Because the `ums-keycloak-extensions-handler` is sending frequent requests (one per second) to Keycloak for retrieval of the Keycloak event history, you might want to stop/remove the deployment while debugging/analysing Keycloak to not get your debug output spammed by these requests. ### Accessing the Keycloak admin console diff --git a/docs/development.md b/docs/development.md index 49de538a..95d3868c 100644 --- a/docs/development.md +++ b/docs/development.md @@ -6,7 +6,7 @@ SPDX-License-Identifier: Apache-2.0

Developing openDesk deployment automation

-Active development on the deployment is currently only available for project members. +Active development on the deployment is currently only available to project members. However, contributions are possible using the [CLA](https://gitlab.opencode.de/bmi/opendesk/info/-/blob/main/CONTRIBUTING.md?ref_type=heads) process. @@ -30,7 +30,7 @@ developing the openDesk platform. ```mermaid flowchart TD J[helmfile.yaml.gotmpl\nor a helmfile outside of this repository]-->A - J-->K[./helmfile/environemnts/*your_environment*/values.yaml.gotmpl\nor any an environment values file] + J-->K[./helmfile/environemnts/*your_environment*/values.yaml.gotmpl\nor another environment values file] A[./helmfile_generic.yaml.gotmpl]-->B[./helmfile/apps/*all_configured_apps*/helmfile.yaml.gotmpl\nReferences the relevant app Helm\ncharts using details from 'charts.yaml.gotmpl'] B-->C[./values-*all_configured_components*.yaml.gotmpl\nValues to template the charts\nwith references to the `images.yaml.gotmpl`] A-->D[./helmfile/environments/default/*\nwith just some examples below] @@ -57,20 +57,15 @@ Before you investigate any app-specific configuration, it is recommended that yo # Default branch, `develop` and other branches -The `main` branch is configured to be the default branch, as visitors of the project on openCode should see that +The `main` branch is configured to be the default branch, as visitors to the project on openCode should see that branch by default. Please use the `develop` branch to diverge your branch(es) from. See the [workflow guide](./docs/workflow.md) for more details on naming conventions. -There is a CI bot that automatically creates a merge request once you initially push your branch to openCode. -Of course, the merge request will target the `develop` branch, be in status `draft`, and you are set as the assignee. - -If you do not plan to merge from the branch you have pushed, please close the auto-created MR. - # External artifacts - `charts.yaml.gotmpl` and `images.yaml.gotmpl` -The `charts.yaml.gotmpl` and `images.yaml.gotmpl` files are the central place to reference external artifacts used for the deployment. +The `charts.yaml.gotmpl` and `images.yaml.gotmpl` files are the central place to reference any external artifacts used for the deployment. Besides the deployment automation itself, some tools work with the contents of the files: @@ -83,11 +78,11 @@ Please find details on these tools below. ## Linting In the project's CI, there is a step dedicated to lint the two yaml files, as we want them to be in -- alphabetical order regarding the components and -- in a logical order regarding the non-commented lines (registry > repository > tag). +- alphabetical order regarding the components +- logical order regarding the non-commented lines (registry > repository > tag). In the linting step, the [openDesk CI CLI](https://gitlab.opencode.de/bmi/opendesk/tooling/opendesk-ci-cli) is used to apply the -just mentioned sorting, and the result is compared with the unsorted version. If there is a delta, the linting fails, and you can fix it by running the CLI tool locally, verifying and applying the result to your branch. +aforementioned sorting, and the result is compared with the unsorted version. If there is a delta, the linting fails, and you can fix it by running the CLI tool locally, verifying and applying the result to your branch. > **Note**
> Please ensure that in component blocks, you use comments only at the beginning of the block or at its end. Ideally, you stick @@ -140,11 +135,11 @@ configured to pull artifacts that do not originate from openCode into projects c The mirror script takes the information on what artifacts to mirror from the annotation inside the two yaml files: - `# upstreamRegistry` *required*: To identify the source registry -- `# upstreamRegistryCredentialId`: *optional*: In case the source registry is not public, the access credentials have to be specified as ENV variables containing the value of this key in their name, so you want to specify that key all uppercase: -  - `MIRROR_CREDENTIALS_SRC__USERNAME` -  - `MIRROR_CREDENTIALS_SRC__PASSWORD` +- `# upstreamRegistryCredentialId`: *optional*: In case the source registry is not public, the access credentials have to be specified as environment variables and contain the value of this key in their name, so you want to specify the key in uppercase: + - `MIRROR_CREDENTIALS_SRC__USERNAME` + - `MIRROR_CREDENTIALS_SRC__PASSWORD` - `# upstreamRepository` *required*: To identify the source repository -- `# upstreamMirrorTagFilterRegEx` *required*: If this annotation is set, the mirror for the component will be activated. Only tags that match the given regular expression are being mirrored. **Note:** You must use single quotes for this attribute's value if you use backslash leading regex notation like `\d`. +- `# upstreamMirrorTagFilterRegEx` *required*: If this annotation is set, the mirror for the component will be activated. Only tags that match the given regular expression will be mirrored. **Note:** You must use single quotes for this attribute's value if you use backslash leading regex notation like `\d`. - `# upstreamMirrorStartFrom` *optional*: Array of numeric values in case you want to mirror only artifacts beginning with a specific version. You must use capturing group in `# upstreamMirrorTagFilterRegEx` to identify the single numeric elements of the version within the tag and use per capturing group (left to right) one numeric array element here to define the version the mirror should start with. @@ -163,4 +158,4 @@ for Helm charts. You may also want to make use of our [standard CI](https://gitlab.opencode.de/bmi/opendesk/tooling/gitlab-config) to quickly get Helm charts and container images that are signed, linted, scanned, and released. -Check out the `.gitlab-ci.yaml` files in the project's [Charts](https://gitlab.opencode.de/bmi/opendesk/components/platform-development/charts) or [Images](https://gitlab.opencode.de/bmi/opendesk/components/platform-development/images) to get an idea how little you need to do yourself. +Check out the `.gitlab-ci.yaml` files in the project's [Charts](https://gitlab.opencode.de/bmi/opendesk/components/platform-development/charts) or [Images](https://gitlab.opencode.de/bmi/opendesk/components/platform-development/images) to get an idea just how little you need to do by yourself. diff --git a/docs/enhanced-configuration.md b/docs/enhanced-configuration.md index 342008ce..816165c0 100644 --- a/docs/enhanced-configuration.md +++ b/docs/enhanced-configuration.md @@ -7,7 +7,7 @@ SPDX-License-Identifier: Apache-2.0 # Overview -The following enhanced configuration use cases are described in separate documents. +The following enhanced configuration use cases are described in their respective documents: - [Separate mail & Matrix domain](./enhanced-configuration/separate-mail-matrix-domain.md) - [Federation with external identity provider](./enhanced-configuration/idp-federation.md) diff --git a/docs/enhanced-configuration/gitops.md b/docs/enhanced-configuration/gitops.md index f0bfa2f6..d46f36ac 100644 --- a/docs/enhanced-configuration/gitops.md +++ b/docs/enhanced-configuration/gitops.md @@ -25,7 +25,7 @@ This documentation will use Argo CD to explain how to deploy openDesk GitOps-sty # ArgoCD We are continuously improving our Argo CD support, please share you experience with Argo CD deployments e.g. by [creating -at ticket](https://gitlab.opencode.de/bmi/opendesk/deployment/opendesk/-/issues). +a ticket](https://gitlab.opencode.de/bmi/opendesk/deployment/opendesk/-/issues). There are two options to deploy openDesk via Argo CD described in the following sections. @@ -42,19 +42,19 @@ References: - [Helmfile CLI documentation](https://helmfile.readthedocs.io/en/latest/#cli-reference) - [Generate K8s YAML Manifests for openDesk](https://gitlab.opencode.de/bmi/opendesk/deployment/options/generate-k8s-yaml-manifests) -Afterwards, you can use the resulting manifests within an standard Argo CD workflow. +Afterwards, you can use the resulting manifests within a standard Argo CD workflow. > **Note**
-> When creating the Argo CD application based on the resulting manifests you must not use the `Automated Sync Policy` +> When creating the Argo CD application based on the resulting manifests, you must not use the `Automated Sync Policy` > offered by Argo CD, as you have to manually ensure the applications are updated in the required sequence. ## Option 2: Helmfile plugin -It is possible to deploy openDesk via Argo CD with community developed +It is possible to deploy openDesk via Argo CD with the community developed [Helmfile plugin](https://github.com/travisghansen/argo-cd-helmfile). You can find an example for this approach in the [Argo CD Deployments](https://gitlab.opencode.de/bmi/opendesk/deployment/options/argocd-deploy) repository. It contains an example Helm chart (`opendesk-parent`) to create Argo CD Applications via a Helm chart (`opendesk`) -according to `app of apps pattern` and is using sync waves to ensure to required deployment and update sequence -for openDesk is met. +according to `app of apps pattern`. It uses sync waves to ensure the deployment matches requirements and the update sequence +for openDesk is satisfied. diff --git a/docs/enhanced-configuration/groupware-migration.md b/docs/enhanced-configuration/groupware-migration.md index c6a6cd95..e53baf09 100644 --- a/docs/enhanced-configuration/groupware-migration.md +++ b/docs/enhanced-configuration/groupware-migration.md @@ -21,11 +21,11 @@ SPDX-License-Identifier: Apache-2.0 Most organizations already have email accounts on various platforms that need to be migrated to openDesk. This document describes the migration from M365 accounts to openDesk using the [audriga Migration Service](https://www.audriga.com) in combination with the master authentication option in openDesk. Other source platforms are also supported, and their migrations work in a similar manner. -The migration can be configured on audriga's self-service website, accessed with most common web browsers (e.g. IE, Firefox, Safari or Chrome). No software needs to be installed on your machine. The service connects to your mailbox similarly to what your email client does. Emails, attachments, folders, and, depending on the source systems, contacts, tasks, notes, and calendar data are being copied to your destination account. See [M365 to OX Migration Guide](https://audriga.com/fileadmin/guides/en/MS365-OX.pdf) for the scope and limitations of the process. +The migration can be configured on audriga's self-service website, accessed with most common web browsers (e.g. IE, Firefox, Safari or Chrome). No software needs to be installed on your machine. The service connects to your mailbox similarly to what your email client does. Emails, attachments, folders, and, depending on the source systems, contacts, tasks, notes, and calendar data are copied to your destination account. See [M365 to OX Migration Guide](https://audriga.com/fileadmin/guides/en/MS365-OX.pdf) for the scope and limitations of the process. The data in the source mailbox will not be deleted or altered. To configure a migration, only three simple steps in audriga's self-service portal have to be completed. After the migration has started, its status can be continuously monitored on the website. -It may not be possible to complete especially large or complex migrations with only this guide. If you identify issues related to I/O, bandwidth, timeline constraints, or anything else that makes the migration more complicated than you feel comfortable handling on your own using the self-service, please get in touch with contact [audriga's support](mailto:support@audriga.com). +It may not be possible to complete especially large or complex migrations with only this guide. If you identify issues related to I/O, bandwidth, time constraints, or anything else that makes the migration more complicated than you are comfortable handling on your own using the self-service, please contact [audriga's support](mailto:support@audriga.com). # Prerequisites @@ -33,7 +33,7 @@ It may not be possible to complete especially large or complex migrations with o The following instructions provide information on how to authenticate Microsoft 365 / Exchange Online accounts in the audriga migration service with "modern authentication" using a service account without the need to provide a username and password for each mailbox that will be migrated. -You will have to select an existing user account that will be used as a service account for the migration. You have to register the audriga application and create an M365 email group known only to you as described in the following steps: +You will have to select an existing user account that will be used as a service account for the migration. You have to register the audriga application and create an M365 email group known only to you, as described in the following steps: ***1. Select one account to serve as a service account*** @@ -49,7 +49,7 @@ To register the audriga app in your tenant, log into your admin account and acce https://login.microsoftonline.com/organizations/v2.0/adminconsent?client_id=3cd27a72-a19e-4945-9715-fc24d940428f&redirect_uri=https://umzug.audriga.com/SMESwitchWebApp/oauth_complete.jsp&scope=https://outlook.office.com/.default - Accept the App "audriga CloudMovr migration" -- You will be redirected to an audriga page, which you can close without requiring additional interaction. +- You will be redirected to an audriga page, which you can close - it does not require additional interaction. > **Note**
> The audriga application is created under the "Enterprise application" tab in the AzureAD console. @@ -70,7 +70,7 @@ In openDesk, you have to have all user accounts with mailboxes pre-defined befor ## Deploy openDesk with master authentication -With openDesk 1.0 Enterprise, you can set openDesk's email components (OX AppSuite and OX Dovecot) into master authentication mode to run the migration as described in this document using the following two settings for your deployment: +With openDesk 1.0 Enterprise, you can set openDesk's email components (OX AppSuite and OX Dovecot) to master authentication mode to run the migration as described in this document using the following two settings for your deployment: ``` secrets: @@ -82,13 +82,13 @@ functional: enabled: true ``` -1. You must specify the master password referenced in the document's following sections. +1. You must specify a master password, it will be referenced later in this document. 2. You need to enable the actual master authentication mode. Updating your deployment with these settings will allow you to continue with the migration scenario. Once the migration is completed, you can remove `secrets.oxAppSuite.adminPassword` and need to turn off the migration mode by setting `functional.migration.oxAppSuite.enabled` to `false` or removing that setting, as `false` is the default before you update your deployment once again. > **Note**
-> For the changes to take effect, it is sufficient to deploy the `open-xchange` component. +> For the changes to take effect, it is sufficient to re-deploy the `open-xchange` component alone. > **Note**
> While in master authentication mode, regular users cannot log in to the webmail module of openDesk or access the mail using IMAP, as it is not recommended that users interact with the target mail infrastructure during the migration scenario described in this document. @@ -110,12 +110,12 @@ Configure openDesk as your destination server: - Select "Configure provider or server" in the provider selection box of the migration application. - In the following dialog, select "Open-Xchange" as protocol. - On the tab "IMAP" -  - For "Mailserver (host name or IP address)" enter your IMAP host, e.g. "webmail.your-opendesk-domain.tld". -  - If your IMAP server is not running on default port 993, enter your nonstandard IMAP port under Details -> Port. -  - Press check. + - For "Mailserver (host name or IP address)" enter your IMAP host, e.g. "webmail.your-opendesk-domain.tld". + - If your IMAP server is not running on default port 993, enter your nonstandard IMAP port under Details -> Port. + - Press check. - On the tab "Open-Xchange" -  - Set the hostname of your OX AppSuite installation, e.g. "webmail.your-opendesk-domain.tld". -  - Press check. + - Set the hostname of your OX AppSuite installation, e.g. "webmail.your-opendesk-domain.tld". + - Press check. - If you receive a green checkmark on both tabs, click "Save". Otherwise, check your settings until you get the green checkmark. ## Adding accounts @@ -142,7 +142,7 @@ Click on check to verify the credentials. If the data is correct, a green checkm After checking and confirming, you can use the same procedure to add further mailboxes. -Alternatively, you can add multiple accounts via CSV upload. Find information in the following. +Alternatively, you can add multiple accounts via CSV upload. More info on that below. ### Add multiple user accounts via CSV file diff --git a/docs/enhanced-configuration/idp-federation.md b/docs/enhanced-configuration/idp-federation.md index e279c9c5..e06d0a53 100644 --- a/docs/enhanced-configuration/idp-federation.md +++ b/docs/enhanced-configuration/idp-federation.md @@ -20,19 +20,21 @@ SPDX-License-Identifier: Apache-2.0 * [openDesk IdP](#opendesk-idp) -Most organizations already have an Identity and Access Management (IAM) system with an identity provider (IdP) for single sign-on to internal or external web applications. +Most organizations already have an Identity and Access Management (IAM) system with an identity provider (IdP) for single sign-on (SSO) to internal or external web applications. -This document shows how to configure your organization's IdP and the openDesk IdP to support account federation with openDesk single sign-on based on your organization's login. +This document explains how to configure your organization's IdP and the openDesk IdP to support account federation with openDesk SSO based on your organization's login. # References -We would like to list successful IdP federation scenarios, so we are also happy about input from the community: +We would like to list successful IdP federation scenarios: | External IdP | openDesk versions tested | |---------------------------------------------------------------------|--------------------------| | [EU Login](https://webgate.ec.europa.eu/cas/userdata/myAccount.cgi) | v0.9.0, v1.2.0 | | [ProConnect](https://www.proconnect.gouv.fr/) | v0.9.0 | +>If you have successfully federated using another External IdP, please let us know so we can update the list above. + # Prerequisites ## User accounts @@ -58,7 +60,7 @@ In addition to the configuration, it is required that user accounts with the sam - This feature is currently unavailable in openDesk's Keycloak, but Univention plans to make it available in the future. - Ad-hoc provisioning creates a user account on the fly during a user's first login. - While ad-hoc provisioning is an excellent approach for a quick start with openDesk, it has various downsides: - - Users are created after their first login, so you cannot find your colleagues in the openDesk apps unless they have already logged in. + - Users are created after their first login, so you cannot find your colleagues in the openDesk apps unless they have already logged in once. - A user account would never be deactivated or deleted in openDesk. - Group memberships are not transferred. @@ -70,7 +72,7 @@ This document focuses on the OIDC federation between an external IdP and the ope ## Versions -The example was tested with openDesk v0.7.0 using its integrated Keycloak v24.0.3. As external IdP, we also used an openDesk deployment of the same version but created a separate realm for proper configuration separation. +The example was tested with openDesk v0.7.0 using its integrated Keycloak v24.0.3. As external IdP, we also used an openDesk deployment of the same version, but created a separate realm for proper configuration separation. ## Example values @@ -85,7 +87,7 @@ The following values are used in this example documentation. Please ensure when ## Keycloak admin console access -To access Keycloak's admin console in an openDesk deployment, you must add a route for `/admin` to the Keycloak's ingress. This is done automatically if you deploy openDesk with `debug.enabled: true`, but beware that this will also cause a lot of log output across all openDesk pods. +To access the Keycloak admin console in an openDesk deployment, you must add a route for `/admin` to the Keycloak ingress. This is done automatically if you deploy openDesk with `debug.enabled: true`, but beware that this will also cause a lot of log output across all openDesk pods. The admin console will be available at: - Organization's IdP: https://idp.organization.tld/admin/master/console/ @@ -97,7 +99,7 @@ For the following configuration steps, log in with user `kcadmin` and grab the p In this example, we use the Keycloak of another openDesk instance to simulate your organization's IdP. However, URL paths differ if you use another product. -Please let us know about your experiences or differences you came across. +Please let us know about your experiences or any differences you encountered. ### Separate realm @@ -115,7 +117,7 @@ If you just created the `fed-test-idp-realm`, you are already in the admin scree - Client create wizard page 1: - *Client type*: `OpenID Connect` - *Client-ID*: `opendesk-federation-client` - - *Name*: `openDesk @ your organization` (is the descriptive text of the client that might show up in your IdP's UI and therefore should explain what the client is used for) + - *Name*: `openDesk @ your organization` (this is the descriptive text of the client that might show up in your IdP's UI and therefore should explain what the client is used for) - Client create wizard page 2: - *Client authentication*: `On` - *Authorization*: `Off` (default) @@ -124,7 +126,7 @@ If you just created the `fed-test-idp-realm`, you are already in the admin scree - `Direct access grants` - Client create wizard page 3: - *Valid Redirect URLs*: `https://id.opendesk.tld/realms/opendesk/broker/auto-federate-idp/endpoint` - - When completed with *Save*, you get to the detailed client configured that also needs some updates: + - When completed with *Save*, you get to the detailed client configuration that also needs some updates: - Tab *Settings* > Section *Logout settings* - *Front channel logout*: `Off` - *Back channel logout URL*: `https://id.opendesk.tld/realms/opendesk/protocol/openid-connect/logout/backchannel-logout` @@ -152,9 +154,9 @@ The following configuration is taking place in the Keycloak realm `opendesk`. - *Client authentication*: `Client secret sent as post` (default) - *Client ID*: Use the client ID you took from your organization's IdP config (`opendesk-federation-client` in this example) - *Client Secret*: Use the secret you took from your organization's IdP config - - When completed with *Add*, you get to the detailed IdP configuration that at least needs some the following update: + - When completed with *Add*, you get to the detailed IdP configuration which at least needs the following update: - *First login flow override*: `auto-federate-flow` - - Depending on your organizations IdP and process preferences additional setting may be required + - Depending on your organizations IdP and process preferences, additional configuration may be required - In case you want to forcefully redirect all users to your organization's IdP (disabling login with local openDesk accounts): - *Authentication* > `2fa-browser` diff --git a/docs/enhanced-configuration/matrix-federation.md b/docs/enhanced-configuration/matrix-federation.md index 27249371..a5cdd367 100644 --- a/docs/enhanced-configuration/matrix-federation.md +++ b/docs/enhanced-configuration/matrix-federation.md @@ -12,7 +12,7 @@ SPDX-License-Identifier: Apache-2.0 The Element chat application and its server component Synapse are based on the Matrix protocol, -that supports federation with other Matrix servers to communicate with the users with accounts on these servers. +which supports federation with other Matrix servers, allowing communication with the users with accounts on these servers. By default, you can chat with users who have an account within your openDesk installation and federate with other matrix-based servers. @@ -35,15 +35,15 @@ The following setting can turn off federation: ```yaml functional: -  externalServices: -    matrix: -      federation: -        enabled: false + externalServices: + matrix: + federation: + enabled: false ``` ## Separate Matrix domain -If you want to federate with other Matrix instances and use a separate Matrix domain, you need to provide a JSON file on +If you want to federate with other Matrix instances and use a separate Matrix domain, you need to provide a JSON file for the Matrix domain to use delegation. It is not part of your openDesk deployment. Domain path: `https://my_organization.tld/.well-known/matrix/server` @@ -51,9 +51,9 @@ Domain path: `https://my_organization.tld/.well-known/matrix/server` Content: ```JSON { -    "m.server": "matrix-federation.opendesk.domain.tld:443" + "m.server": "matrix-federation.opendesk.domain.tld:443" } ``` -More detailed information can be found in Matrix/Synapse documentation: +More detailed information can be found in the Matrix/Synapse documentation: [Matrix Delegation](https://element-hq.github.io/synapse/latest/delegate.html) diff --git a/docs/enhanced-configuration/self-signed-certificates.md b/docs/enhanced-configuration/self-signed-certificates.md index e3c6dc27..d15c3cae 100644 --- a/docs/enhanced-configuration/self-signed-certificates.md +++ b/docs/enhanced-configuration/self-signed-certificates.md @@ -3,25 +3,27 @@ SPDX-FileCopyrightText: 2024 Zentrum für Digitale Souveränität der Öffentlic SPDX-License-Identifier: Apache-2.0 --> -

Self-signed certificate and custom Certificate Authority (CA)

+

Self-signed certificates and custom Certificate Authority (CA)

* [Configuration](#configuration) * [Option 1: Bring Your Own Certificate](#option-1-bring-your-own-certificate) * [Option 2a: Use cert-manager.io with auto-generated namespace based root-certificate](#option-2a-use-cert-managerio-with-auto-generated-namespace-based-root-certificate) - * [Option 2b: Use cert-manager.io with pre-defined/shared root-certificate](#option-2b-use-cert-managerio-with-pre-definedshared-root-certificate) + * [Option 2b: Use cert-manager.io with a pre-defined or shared root-certificate](#option-2b-use-cert-managerio-with-a-pre-defined-or-shared-root-certificate) -Deploying openDesk into an environment with custom public key infrastructure (PKI) that is usually not part of -public certificate authority chains or deploying openDesk into a local cluster without ACME challenge. +This document covers: +* Deploying openDesk into an environment with custom public key infrastructure (PKI) that is usually not part of +public certificate authority chains +* deploying openDesk into a local cluster without ACME challenge # Configuration -There are two options to address the use case. +There are two options to address these use case: ## Option 1: Bring Your Own Certificate -This option is useful, when you have your own PKI in your environment which is trusted by all clients that should +This option is useful when you have your own PKI in your environment which is also trusted by all clients that should access openDesk. 1. Disable cert-manager.io certificate resource creation: @@ -31,26 +33,26 @@ access openDesk. enabled: false ``` -1. Enable mount of self-signed certificates: +2. Enable mount of self-signed certificates: ```yaml certificate: selfSigned: true ``` -1. Create a Kubernetes secret named `opendesk-certificates-tls` of type `kubernetes.io/tls` containing either a valid +3. Create a Kubernetes secret named `opendesk-certificates-tls` of type `kubernetes.io/tls` containing either a valid wildcard certificate or a certificate with [all required subdomains](../../helmfile/environments/default/global.yaml.gotmpl) set as SANs (Subject Alternative Name). -1. Create a Kubernetes secret with name `opendesk-certificates-ca-tls` of type `kubernetes.io/tls` containing the custom +4. Create a Kubernetes secret with name `opendesk-certificates-ca-tls` of type `kubernetes.io/tls` containing the custom CA certificate as X.509 encoded (`ca.crt`) and as jks trust store (`truststore.jks`). -1. Create a Kubernetes secret with name `opendesk-certificates-keystore-jks` with key `password` and as value the jks +5. Create a Kubernetes secret with name `opendesk-certificates-keystore-jks` with key `password` and as value the jks trust store password. ## Option 2a: Use cert-manager.io with auto-generated namespace based root-certificate -This option is useful, when you do not have a trusted certificate available and can't fetch a certificate from +This option is useful when you do not have a trusted certificate available and can't fetch a certificate from Let’s Encrypt. It will result in a cert-manager managed root certificate in the namespace you deploy openDesk into. 1. Create self-signed cert-manager.io Cluster Issuer: @@ -63,7 +65,7 @@ Let’s Encrypt. It will result in a cert-manager managed root certificate in th selfSigned: {} ``` -1. Enable mount and creation of self-signed certificates: +2. Enable mount and creation of self-signed certificates: ```yaml certificate: issuerRef: @@ -71,14 +73,14 @@ Let’s Encrypt. It will result in a cert-manager managed root certificate in th selfSigned: true ``` -## Option 2b: Use cert-manager.io with pre-defined/shared root-certificate +## Option 2b: Use cert-manager.io with a pre-defined or shared root-certificate Use this approach if you like to use a pre-created CA root certificate that can be "shared" (as copy) between multiple namespaces in a cluster. -1. Create self-signed cert-manager.io Cluster Issuer root certificate the same was as in *Option 2a*. +1. Create self-signed cert-manager.io Cluster Issuer root certificate the same way as in *Option 2a*. -1. Create the root certificate for the previously created CA, in the example it is placed into the namespace `cert-manager`. +2. Create the root certificate for the previously created CA, in the example it is placed into the namespace `cert-manager`. ```yaml apiVersion: cert-manager.io/v1 kind: Certificate @@ -102,8 +104,8 @@ multiple namespaces in a cluster. renewBefore: 87599h ``` -1. Copy this cert's secret into the/each namespace you want to make use of the cert. +3. Copy this certificates secret into all namespaces you want to make use of the certificate in. -1. Create issuer in the/each namespace you want to make use of the cert. +4. Create an issuer resource in all namespaces you want to make use of the certificate in. -The latter two steps are part of the `env-start:` section within [`.gitlab-ci.yml`](../../.gitlab-ci.yml). +>The latter two steps are part of the `env-start:` section within [`.gitlab-ci.yml`](../../.gitlab-ci.yml). diff --git a/docs/external-services.md b/docs/external-services.md index e0083f2b..fe750286 100644 --- a/docs/external-services.md +++ b/docs/external-services.md @@ -20,7 +20,7 @@ When deploying this suite to production, you need to configure the applications service. > **Note**
-> openDesk supports PostgreSQL as alternative database backend for Nextcloud and XWiki. PostgreSQL is likely become the preferred option/default in the future and MariaDB might be deprecated at a later point requiring migrations[^1] if you do not select PostgreSQL for new installations. +> openDesk supports PostgreSQL as alternative database backend for Nextcloud and XWiki. PostgreSQL is likely to become the preferred option/default in the future should MariaDB become deprecated. This would cause migration[^1] to be necessary if you do not select PostgreSQL for new installations. | Component | Name | Parameter | Key | Default | | ------------------ | ------------------ | --------- | --------------------------------------------- | ---------------------------- | @@ -155,7 +155,7 @@ service. # Footnotes -[^1] The upstream product provide some valuable information regarding database migrations: +[^1] The upstream product documentation provides some valuable information regarding database migrations: - Nextcloud: https://docs.nextcloud.com/server/latest/admin_manual/configuration_database/db_conversion.html - XWiki: - https://www.xwiki.org/xwiki/bin/view/Documentation/AdminGuide/Backup#HUsingtheXWikiExportfeature @@ -165,4 +165,4 @@ service. [^3] openDesk Enterprise only. -[^4] XWiki requires root access when using MariaDB as sub-wikis are using separate databases that are managed by XWiki. When using PostgreSQL with XWiki no root user is required as the sub-wikis are managed within multiple schemes within a single database. +[^4] XWiki requires root access when using MariaDB due to the fact that sub-wikis use separate databases that are managed by XWiki. When using PostgreSQL with XWiki no root user is required as the sub-wikis are managed within multiple schemas within a single database. diff --git a/docs/getting-started.md b/docs/getting-started.md index 5d6dcb22..931a4f16 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -58,18 +58,18 @@ For the following guide, we will use `dev` as environment where variables can be ## DNS The deployment is designed to deploy each application/service under a dedicated subdomain. -For your convenience, we recommend creating a `*.domain.tld` A-Record to your cluster ingress controller; otherwise, you must create an A-Record for each subdomain. +For your convenience, we recommend creating a `*.domain.tld` A-Record for your cluster Ingress Controller; otherwise, you must create an A-Record for each subdomain. -| Record name | Type | Value | Additional information | -| ----------------------------- | ---- | -------------------------------------------------- | ---------------------------------------------------------------- | -| *.domain.tld | A | IPv4 address of your Ingress Controller | | -| *.domain.tld | AAAA | IPv6 address of your Ingress Controller | | -| mail.domain.tld | A | IPv4 address of your postfix NodePort/LoadBalancer | Optional mail should directly be delivered to openDesk's Postfix | -| mail.domain.tld | AAAA | IPv6 address of your postfix NodePort/LoadBalancer | Optional mail should directly be delivered to openDesk's Postfix | -| domain.tld | MX | `10 mail.domain.tld` | | -| domain.tld | TXT | `v=spf1 +a +mx +a:mail.domain.tld ~all` | Optional, use proper MTA record if present | -| _dmarc.domain.tld | TXT | `v=DMARC1; p=quarantine` | Optional | -| default._domainkey.domain.tld | TXT | `v=DKIM1; k=rsa; h=sha256; ...` | Optional DKIM settings | +| Record name | Type | Value | Additional information | +|-------------------------------|------|----------------------------------------------------|-------------------------------------------------------------------| +| *.domain.tld | A | IPv4 address of your Ingress Controller | | +| *.domain.tld | AAAA | IPv6 address of your Ingress Controller | | +| mail.domain.tld | A | IPv4 address of your postfix NodePort/LoadBalancer | Optional, mail should directly be delivered to openDesk's Postfix | +| mail.domain.tld | AAAA | IPv6 address of your postfix NodePort/LoadBalancer | Optional, mail should directly be delivered to openDesk's Postfix | +| domain.tld | MX | `10 mail.domain.tld` | | +| domain.tld | TXT | `v=spf1 +a +mx +a:mail.domain.tld ~all` | Optional, use proper MTA record if present | +| _dmarc.domain.tld | TXT | `v=DMARC1; p=quarantine` | Optional | +| default._domainkey.domain.tld | TXT | `v=DKIM1; k=rsa; h=sha256; ...` | Optional, DKIM settings | ## Domain @@ -83,14 +83,14 @@ global: nextcloud: "files" ``` -The domain has to be set either via `dev` environment +The domain has to be set either via `dev` environment: ```yaml global: domain: "domain.tld" ``` -or via environment variable +or alternatively via environment variable: ```shell export DOMAIN=domain.tld @@ -98,7 +98,8 @@ export DOMAIN=domain.tld ### Apps -All available apps and their default value are in `helmfile/environments/default/opendesk_main.gotmpl`. +Depending on your ideal openDesk deployment, you may wish to disable or enable certain apps. +All available apps and their default values are located in `helmfile/environments/default/opendesk_main.gotmpl`. | Component | Name | Default | Description | | -------------------- | --------------------------- | ------- | ------------------------------ | @@ -124,7 +125,7 @@ All available apps and their default value are in `helmfile/environments/default | Redis | `apps.redis.enabled` | `true` | Cache Database | | XWiki | `apps.xwiki.enabled` | `true` | Knowledge management | -Exemplary, Jitsi can be disabled like: +For example, Jitsi can be disabled like this: ```yaml apps: @@ -141,8 +142,8 @@ For untouched upstream artifacts that do not belong to a functional component's like Docker Hub. Doing a test deployment will be fine with this setup. In case you want to deploy multiple times a day -and fetch from the same IP address, you might run into rate limits at Docker Hub. In that case and in cases you -prefer the use of a private image registry, you can configure such for +and fetch from the same IP address, you might run into rate limits at Docker Hub. In that case, and in case you +prefer the use of a private image registry, you can configure these in [your target environment](../helmfile/environments/dev/values.yaml.gotmpl.sample) by setting - `global.imageRegistry` for a private image registry and - `global.helmRegistry` for a private Helm chart registry. @@ -158,7 +159,7 @@ alternatively, you can use an environment variable: export PRIVATE_IMAGE_REGISTRY_URL=my_private_registry.domain.tld ``` -or control repository override fine-granular per registry: +or for more granular control over repository overrides per registry (rewrites): ```yaml repositories: @@ -179,7 +180,7 @@ global: ### Service -Some apps, like Jitsi or Dovecot, require HTTP and external TCP connections. +Some apps, like Jitsi and Dovecot, require HTTP and external TCP connections. These apps create a Kubernetes service object. You can configure whether `NodePort` (for on-premise), `LoadBalancer` (for cloud), or `ClusterIP` (to disable) should be used: @@ -192,7 +193,7 @@ cluster: ### Networking -If your cluster has not the default `cluster.local` domain configured, you need to provide the domain via: +If your cluster does not have the default `cluster.local` domain configured, you need to provide the domain via: ```yaml cluster: @@ -200,7 +201,7 @@ cluster: domain: "acme.internal" ``` -If your cluster has not the default `10.0.0.0/8` CIDR configured, you need to provide the CIDR via the following: +If your cluster does not have the default `10.0.0.0/8` CIDR configured, you need to provide the CIDR via the following: ```yaml cluster: @@ -209,8 +210,8 @@ cluster: - "127.0.0.0/8" ``` -If your load balancer / reverse proxy IPs are not already covered by the above `cidr` you need to -explicitly configure the related IPs or IP ranges: +If your load balancer / reverse proxy IPs are not already included in the above `cidr` you need to +explicitly configure their related IPs or IP ranges: ```yaml cluster: @@ -221,9 +222,8 @@ cluster: ### Ingress -By default, the `ingressClassName` is empty to select your default ingress controller. You may want to customize it by -setting the following attribute to the name of the currently only supported ingress controller `ingress-nginx` (see -[requirements.md](requirements.md)) for reference) within your deployment if that is not the cluster's default ingress. +By default, the `ingressClassName` is empty and selects the default ingress controller in your cluster. You can customize it by +setting the following attribute to the name of the ingress controller the within your deployment you wish to use. Useful if the ingress controller you wish to use is not the default. ```yaml ingress: @@ -236,7 +236,7 @@ Currently, the only supported ingress controller is `ingress-nginx` (see ### Container runtime Some apps require specific configurations for the container runtime. You can set your container runtime like `cri-o`, -`containerd` or `docker` by: +`containerd` or `docker` by using the following attribute: ```yaml cluster: @@ -245,7 +245,7 @@ cluster: ``` ### Volumes -The **StorageClass** must be set by: +The StorageClass must be set using the following attribute: ```yaml persistence: @@ -255,8 +255,8 @@ persistence: ``` `RWX` is optional and requires that your cluster has a `ReadWriteMany` volume provisioner. If you can make use -of it it benefits the distribution or scaling of apps. By default, only `ReadWriteOnce` is enabled. -To enable `ReadWriteMany` you have to set: +of it, it largely benefits the distribution and scaling of apps. By default, only `ReadWriteOnce` is enabled. +To enable `ReadWriteMany` you can use the following attribute: ```yaml cluster: @@ -272,7 +272,7 @@ While openDesk configures the applications with meaningful defaults, you can che ### Ports -**Note:** If you use `NodePort` for service exposure, you must check your deployment for the actual ports. +**Note:** If you use `NodePort` for service exposure, you must check your deployment for the actual ports and ensure they are opened where necessary. #### Web-based user interface @@ -286,7 +286,7 @@ To use the openDesk functionality with its web-based user interface, you need to #### Mail clients -To connect with mail clients like [Thunderbird](https://www.thunderbird.net/), the following ports need public exposure: +To connect with mail clients like [Thunderbird](https://www.thunderbird.net/), the following ports need to be publicly exposed: | Component | Description | Port | Type | | ------------------ | ----------------------- | ----: | ---: | @@ -298,7 +298,7 @@ To connect with mail clients like [Thunderbird](https://www.thunderbird.net/), t ### Mail/SMTP configuration To use the full potential of the openDesk, you need to set up an SMTP relay that allows sending emails from -the whole subdomain. +the whole subdomain. The following attribute can be set: ```yaml smtp: @@ -308,7 +308,7 @@ smtp: ``` Enabling DKIM signing of emails helps to reduce spam and increases trust. -openDesk ships dkimpy-milter as Postfix milter for signing emails. +openDesk ships dkimpy-milter as Postfix milter for signing emails. The following attributes can be set: ```yaml apps: @@ -341,9 +341,9 @@ turn: ### Certificate issuer -As mentioned in [requirements](requirements.md#certificate-management), you can provide your own valid certificate. A TLS +As mentioned in [requirements](requirements.md#certificate-management), you can provide your own valid certificate. A TLS type secret named `opendesk-certificates-tls` must be present in the application namespace. For deployment, you can -turn off `Certificate` resource creation by: +turn off `Certificate` resource creation with: ```yaml apps: @@ -351,7 +351,7 @@ apps: enabled: false ``` -If you want to leverage the `cert-manager.io` to handle certificates, like `Let's encrypt`, you need to provide the +If you want to leverage `cert-manager.io` to handle certificates, like `Let's encrypt`, you need to provide the configured cluster issuer: ```yaml @@ -360,7 +360,7 @@ certificate: name: "letsencrypt-prod" ``` -Additionally, it is possible to request wildcard certificates by: +Additionally, it is possible to request wildcard certificates with: ```yaml certificate: @@ -393,13 +393,13 @@ helmfile apply -e dev -n [-l