diff --git a/.gitlab/common/common.yml b/.gitlab/common/common.yml index 27936440..692707e1 100644 --- a/.gitlab/common/common.yml +++ b/.gitlab/common/common.yml @@ -2,8 +2,8 @@ # SPDX-License-Identifier: Apache-2.0 --- variables: - OPENDESK_CI_CLI_IMAGE: "registry.opencode.de/bmi/opendesk/tooling/opendesk-ci-cli:2.5.0\ - @sha256:630e102edc70c9e730a46180e79ff278fd8b5039eb336110e0df89fe415225ef" + OPENDESK_CI_CLI_IMAGE: "registry.opencode.de/bmi/opendesk/tooling/opendesk-ci-cli:2.5.1\ + @sha256:570440f48c46e69a1b989c44cc9e9c243fbfdd11f4bc2a39b76138bc19f5d69d" OPENDESK_LINT_IMAGE: "registry.opencode.de/bmi/opendesk/components/platform-development/images/ci-lint:1.0.6\ @sha256:0a8997876a0c3f5a3c73eb6bd75c5cde63757bc31b983bfd92cfcb17389d536f" diff --git a/README.md b/README.md index 67b686ac..4b465374 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,6 @@ SPDX-License-Identifier: Apache-2.0 * [Overview](#overview) -* [Disclaimer](#disclaimer) * [Requirements](#requirements) * [Getting started](#getting-started) * [Advanced customization](#advanced-customization) @@ -28,17 +27,17 @@ openDesk is a Kubernetes based, open-source and cloud-native digital workplace s openDesk currently features the following functional main components: -| Function | Functional Component | Component
Version | Upstream Documentation | -| -------------------- | --------------------------- | ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | -| Chat & collaboration | Element ft. Nordeck widgets | [1.11.67](https://github.com/element-hq/element-desktop/releases/tag/v1.11.67) | [For the most recent release](https://element.io/user-guide) | -| Diagram editor | CryptPad ft. diagrams.net | [5.6.0](https://github.com/cryptpad/cryptpad/releases/tag/5.6.0) | [For the most recent release](https://docs.cryptpad.org/en/) | -| File management | Nextcloud | [29.0.7](https://nextcloud.com/de/changelog/#29-0-7) | [SNextcloud 29](https://docs.nextcloud.com/) | -| Groupware | OX App Suite | [8.26](https://documentation.open-xchange.com/appsuite/releases/8.26/) | Online documentation available from within the installed application; [Additional resources](https://www.open-xchange.com/resources/oxpedia) | -| Knowledge management | XWiki | [16.4.4](https://www.xwiki.org/xwiki/bin/view/ReleaseNotes/Data/XWiki/16.4.4/) | [For the most recent release](https://www.xwiki.org/xwiki/bin/view/Documentation) | -| Portal & IAM | Nubus | [1.0] | [Univention's documentation website](https://docs.software-univention.de/n/en/nubus.html) | -| Project management | OpenProject | [14.6.1](https://www.openproject.org/docs/release-notes/14-6-1/) | [For the most recent release](https://www.openproject.org/docs/user-guide/) | -| Videoconferencing | Jitsi | [2.0.9646](https://github.com/jitsi/jitsi-meet/releases/tag/stable%2Fjitsi-meet_9646) | [For the most recent release](https://jitsi.github.io/handbook/docs/category/user-guide/) | -| Weboffice | Collabora | [24.04.7.2](https://www.collaboraoffice.com/code-24-04-release-notes/) | Online documentation available from within the installed application; [Additional resources](https://sdk.collaboraonline.com/) | +| Function | Functional Component | Component
Version | Upstream Documentation | +| -------------------- | --------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | +| Chat & collaboration | Element ft. Nordeck widgets | [1.11.67](https://github.com/element-hq/element-desktop/releases/tag/v1.11.67) | [For the most recent release](https://element.io/user-guide) | +| Diagram editor | CryptPad ft. diagrams.net | [5.6.0](https://github.com/cryptpad/cryptpad/releases/tag/5.6.0) | [For the most recent release](https://docs.cryptpad.org/en/) | +| File management | Nextcloud | [29.0.7](https://nextcloud.com/de/changelog/#29-0-7) | [SNextcloud 29](https://docs.nextcloud.com/) | +| Groupware | OX App Suite | [8.28](https://documentation.open-xchange.com/appsuite/releases/8.28/) | Online documentation available from within the installed application; [Additional resources](https://documentation.open-xchange.com/ | +| Knowledge management | XWiki | [16.4.4](https://www.xwiki.org/xwiki/bin/view/ReleaseNotes/Data/XWiki/16.4.4/) | [For the most recent release](https://www.xwiki.org/xwiki/bin/view/Documentation) | +| Portal & IAM | Nubus | [1.0](https://www.univention.de/produkte/nubus/) | [Univention's documentation website](https://docs.software-univention.de/n/en/nubus.html) | +| Project management | OpenProject | [14.6.1](https://www.openproject.org/docs/release-notes/14-6-1/) | [For the most recent release](https://www.openproject.org/docs/user-guide/) | +| Videoconferencing | Jitsi | [2.0.9646](https://github.com/jitsi/jitsi-meet/releases/tag/stable%2Fjitsi-meet_9646) | [For the most recent release](https://jitsi.github.io/handbook/docs/category/user-guide/) | +| Weboffice | Collabora | [24.04.7.2](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 align the applications with best practices regarding container design and operations. @@ -47,21 +46,6 @@ This documentation aims to give you all that is needed to set up your own instan Basic knowledge of Kubernetes and DevOps processes is required though. -# Disclaimer - -openDesk will face breaking changes in the near future without upgrade paths before -[technical release](https://gitlab.opencode.de/bmi/opendesk/deployment/sovereign-workplace/-/releases) -v1.0.0 is reached. - -While most components support upgrades, major configuration or component changes may occur, therefore we recommend -from scratch installations for now. - -In the next months, we not only expect to integrate upstream updates of the functional components to include their -most recent feature and security sets, but also to address operational topics like scalability for the openDesk -platform. - -Of course, further development also includes enhancing the documentation itself. - # Requirements ⟶ Visit our detailed [Requirements](./docs/requirements.md) overview. diff --git a/docs/ci.md b/docs/ci.md index feba6a97..df0a9fae 100644 --- a/docs/ci.md +++ b/docs/ci.md @@ -17,27 +17,22 @@ The project includes a `.gitlab-ci.yml` that allows you to execute the deploymen When starting the pipeline through the GitLab UI, you will be queried for some variables plus the following ones: -- `DOMAIN`: Primary domain for your deployment making the openDesk services available e.g. as `https://portal.DOMAIN`. -- `MAIL_DOMAIN`: (optional) Domain for the users mail addresses, defaults to `DOMAIN`. -- `MATRIX_DOMAIN`: (optional) Domain for the users Matrix IDs, defaults to `DOMAIN`. -- `NAMESPACE`: Namespace of your K8s cluster openDesk will be installed to. +- `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`. +- `MATRIX_DOMAIN` (optional): The domain for the users' Matrix IDs; it defaults to `DOMAIN`. +- `NAMESPACE`: Namespace of your K8s cluster openDesk will be installed. - `MASTER_PASSWORD_WEB_VAR`: Overwrites value of `MASTER_PASSWORD`. -Based on your input, the following variables will be set: -- `MASTER_PASSWORD:`: `MASTER_PASSWORD_WEB_VAR`. If `MASTER_PASSWORD_WEB_VAR` - is not set, the default for `MASTER_PASSWORD` will be used, unless you set - `MASTER_PASSWORD` as a masked CI/CD variable in GitLab to supersede the default. - You might want to set credential variables in the GitLab project at `Settings` > `CI/CD` > `Variables`. # Tests The GitLab CI pipeline contains a job named `run-tests` that can trigger a test suite pipeline on another GitLab project. -In order for the trigger to work, the variable `TESTS_PROJECT_URL` has to be set on this GitLab project's CI variables -that can be found at `Settings` -> `CI/CD` -> `Variables`. The variable should have this format: +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 testset, 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 +To select the current test set, 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 in the opendesk-env repository. \ No newline at end of file +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. diff --git a/docs/components.md b/docs/components.md index aae47a0d..1562be05 100644 --- a/docs/components.md +++ b/docs/components.md @@ -5,7 +5,7 @@ SPDX-License-Identifier: Apache-2.0 -->

Components

-This section covers the internal system requirements as well as external service requirements for productive use. +This section covers the internal system requirements and external service requirements for productive use. * [Overview](#overview) @@ -21,88 +21,88 @@ This section covers the internal system requirements as well as external service # Overview -openDesk consists out of a variety of open-source projects. Here is a list with the description and type. +openDesk consists of a variety of open-source projects. Here is a list with the description and type. Components of type `Eval` are used for development and evaluation purposes only, they need to be replaced in production deployments. -| Component | Description | Type | +| Component                   | Description                    | Type       | |-----------------------------|--------------------------------|------------| -| Certificates | TLS certificates | Eval | -| ClamAV (Distributed) | Antivirus engine | Eval | -| ClamAV (Simple) | Antivirus engine | Eval | -| Collabora | Weboffice | Functional | -| CryptPad | Weboffice | Functional | -| dkimpy-milter | DKIM milter for Postfix | Eval | -| Element | Secure communications platform | Functional | -| Jitsi | Videoconferencing | Functional | -| MariaDB | Database | Eval | -| Memcached | Cache Database | Eval | -| MinIO | Object Storage | Eval | -| Nextcloud | File share | Functional | -| Nubus (UMS) | Identity Management & Portal | Functional | -| OpenProject | Project management | Functional | -| OX Appsuite | Groupware | Functional | -| OX Dovecot | Mail backend (IMAP) | Functional | -| Postfix | MTA | Eval | -| PostgreSQL | Database | Eval | -| Redis | Cache Database | Eval | -| XWiki | Knowledge Management | Functional | +| Certificates                | TLS certificates               | Eval       | +| ClamAV (Distributed)        | Antivirus engine               | Eval       | +| ClamAV (Simple)             | Antivirus engine               | Eval       | +| Collabora                   | Weboffice                      | Functional | +| CryptPad                    | Weboffice                      | Functional | +| dkimpy-milter               | DKIM milter for Postfix        | Eval       | +| Element                     | Secure communications platform | Functional | +| Jitsi                       | Videoconferencing              | Functional | +| MariaDB                     | Database                       | Eval       | +| Memcached                   | Cache Database                 | Eval       | +| MinIO                       | Object Storage                 | Eval       | +| Nextcloud                   | File share                     | Functional | +| Nubus (UMS)                 | Identity Management & Portal   | Functional | +| OpenProject                 | Project management             | Functional | +| OX Appsuite                 | Groupware                      | Functional | +| OX Dovecot                  | Mail backend (IMAP)            | Functional | +| Postfix                     | MTA                            | Eval       | +| PostgreSQL                  | Database                       | Eval       | +| Redis                       | Cache Database                 | Eval       | +| XWiki                       | Knowledge Management           | Functional | # Component integration -Some use cases require inter component integration. +Some use cases require inter-component integration. ```mermaid flowchart TD - OX-AppSuite_Frontend-->|Silent Login, Filepicker, Central Navigation|Intercom_Service - Element-->|Silent Login, Central Navigation|Intercom_Service - Intercom_Service-->|Silent Login, Token Exchange|IdP - Intercom_Service-->|Filepicker|Nextcloud - Intercom_Service-->|Central Navigation|Portal - OX-AppSuite_Backend-->|Filepicker|Nextcloud - Nextcloud-->|Central Navigation|Portal - OpenProject-->|Central Navigation|Portal - OpenProject-->|File Store|Nextcloud - XWiki-->|Central Navigation|Portal - Nextcloud-->|Central Contacts|OX-AppSuite_Backend - OX-AppSuite_Frontend-->|Filepicker|OX-AppSuite_Backend + OX-AppSuite_Frontend-->|Silent Login, Filepicker, Central Navigation|Intercom_Service + Element-->|Silent Login, Central Navigation|Intercom_Service + Intercom_Service-->|Silent Login, Token Exchange|IdP + Intercom_Service-->|Filepicker|Nextcloud + Intercom_Service-->|Central Navigation|Portal + OX-AppSuite_Backend-->|Filepicker|Nextcloud + Nextcloud-->|Central Navigation|Portal + OpenProject-->|Central Navigation|Portal + OpenProject-->|File Store|Nextcloud + XWiki-->|Central Navigation|Portal + Nextcloud-->|Central Contacts|OX-AppSuite_Backend + OX-AppSuite_Frontend-->|Filepicker|OX-AppSuite_Backend ``` Most details can be found in the upstream documentation that is linked in the respective sections. ## Intercom Service / Silent Login -The Intercom Service is deployed in context of Nubus/UMS. Its role is to enable cross-application integration +The Intercom Service is deployed in the context of Nubus/UMS. 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. -To establish a session with the Intercom Service an application can use the silent login feature within an iframe. +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. +Currently, only OX AppSuite and Element are using the frontend-based integration. **Links** - [Intercom Service upstream documentation](https://docs.software-univention.de/intercom-service/latest/index.html). ## Filepicker -The Nextcloud filepicker is integrated into the OX AppSuite supporting the following use cases against the respective openDesk instance's Nextcloud: -- Attaching files from Nextcloud to emails. -- Adding links of Nextcloud files to emails. -- Saving attachments from emails into Nextcloud. -- Attaching files from Nextcloud to calendar entries. +The Nextcloud Filepicker is integrated into the OX AppSuite, supporting the following use cases against 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. +- Attach files from Nextcloud to calendar entries. -The filepicker is using 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 is communicating directly with Nextcloud, -which is used when adding a file to an email or storing a file into Nextcloud, to avoid passing these files through the user's browser. +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. **Links** - [OX AppSuite Nextcloud Integration upstream documentation](https://gitlab.open-xchange.com/extensions/nextcloud-integration/-/tree/main/documentation). ## Central Navigation -Central navigation is based on an API endpoint in the Nubus portal that returns a JSON containing the contents of the portal for +Central navigation is based on an API endpoint in the Nubus portal that returns a JSON containing the portal's contents for 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 @@ -120,8 +120,8 @@ curl 'https://portal./univention/portal/navigation.json?base=https%3A//p ## 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 -- create a new contact in the user's contacts folder when a file is shared with a yet unknown email address. +OX App Suite is 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. **Links:** @@ -133,9 +133,9 @@ OX App Suite is managing contacts in openDesk. Therefore Nextcloud's PHP backend While OpenProject allows you to attach files to work packages directly, it is often preferred that the files are stored within Nextcloud or to link an existing file from your openDesk Nextcloud to a work package. -Therefore openDesk pre-configures the trust between the openDesk instance's OpenProject and Nextcloud during the `openproject-boostrap` deployment step. As prerequisite for that openDesk's Nextcloud contains the `integration_openproject` app. +Therefore, openDesk pre-configures the trust between the openDesk instance's OpenProject and Nextcloud during the `openproject-boostrap` deployment step. As a prerequisite for that, openDesk's Nextcloud contains the `integration_openproject` app. -The file store still needs to be enabled on a per-project level in OpenProject's project admin section. +The file store must still be enabled per project in OpenProject's project admin section. **Links:** - [OpenProject's documentation on Nextcloud integration](https://www.openproject.org/docs/system-admin-guide/integrations/nextcloud/) @@ -145,42 +145,41 @@ The file store still needs to be enabled on a per-project level in OpenProject's An overview of - components that consume the LDAP service. - - The components accessing the LDAP using a component specific LDAP search account. -- components using Univention Keycloak as identity provider (IdP). - - If not otherwise denoted the components make use of OAuth2 / OIDC flows. - - All components have a client configured in Keycloak, except for Jitsi which is using authentication with the - [Authorization Code Flow](https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth) that does not - require an OIDC client to be configured in Keycloak. +  - The components access the LDAP using a component-specific LDAP search account. +- components using Univention Keycloak as an identity provider (IdP). +  - The components should use OAuth2 / OIDC flows if not otherwise denoted. +  - All components have a client configured in Keycloak, except for Jitsi, which is using authentication with the + [Authorization Code Flow](https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth) that does not + require an OIDC client to be configured in Keycloak. Some components trust others to handle authentication for them. ```mermaid flowchart TD - K[IdP]-->L[LDAP] - N[Nextcloud]-->L - O[OpenProject] --> L - A[OX AppSuite]-->L - D[OX Dovecot]-->L - P[Portal/Admin]-->L - X[XWiki]-->L - A-->K - N-->K - D-->K - O-->K - X-->K - P-->|SAML|K - E[Element]-->K - J[Jitsi]-->K - I[IntercomService]-->K - C[Collabora]-->N - R[CryptPad]-->N - F[Postfix]-->D + K[IdP]-->L[LDAP] + N[Nextcloud]-->L + O[OpenProject] --> L + A[OX AppSuite]-->L + D[OX Dovecot]-->L + P[Portal/Admin]-->L + X[XWiki]-->L + A-->K + N-->K + D-->K + O-->K + X-->K + P-->|SAML|K + E[Element]-->K + J[Jitsi]-->K + I[IntercomService]-->K + C[Collabora]-->N + R[CryptPad]-->N + F[Postfix]-->D ``` # Provisioning -Currently, active provisioning is only done for OX AppSuite. The OX-Connector is synchronizing, creating, modifying and -deleting activities for the following objects to the OX AppSuite using the AppSuite's SOAP API: +Currently, active provisioning is only done for OX AppSuite. The OX-Connector synchronizes the following objects to the OX AppSuite using the AppSuite's SOAP API: - Contexts - Users diff --git a/docs/debugging.md b/docs/debugging.md index aa6037a5..60d656b9 100644 --- a/docs/debugging.md +++ b/docs/debugging.md @@ -17,53 +17,55 @@ SPDX-License-Identifier: Apache-2.0 # Disclaimer -This document collects information how to deal with debugging an openDesk deployment. +This document collects information on how to deal with debugging an openDesk deployment. -It will be extended over time as we have to deal with debugging cases. +It will be extended over time as we deal with debugging cases. We for sure do not want to reinvent the wheel, so we might link to external sources that contain helpful information where available. -**Note:** You should never enable debug in production environments! By looking up `debug.enable` in the deployment you -will find the various places changes are applied when enabling debugging. So outside of development and test -environments you may want to make use of them in a very thoughtful and selective manner if needed. +> **Warning**
+> You should never enable the debug option in production environments! By looking up `debug.enable` in the deployment, you +will find the various places changes are applied when enabling debugging. So, outside of development and test +environments, you should use them thoughtfully and carefully if needed. # Enable debugging Set `debug.enable` to `true` in [`debug.yaml`](../helmfile/environments/default/debug.yaml) to set the -component's log level to debug and it get some features like: +component's log level to debug, and it gets some features like: - The `/admin` console is routed for Keycloak. - An ingress for `http://minio-console.` is configured. and set the log level for components to "Debug". -**Note**: When enabling debug and running upgrades you must manually delete all jobs before the upgrade. As with debug -we keep the jobs and some job fields are immutable it could otherwise lead into an upgrade failure. +> **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! +> **Note**
+> All containers should write their log output to STDOUT; if you find (valuable) logs inside a container, please let us know! # Adding containers to a pod for debugging purposes -During test or development you come across the need to execute tools, browse or even change things in the filesystem of another container. +During testing or development, you may need to execute tools, browse, or even change things in the filesystem of another container. -This can be a challenge the more security hardened container images are, because there are no debugging tools available and sometimes not even a shell. +This can be a challenge the more security-hardened the container images are because there are no debugging tools available, and sometimes, there is not even a shell. Adding a container to a Pod can ease the pain. -Below you will find some wrap-up notes when it comes to debugging openDesk by adding debug containers. Of course there are a lot of more detailed resources out in the wild. +Below are some wrap-up 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 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 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`. - Ensure the `shareProcessNamespace` option is enabled for the Pod. - Reference the selected container within the `containers` array of the deployment. -- In case you want to access another containers filesystem, ensure the user/group settings of both containers match. +- If you want to access another container's filesystem, ensure both containers' user/group settings match. - Save & update the deployment. -The following example can e.g. be used to debug the `openDesk-Nextcloud-PHP` container, in case you want to modify files, don't forget to set `readOnlyRootFilesystem` to `true` on the PHP container. +The following example can be used to debug the `openDesk-Nextcloud-PHP` container; if you want to modify files, remember to set `readOnlyRootFilesystem` to `true` on the PHP container. -``` +```yaml shareProcessNamespace: true containers: - name: debugging @@ -83,36 +85,36 @@ The following example can e.g. be used to debug the `openDesk-Nextcloud-PHP` con type: RuntimeDefault ``` -- After the deployment was reloaded open the shell of the debugging container. -- When you've been successful you will see the processes of both/all containers in the pod when doing a `ps aux`. -- To access another containers filesystem just select the PID of a process from the other container an do a `cd /proc//root` +- 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`. +- To access other containers' filesystems, select the PID of a process from the other container and do a `cd /proc//root`. ## Temporary/ephemeral containers -Interesting read we picked most of the details below from: https://iximiuz.com/en/posts/kubernetes-ephemeral-containers/ +An interesting read 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/). +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: -- `NAMESPACE`: The namespace the Pod you want to inspects is running in. -- `DEPLOYMENT_NAME`: The name of the deployment responsible for spawning the Pod you want to inspect within the pre-mentioned namespace. +For the commands further down this section, we 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`: Chose the name for the container, "debugging" seem obvious. -- `DEBUG_IMAGE`: The image you want to make use of for debugging purposes. +- `EPH_CONTAINER_NAME`: Choose the name for the container, and "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 DEBUG_IMAGE=registry.opencode.de/bmi/opendesk/components/platform-development/images/opendesk-debugging-image:1.0.0 +export DEBUG_IMAGE=registry.opencode.de/bmi/opendesk/components/platform-development/images/opendesk-debugging-image:latest ``` You still need to ensure that your deployment supports process namespace sharing: -``` +```shell kubectl -n ${NAMESPACE} patch deployment ${DEPLOYMENT_NAME} --patch ' spec: template: @@ -120,12 +122,12 @@ spec: shareProcessNamespace: true' ``` -Now you can add the ephemeral container with: -``` +Now, you can add the ephemeral container with: +```shell kubectl -n ${NAMESPACE} debug -it --attach=false -c ${EPH_CONTAINER_NAME} --image={DEBUG_IMAGE} ${POD_NAME} ``` and open its interactive terminal with -``` +```shell kubectl -n ${NAMESPACE} attach -it -c ${EPH_CONTAINER_NAME} ${POD_NAME} ``` @@ -133,9 +135,9 @@ kubectl -n ${NAMESPACE} attach -it -c ${EPH_CONTAINER_NAME} ${POD_NAME} ## MariaDB -When using the openDesk bundled MariaDB you can explore database(s) using the MariaDB interactive terminal from the pod's command line: `mariadb -u root -p`. As password provide the value for `MARIADB_ROOT_PASSWORD` set 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` found in the Pod's environment. -While you will find all 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 online documentation](https://mariadb.com/kb/en/mariadb-command-line-client/), some quick commands are: - `help`: Get help on the psql command set - `show databases`: Lists all databases @@ -145,28 +147,27 @@ While you will find all details for the CLI tool in [the online documentation](h ## Nextcloud -`occ` is the CLI for Nextcloud, all the details can be found in the [upstream documentation](https://docs.nextcloud.com/server/latest/admin_manual/configuration_server/occ_command.html). +`occ` is the CLI for Nextcloud; all the details can be found in the [upstream documentation](https://docs.nextcloud.com/server/latest/admin_manual/configuration_server/occ_command.html). You can run occ commands in the `opendesk-nextcloud-php` pod like this: `php /var/www/html/occ config:list` ## OpenProject -OpenProject is a Ruby on Rails application. Therefore you can make use of the Rails console from the pod's command line `bundle exec rails console` - +OpenProject is a Ruby on Rails application. Therefore, you can make use of the Rails console from the Pod's command line `bundle exec rails console` and run debug code like this: ``` uri = URI('https://nextcloud.url/apps/integration_openproject/check-config') Net::HTTP.start(uri.host, uri.port, - :use_ssl => uri.scheme == 'https') do |http| - request = Net::HTTP::Get.new uri - response = http.request request # Net::HTTPResponse object + :use_ssl => uri.scheme == 'https') do |http| + request = Net::HTTP::Get.new uri + response = http.request request # Net::HTTPResponse object end ``` ## PostgreSQL -When using the openDesk bundled PostgreSQL you can explore database(s) using the PostgreSQL interactive terminal from the pod's command line: `psql -U postgres`. +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: diff --git a/docs/development.md b/docs/development.md index f51ed6c2..990082d6 100644 --- a/docs/development.md +++ b/docs/development.md @@ -7,7 +7,7 @@ SPDX-License-Identifier: Apache-2.0

Developing openDesk deployment automation

Active development on the deployment is currently only available for project members. -But contributions will be possible soon once the CLA process is sorted out. +However, contributions will be possible using the CLA process. * [Overview](#overview) * [Default branch, `develop` and other branches](#default-branch-develop-and-other-branches) @@ -17,31 +17,31 @@ But contributions will be possible soon once the CLA process is sorted out. * [Renovate](#renovate) * [Mirroring](#mirroring) * [Get new artifacts mirrored](#get-new-artifacts-mirrored) -* [Creating new charts / images](#creating-new-charts--images) +* [Creating new charts/images](#creating-new-chartsimages) # Overview -The following sketch provides an high level overview to get a basic understanding of the deployment relevant -structure of this repository. An understanding of that structure is vital if you want to contribute to -the development of the deployment automation of openDesk. +The following sketch provides a high-level overview to get a basic understanding of the deployment-relevant +structure of this repository. Understanding that structure is vital if you want to contribute to +developing the openDesk platform. ```mermaid flowchart TD - J[helmfile.yaml\nor a helmfile outside of this repository]-->A - J-->K[./helmfile/environemnts/*your_environment*/values.yaml.gotmpl\nor any an environment values file] - A[./helmfile_generic.yaml]-->B[./helmfile/apps/*all_configured_apps*/helmfile.yaml\nReferences the relevant app Helm\ncharts using details from 'charts.yaml'] - B-->C[./values-*all_configured_components*.yaml.gotmpl\nValues to template the charts\nwith references to the `images.yaml`] - A-->D[./helmfile/environments/default/*\nwith just some examples below] - D-->F[charts.yaml] - D-->G[images.yaml] - D-->H[global.*] - D-->I[secrets.yaml\nreplicas.yaml\nresources.yaml\n...] - A-->|overwrite defaults with your\ndeployment/environment specific values|E[./helmfile/environments/default/values.yaml.gotmpl] + J[helmfile.yaml\nor a helmfile outside of this repository]-->A + J-->K[./helmfile/environemnts/*your_environment*/values.yaml.gotmpl\nor any an environment values file] + A[./helmfile_generic.yaml]-->B[./helmfile/apps/*all_configured_apps*/helmfile.yaml\nReferences the relevant app Helm\ncharts using details from 'charts.yaml'] + B-->C[./values-*all_configured_components*.yaml.gotmpl\nValues to template the charts\nwith references to the `images.yaml`] + A-->D[./helmfile/environments/default/*\nwith just some examples below] + D-->F[charts.yaml] + D-->G[images.yaml] + D-->H[global.*] + D-->I[secrets.yaml\nreplicas.yaml\nresources.yaml\n...] + A-->|overwrite defaults with your\ndeployment/environment specific values|E[./helmfile/environments/default/values.yaml.gotmpl] ``` -The `helmfile.yaml` file in the root folder serves as the foundation +The `helmfile.yaml` file in the root folder is the foundation for the entire deployment. It references the `helmfile_generic.yaml` -file, which includes app-specific `helmfile.yaml` files, as well as +file, which includes app-specific `helmfile.yaml` files and global values files located in `./environments/default`. `helmfile.yaml` also refers to three predefined environments: `dev`, @@ -51,27 +51,26 @@ The `helmfile_generic.yaml` file is designed to be referenced from external repositories, where custom environments may be defined. An example is demonstrated in the `helmfile.yaml` file. -Before you look into any app specific configuration it is recommended to review the contents of `./environments/default` to get an understanding of what -details are maintained in there, as they are usually referenced by the app configurations. +Before you investigate any app-specific configuration, it is recommended that you review the contents of `./helmfile/environments/default` to understand what configuration details are set there, as the app deployments reference them. # Default branch, `develop` and other branches The `main` branch is configured to be the default branch, as visitors of the project on Open CoDE should see that branch by default. -Please use the `develop` branch to diverge your own branch(es) from. See the [workflow guide](./workflow.md) +Please use the `develop` branch to diverge your branch(es) from. See the [workflow guide](./workflow.md) for more details on naming conventions. -There is a CI bot that automatically creates a merge request once you initially pushed your branch to Open CoDE. -The merge request will of course target the `develop` branch, be in status `draft` and have you as assignee. +There is a CI bot that automatically creates a merge request once you initially push your branch to Open CoDE. +Of course, the merge request will target the `develop` branch, be in status `draft`, and you are set as the assignee. -In case you do not plan to actually merge from the branch you have pushed, please close or delete the auto-created MR. +If you do not plan to merge from the branch you have pushed, please close the auto-created MR. # External artifacts - `charts.yaml` and `images.yaml` -The `charts.yaml` and `images.yaml` are the central place to reference external artifacts that are used for the deployment. +The `charts.yaml` and `images.yaml` files are the central place to reference external artifacts used for the deployment. -Beside the deployment automation itself some tools work with the contents of the files: +Besides the deployment automation itself, some tools work with the contents of the files: - **Linting**: Ensures consistency of the file contents for the other tools. - **Renovate**: Automatically create MRs that update the components to their latest version. @@ -81,35 +80,35 @@ 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 +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). -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 probably -want to fix it by running the CLI tool locally. +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. -**Note**: Please ensure that in component blocks you use comments only at the beginning of the block or at its end. Ideally you just stick +> **Note**
+> Please ensure that in component blocks, you use comments only at the beginning of the block or at its end. Ideally, you stick with the many available examples in the yaml files. Example: -``` - synapse: - # providerCategory: "Supplier" - # providerResponsible: "Element" - # upstreamRegistry: "https://registry-1.docker.io" - # upstreamRepository: "matrixdotorg/synapse" - # upstreamMirrorTagFilterRegEx: '^v(\d+)\.(\d+)\.(\d+)$' - # upstreamMirrorStartFrom: ["1", "91", "2"] - registry: "registry.opencode.de" - repository: "bmi/opendesk/components/supplier/element/images-mirror/synapse" - tag: "v1.91.2@sha256:1d19508db417bb2b911c8e086bd3dc3b719ee75c6f6194d58af59b4c32b11322" +```yaml + synapse: + # providerCategory: "Supplier" + # providerResponsible: "Element" + # upstreamRegistry: "https://registry-1.docker.io" + # upstreamRepository: "matrixdotorg/synapse" + # upstreamMirrorTagFilterRegEx: '^v(\d+)\.(\d+)\.(\d+)$' + # upstreamMirrorStartFrom: ["1", "91", "2"] + registry: "registry.opencode.de" + repository: "BMI/opendesk/components/supplier/element/images-mirror/synapse" + tag: "v1.91.2@sha256:1d19508db417bb2b911c8e086bd3dc3b719ee75c6f6194d58af59b4c32b11322" ``` ### Disable linting selectively -If you follow the "push early, push often" paradigm to save your work to the central Git instance or you just fix a typo in the text -of an existing documentation you might want to avoid the CI with its linting to be executed, as it might not offer additional value. +If you follow the "push early, push often" paradigm to save your work to the central Git instance, or you just fix a typo in +existing documentation, you can avoid the CI and its linting being executed, as it might not offer additional value. GitLab offers two options to skip the CI on a commit/push: - Add `[ci skip]` to your commit message ([details](https://docs.gitlab.com/ee/ci/pipelines/#skip-a-pipeline)). @@ -124,43 +123,42 @@ Uses a regular expression to match the values of the following attributes: - `# upstreamRepository` *required* - `tag` *required* -Checks for newer versions of the given artefact and creates a MR containing the newest version's tag (and digest). +Checks for newer versions of the given artifact and creates an MR containing the newest version's tag (and digest). ## Mirroring - See also: https://gitlab.opencode.de/bmi/opendesk/tooling/oci-pull-mirror -**Note:** The mirror is scheduled to run every hour at 42 minutes past the hour. +> **Note:**
+> The mirror is scheduled to run every hour at 42 minutes past the hour. -openDesk strives to make all relevant artifacts available on Open CoDE so there is the mirroring process +openDesk strives to make all relevant artifacts available on Open CoDE so there is a mirroring process configured to pull artifacts that do not originate from Open CoDE into projects called `*-Mirror` within the [openDesk Components section](https://gitlab.opencode.de/bmi/opendesk/components). 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 specific that key all uppercase: - - `MIRROR_CREDENTIALS_SRC__USERNAME` - - `MIRROR_CREDENTIALS_SRC__PASSWORT` +- `# 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__PASSWORT` - `# upstreamRepository` *required*: To identify the source repository -- `# upstreamMirrorTagFilterRegEx` *required*: If this annotation is set it activates the mirror for the component. Only tags are being mirrored that match the given regular expression. **Note:** You have to use single quotes for this attribute's value in case 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 groups - 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. +- `# 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`. +- `# 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. ### Get new artifacts mirrored -If you want new images or charts to be mirrored that are not yet included in one of the yaml files there are two options: +If you want new images or charts mirrored that are not yet included in one of the yaml files, you can add them in your branch, including the aforementioned mirror annotations, and ask somebody from the platform development team to trigger the mirror's CI based on your branch. -You include them in your branch with all required annotations and either -1. ask somebody from the platform development team to trigger the mirror's CI based on your branch or -2. you get your branch merged to `develop` already. +Once your branch is merged into develop, your artifacts are mirrored hourly. -# Creating new charts / images +# Creating new charts/images -When you create new Helm charts please check out the +When you create new Helm charts, please check out the [openDesk Best Practices](https://gitlab.opencode.de/bmi/opendesk/components/platform-development/charts/opendesk-best-practises) for Helm charts. You may also want to make use of our [standard CI](https://gitlab.opencode.de/bmi/opendesk/tooling/gitlab-config) to -easily get Charts and Images that are signed, linted, scanned and released. +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. diff --git a/docs/enhanced-configuration.md b/docs/enhanced-configuration.md index 6c140e70..288984b3 100644 --- a/docs/enhanced-configuration.md +++ b/docs/enhanced-configuration.md @@ -9,6 +9,7 @@ SPDX-License-Identifier: Apache-2.0 The following enhanced configuration use cases are described in separate documents. -- [Separate mail & Matrix domain](enhanced-configuration/separate-mail-matrix-domain.md) -- [Federation with external identity provider](enhanced-configuration/idp-federation.md) -- [Matrix federation](enhanced-configuration/matrix-federation.md) +- [Separate mail & Matrix domain](./enhanced-configuration/separate-mail-matrix-domain.md) +- [Federation with external identity provider](./enhanced-configuration/idp-federation.md) +- [Matrix federation](./enhanced-configuration/matrix-federation.md) +- [Groupware migration from M365 to openDesk](./enhanced-configuration/groupware-migration.md) diff --git a/docs/enhanced-configuration/groupware-migration.md b/docs/enhanced-configuration/groupware-migration.md new file mode 100644 index 00000000..2c3e6f5b --- /dev/null +++ b/docs/enhanced-configuration/groupware-migration.md @@ -0,0 +1,185 @@ +r + +

Migration from M365 with audriga migration service and master authentication

+ +* [Context](#context) +* [Prerequisites](#prerequisites) + * [Prepare M365 tenant for access](#prepare-m365-tenant-for-access) + * [Provisioning user accounts in openDesk](#provisioning-user-accounts-in-opendesk) + * [Deploy openDesk with master authentication](#deploy-opendesk-with-master-authentication) +* [Migration configuration](#migration-configuration) + * [Select the source provider and configure your openDesk instance](#select-the-source-provider-and-configure-your-opendesk-instance) + * [Adding accounts](#adding-accounts) + * [Add user accounts individually](#add-user-accounts-individually) + * [Add multiple user accounts via CSV file](#add-multiple-user-accounts-via-csv-file) + * [Start the migration](#start-the-migration) + * [Monitor migration status](#monitor-migration-status) + +# Context + +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 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). + +# Prerequisites + +## Prepare M365 tenant for access + +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: + +***1. Select one account to serve as a service account*** + +Please note that the account that shall serve as the service account requires a Microsoft 365/Exchange online license (mailbox). + +> **Notes**
+> If you want to designate your admin account as a service account, you have to provide the admin with a license. + +***2. Register the audriga app in your tenant*** + +To register the audriga app in your tenant, log into your admin account and access the following URL: + + 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. + +> **Note**
+> The audriga application is created under the "Enterprise application" tab in the AzureAD console. + +***3. Create a "secret" group in the M365 tenant*** + +Create a "secret" group in the customer tenant. + +- Go to > Azure Active Directory > Groups > New Group +- Choose a group name and group email address that includes the word "audriga" in lowercase ("Audriga" will not work), like *audriga-migration@your-maildomain.tld* +- Choose the group type "Microsoft 365" +- Appoint your service account (see 1.) as the owner of this group + + +## Provisioning user accounts in openDesk + +In openDesk, you have to have all user accounts with mailboxes pre-defined before running the migration. You can either manually create your accounts using an IAM administrator or use the [user import tool](https://gitlab.opencode.de/bmi/opendesk/components/platform-development/images/user-import) to batch import user accounts to your openDesk deployment. + +## 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: + +``` +secrets: + oxAppsuite: + adminPassword: "your_temporary_master_password" +functional: + migration: + oxAppsuite: + enabled: true +``` + +1. You must specify the master password referenced in the document's following sections. +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. + +> **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. + +# Migration configuration + +The migration is configured in 3 steps using the [audriga migration self-service](https://umzug.audriga.com/SMESwitchWebApp/?client=groupware). + +Ensure you meet the prerequisites. For example, this document does not support using the standard username/password-based authentication option for M365. + +## Select the source provider and configure your openDesk instance + +Choose [Microsoft 365 / Exchange Online (Admin)](https://umzug.audriga.com/SMESwitchWebApp/?client=groupware#src=onmicrosoft.com) as your current provider. + +> **Note**
+> You may need to start typing in "Microsoft Office 365/Exchange Online" for it to appear in the list. + +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. +- On the tab "Open-Xchange" +  - 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 + +You can add accounts one by one, which seems only feasible for test scenarios, or when you migrate a handful of mailboxes, or you can add accounts using CSV upload. Both options are described in the following subsections. + +### Add user accounts individually + +By default, you will enter the "Add Mailbox" tab where you can add individual accounts for M365: + +``` +Username:             enter the username of the service account, e.g. eva@your-maildomain.tld +Password:             enter the particular group email address, e.g. audriga-migration@your-maildomain.tld +Details -> mailbox:   enter the user's mailbox you want to migrate, e.g. pia@your-maildomain.tld +``` + +On the openDesk site, please provide: +``` +Username:             enter the username of the mailbox you want to migrate to, e.g. pia@your-maildomain.tld +Password:             enter the master password +``` + +Click on check to verify the credentials. If the data is correct, a green checkmark will appear. A red cross will be displayed if the credentials need to be corrected. + +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. + +### Add multiple user accounts via CSV file + +Prepare a CSV file with all necessary information. Unsurprisingly, this is the same information as described in the "Add User Accounts Individually" section above. + +The CSV requires the following column order with a closing semicolon after the last value - but no headline is expected; the first line must be your migration data already: +``` +M365ServiceAccount;M365GroupEmailAddress;M365Mailbox;openDeskMailbox;openDeskMasterPassword; +``` + +Example CSV: +``` +eva@your-maildomain.tld;audriga-migration@your-maildomain.tld;eva@your-maildomain.tld;eva;YourMasterPassword; +eva@your-maildomain.tld;audriga-migration@your-maildomain.tld;max@your-maildomain.tld;max;YourMasterPassword; +eva@your-maildomain.tld;audriga-migration@your-maildomain.tld;pia@your-maildomain.tld;pia;YourMasterPassword; +eva@your-maildomain.tld;audriga-migration@your-maildomain.tld;ida@your-maildomain.tld;ida;YourMasterPassword; +``` + +Select the "Add multiple accounts" tab to configure up to 50 user accounts by uploading a CSV file. If you need to migrate more accounts, you can execute the migration multiple times. + +Click "Check" and save afterwards. + +## Start the migration + +You will see a summary of the migration, including the number of accounts and the amount of data. Even if the analysis of the source accounts has not yet been completed, you can proceed. + +Ensure you have a valid voucher; otherwise, you must complete the payment process. + +Press "Start Migration" to proceed. + +## Monitor migration status + +The migration process may take some time to start. For large amounts of data, it may take a couple of hours. + +Click on "Details" to get further information about the migration. + +You can access a detailed log for each account by clicking "Protocol" on the right-hand side. Here, you can see detected duplicates or encountered errors (e.g., if emails cannot be transferred due to your provider's size limitations). + +You will receive status emails for the migration job's submission and start, as well as when the migration job is finished. The emails are sent to the email address you have entered during the configuration. Those emails include a link to the status website so you can easily track and monitor your migration. Once the migration has been started, you can safely close the status website and shut down your computer; the migration will continue. You can re-open the status website anytime. diff --git a/docs/enhanced-configuration/idp-federation.md b/docs/enhanced-configuration/idp-federation.md index 04a83046..d7367b8a 100644 --- a/docs/enhanced-configuration/idp-federation.md +++ b/docs/enhanced-configuration/idp-federation.md @@ -20,109 +20,107 @@ SPDX-License-Identifier: Apache-2.0 # Context -Most organizations already have an Identity and Access Management (IAM) of their own that includes 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 to internal or external web applications. -This document shows how to configure your organizations IdP as well as the openDesk IdP to allow account federation to support single-sign-on to openDesk based on your organization's login. +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. # Prerequisites ## User accounts -Beside the configuration it is required that the user accounts with the same name exist within openDesk. This prerequisite is outside the scope of this document. - -We will provide additional documents regarding user provisioning in the future, so here's just an overview regarding potential scenarios: +In addition to the configuration, it is required that user accounts with the same name exist within openDesk. While this prerequisite is outside the scope of this document, the following approaches are feasible: - Manual user management - - That is a lightweight way for testing your IdP federation setup or in case you just have a small amount of users to manage. - - Just create and maintain you user(s) in openDesk and ensure the username in your IAM and openDesk is identical. + - A lightweight option to test your IdP federation setup or if you have only a small number of users to manage. + - Create and maintain your user(s) in openDesk and ensure the username in your IAM and openDesk is identical. - User import - - If you need to create more than just a couple of test accounts you can use the [openDesk User Importer](https://gitlab.opencode.de/bmi/opendesk/tooling/user-import) that utilizes the UDM REST API for user account creation. + - If you need to create more than just a couple of test accounts, you can use the [openDesk User Importer](https://gitlab.opencode.de/bmi/opendesk/components/platform-development/images/user-import) that utilizes the UDM REST API for user account creation. - Downsides: Managing groups and deleting accounts needs to be done manually. - Automated Pre-provisioning: - - Pre-provisioning users and groups including de-provisioning (deleting) accounts is the best practice as it ensures that openDesk is in sync with your organization's IAM. + - Pre-provisioning users and groups, including de-provisioning (deleting) accounts, is the best practice to ensure that openDesk is in sync with your organization's IAM. - There are at least two ways of implementing the pre-provisioning: - UDM REST API: - - Build a provisioning solution by yourself using the [UDM REST API](https://docs.software-univention.de/developer-reference/5.0/en/udm/rest-api.html). - - The API gives you full control over the contents of the IAM in order to create, update or delete users and groups. + - Build a provisioning solution using the [UDM REST API](https://docs.software-univention.de/developer-reference/5.0/en/udm/rest-api.html). + - The API gives you complete control over the contents of the IAM to create, update, or delete users and groups. - Nubus Directory Importer: - It is based on a Python one-way directory synchronization for users and groups. - Please find more details in the [upstream product's documentation](https://docs.software-univention.de/nubus-kubernetes-operation/latest/en/howto-connect-external-iam.html). - Ad-hoc provisioning (AHP) - - This feature is currently not available in the openDesk Keycloak, but there are plans by the Supplier Univention to make it available. - - Ad-hoc provisioning creates an user account on the fly during a users first login. - - While AHP this is a nice approach for a quick start with openDesk it has various downsides: - - Users are just created after their first login, so you cannot find your colleagues in the openDesk apps unless they already logged in. + - 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. - A user account would never be deactivated or deleted in openDesk. - Group memberships are not transferred. ## External IdP with OIDC -This document focusses on the OIDC federation between an external IdP and the openDesk IdP. It makes use of the OpenID Connect (OIDC) protocol, so your external IdP must support OIDC. +This document focuses on the OIDC federation between an external IdP and the openDesk IdP. It uses the OpenID Connect (OIDC) protocol, so your external IdP must support OIDC. # Example configuration ## 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 separation of the configuration. +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 -The following values are used in this example documentation. Please ensure when you come across such a value even if it is part of a URL hostname or path that you adapt it where needed to your setup: +The following values are used in this example documentation. Please ensure when you come across such a value, even if it is part of a URL hostname or path, that you adapt it where needed to your setup: -- `idp.organization.tld`: hostname for your organization's IdP -- `id.opendesk.tld`: hostname for the openDesk IdP, so openDesk is obviously deployed at `opendesk.tld` -- `fed-test-idp-realm`: realm name for your organizations IdP -- `opendesk-federation-client`: OIDC client for the openDesk federation that is defined in your organizations IdP -- `auto-federate-idp`: Identifier of your organizations IdP's configuration within the openDesk Keycloak. +- `idp.organization.tld`: hostname for your organization's IdP. +- `id.opendesk.tld`: hostname for the openDesk IdP, so openDesk is deployed at `opendesk.tld`. +- `fed-test-idp-realm`: realm name for your organization's IdP. +- `opendesk-federation-client`: OIDC client for the openDesk federation defined in your organization's IdP. +- `auto-federate-idp`: Identifier of your organization IdP's configuration within the openDesk Keycloak. - `auto-federate-flow`: Identifier of the required additional login flow to be created and referenced in the openDesk Keycloak. ## Keycloak admin console access -To access the admin console of Keycloak in an openDesk deployment you need to 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 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. The admin console will be available at: - Organization's IdP: https://idp.organization.tld/admin/master/console/ - openDesk IdP: https://id.opendesk.tld/admin/master/console/ -For the following configuration steps login with user `kcadmin` and grab the password from the `ums-keycloak` pod's `KEYCLOAK_ADMIN_PASSWORD` variable. +For the following configuration steps, log in with user `kcadmin` and grab the password from the `ums-keycloak` pod's `KEYCLOAK_ADMIN_PASSWORD` variable. ## Your organizations IdP -As we use the Keycloak of another openDesk instance to simulate your organization's IdP in this example, especially URL paths within the Keycloak might differ if you use different products. +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. ### Separate realm -To not interfere with an existing configuration for our test scenario we create a separate realm: +To not interfere with an existing configuration for our test scenario, we create a separate realm: -- `Create realm` (from realm selection drop down menu in the left upper corner) +- `Create realm` (from the realm selection drop-down menu in the left upper corner) - *Realm name*: `fed-test-idp-realm` - `Create` ### OIDC Client -If you just created the `fed-test-idp-realm` your are already in the admin screen for the realm, if not use the realm selection drop down menu in the left upper corner to switch to the realm. +If you just created the `fed-test-idp-realm`, you are already in the admin screen for the realm; if not, use the realm selection drop-down menu in the upper left corner to switch to the realm. - *Clients* > *Create Client* - 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 you IdP's UI and therefore should explain what the client is used for) + - *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) - Client create wizard page 2: - *Client authentication*: `On` - *Authorization*: `Off` (default) - *Authentication flow*: leave defaults - - `Standard flow` - - `Direct access grants` + - `Standard flow` + - `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 configured 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` - Tab *Credentials* - - Copy the *Client Secret* as we need it for the configuration of the openDesk IdP to be used in the openDesk IdP, as well as the *Client-ID*. + - Copy the *Client Secret* and the *Client-ID* as we need them to configure the openDesk IdP. ## openDesk IdP @@ -137,20 +135,20 @@ The following configuration is taking place in the Keycloak realm `opendesk`. - *Identity providers* > *User-defined* > *OpenID Connect 1.0* - *Alias*: `auto-federate-idp` (used in our example) - - *Display Name*: Descriptive Name in case you do not forcefully redirect the user to the IdP that name is shown in the login screen for manual selection. + - *Display Name*: A descriptive Name, in case you do not forcefully redirect the user to the IdP, that name is shown on the login screen for manual selection. - *Use discovery endpoint*: `On` (default) - *Discovery endpoint*: `https://idp.organization.tld/realms/fed-test-idp-realm/.well-known/openid-configuration` - this URL may look different if you do not use Keycloak or a different Keycloak version as IdP in your organization - - In case the IdP metadata could not be auto-discovered you will get an error. - - If everything is fine you can review the discovered metadata for your IdP by clicking on *Show metadata*. + - You will get an error if the IdP metadata cannot be auto-discovered. + - If everything is fine, you can review the discovered metadata for your IdP by clicking on *Show metadata*. - *Client authentication*: `Client secret sent as post` (default) - - *Client ID*: Use the client ID you took form your organization's IdP config (`opendesk-federation-client` in this example) - - *Client Secret*: Use the secret you took form your organization's IdP config - - When completed with *Add* you get to the detailed IdP configured that also needs some updates (you may need to open the *Advanced* section to access some settings) + - *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 configured that also needs some updates (you may need to open the *Advanced* section to access some settings) - *Back-channel logout*: `On` - *Disable user info*: `On` - *First login flow override*: `auto-federate-flow` -- In case you want to forcefully redirect all users to your organizations IdP (disabling login with local openDesk accounts): +- In case you want to forcefully redirect all users to your organization's IdP (disabling login with local openDesk accounts): - *Authentication* > `2fa-browser` - Click on the cogwheel next to the *Identity Provider Re-director* - *Alias*: `auto-federate-idp` diff --git a/docs/enhanced-configuration/matrix-federation.md b/docs/enhanced-configuration/matrix-federation.md index dd797284..5a505a97 100644 --- a/docs/enhanced-configuration/matrix-federation.md +++ b/docs/enhanced-configuration/matrix-federation.md @@ -6,20 +6,20 @@ SPDX-License-Identifier: Apache-2.0

Matrix federation

-* [Use case](#use-case) +* [Context](#context) * [Example configuration](#example-configuration) * [Disable federation](#disable-federation) * [Separate Matrix domain](#separate-matrix-domain) -# Use case +# Context 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. -By default, you can chat with users that have an account within your openDesk installation and federate with other +By default, you can chat with users who have an account within your openDesk installation and federate with other matrix-based servers. -Federation support can be disabled. +Federation support can be turned off. # Example configuration @@ -28,36 +28,35 @@ Please ensure when you come across such a value, even if it is part of a URL hostname or path, that you adapt it where needed to your setup: - `opendesk.domain.tld`: the mandatory `DOMAIN` setting for your deployment resulting in -`https://chat.opendesk.domain.tld` to access the Element chat. +`https://chat.opendesk.domain.tld` for access to the Element chat. - `my_organization.tld`: an optional alternative domain used for mail and/or Matrix. -If not used it is also set to `opendesk.domain.tld`. +It is also set to `opendesk.domain.tld` if not used. ## Disable federation -The following setting can disable federation: +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 -the Matrix domain to use delegation. -This is not included inside openDesk. +the Matrix domain to use delegation. It is not part of your openDesk deployment. 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: -[Matrix Delegation](https://matrix-org.github.io/synapse/v1.98/delegate.html) +[Matrix Delegation](https://element-hq.github.io/synapse/latest/delegate.html) diff --git a/docs/enhanced-configuration/separate-mail-matrix-domain.md b/docs/enhanced-configuration/separate-mail-matrix-domain.md index d9e27086..cb96254f 100644 --- a/docs/enhanced-configuration/separate-mail-matrix-domain.md +++ b/docs/enhanced-configuration/separate-mail-matrix-domain.md @@ -3,9 +3,9 @@ SPDX-FileCopyrightText: 2024 Zentrum für Digitale Souveränität der Öffentlic SPDX-License-Identifier: Apache-2.0 --> -

Separate domains for mail and or matrix

+

Separate domains for mail and or Matrix

-* [Use case](#use-case) +* [Context](#context) * [Example configuration](#example-configuration) * [Mail domain](#mail-domain) * [Matrix domain](#matrix-domain) @@ -14,24 +14,24 @@ SPDX-License-Identifier: Apache-2.0 * [Content Security Policy](#content-security-policy) * [.well-known](#well-known) -# Use case +# Context -As communication over mail and chat can go beyond the borders of your openDesk installation you may want to use different domains for the mail and/or matrix. +As communication over mail and chat can go beyond the borders of your openDesk installation, you may want to use different domains for the mail and/or Matrix. # Example configuration -The following values are used in this example documentation. Please ensure when you come across such a value even if it is part of a URL hostname or path that you adapt it where needed to your setup: +The following values are used in this example documentation. Please ensure when you come across such a value, even if it is part of a URL hostname or path, that you adapt it where needed to your setup: - `opendesk.domain.tld`: the mandatory `DOMAIN` setting for your deployment resulting in `https://mail.opendesk.domain.tld` to access emails and `https://chat.opendesk.domain.tld` to access the Element chat that is based on the Matrix protocol. - `my_organization.tld`: the alternative domain used for mail and/or Matrix. ## Mail domain -By default all email addresses in openDesk are created based on the `DOMAIN` you specified for your deployment. In our example resulting in the users having `@opendesk.domain.tld` as mail addresses. In case you prefer the users to send and receive emails with another domain you can set that one using the optional `MAIL_DOMAIN` in the deployment: +By default, all email addresses in openDesk are created based on the `DOMAIN` you specified for your deployment. In our example, the users have `@opendesk.domain.tld` as their mail addresses. In case you prefer the users to send and receive emails with another domain, you can set that one using the optional `MAIL_DOMAIN` in the deployment: ```yaml global: - mailDomain: "my_organization.tld" +  mailDomain: "my_organization.tld" ``` or via environment variable @@ -40,21 +40,21 @@ or via environment variable export MAIL_DOMAIN=my_organization.tld ``` -This of course requires the MX record for the domain to point to the mail host for your openDesk deployment. Optionally add the SPF and DMARC records. +Of course, this requires the domain's MX record to point to the mail host for your openDesk deployment. You can optionally add the SPF and DMARC records. -| Record name | Type | Value | +| Record name                | Type | Value                                            | | -------------------------- | ---- | ------------------------------------------------ | -| my_organization.tld | MX | `10 mail.opendesk.domain.tld` | -| my_organization.tld | TXT | `v=spf1 +a +mx +a:mail.opendesk.domain.tld ~all` | -| _dmarc.my_organization.tld | TXT | `v=DMARC1; p=quarantine` | +| my_organization.tld        | MX   | `10 mail.opendesk.domain.tld` | +| my_organization.tld        | TXT  | `v=spf1 +a +mx +a:mail.opendesk.domain.tld ~all` | +| _dmarc.my_organization.tld | TXT  | `v=DMARC1; p=quarantine` | ## Matrix domain -Similar to the specific domain for email addresses you may want to specify a domain that differs from your deployment's default `DOMAIN` to define your users Matrix IDs. Use the `MATRIX_DOMAIN` to do so: +Similar to the specific domain for email addresses, you may want to specify a domain that differs from your deployment's default `DOMAIN` to define your user's Matrix IDs. Use the `MATRIX_DOMAIN` to do so: ```yaml global: - matrixDomain: "my_organization.tld" +  matrixDomain: "my_organization.tld" ``` or via environment variable @@ -67,17 +67,17 @@ export MATRIX_DOMAIN=my_organization.tld The following changes apply to the standard DNS: -| Record name | Type | Value | Comment | -| -------------------------------- | ---- | -------------------------------------- | ---------------------------------------------------------------------------------- | -| _matrix._tcp.my_organization.tld | SRV | `1 10 PORT matrix.opendesk.domain.tld` | `PORT` is your NodePort/LoadBalancer port of `opendesk-synapse-federation` service | +| Record name | Type | Value | Comment | +| -------------------------------- | ---- | -------------------------------------- | -------------------------------------------------------------------------------------- | +| _matrix._tcp.my_organization.tld | SRV | `1 10 PORT matrix.opendesk.domain.tld` | `PORT` is your NodePort/LoadBalancer port of the `opendesk-synapse-federation` service | -*Note:* `matrix.opendesk.domain.tld` in the "Value" column can also be the IP address where synapse TLS port is listening to. +*Note:* `matrix.opendesk.domain.tld` in the "Value" column can also be the IP address synapse TLS port listens to. ### Webserver #### Content Security Policy -The webserver of `my_organization.tld` should add `*.opendesk.domain.tld` to its CSP header. +The `my_organization.tld` webserver should add `*.opendesk.domain.tld` to its CSP header. #### .well-known @@ -89,11 +89,11 @@ you need to create a JSON file with the following contents that is served from ```json { - "m.homeserver": { - "base_url": "https://matrix.opendesk.domain.tld" +  "m.homeserver": { +    "base_url": "https://matrix.opendesk.domain.tld" } } ``` -This ensures clients know where to find the Matrix protocol endpoint when users specify `my_organization.tld` +The above configuration ensures clients know where to find the Matrix protocol endpoint when users specify `my_organization.tld` as their homeserver. diff --git a/docs/external-services.md b/docs/external-services.md index c961af00..6bc6c795 100644 --- a/docs/external-services.md +++ b/docs/external-services.md @@ -5,7 +5,7 @@ SPDX-License-Identifier: Apache-2.0

External services

-This document will cover the additional configuration to use external services like databases, caches or buckets. +This document will cover the additional configuration for external services like databases, caches, or buckets. * [Database](#database) @@ -15,96 +15,96 @@ This document will cover the additional configuration to use external services l # Database -When deploying this suite to production, you need to configure the applications to use your production grade database +When deploying this suite to production, you need to configure the applications to use your production-grade database service. -| Component | Name | Type | Parameter | Key | Default | +| Component   | Name               | Type       | Parameter | Key                                      | Default                    | |-------------|--------------------|------------|-----------|------------------------------------------|----------------------------| -| Element | Synapse | PostgreSQL | | | | -| | | | Name | `databases.synapse.name` | `matrix` | -| | | | Host | `databases.synapse.host` | `postgresql` | -| | | | Port | `databases.synapse.port` | `5432` | -| | | | Username | `databases.synapse.username` | `matrix_user` | -| | | | Password | `databases.synapse.password` | | -| Keycloak | Keycloak | PostgreSQL | | | | -| | | | Name | `databases.keycloak.name` | `keycloak` | -| | | | Host | `databases.keycloak.host` | `postgresql` | -| | | | Port | `databases.keycloak.port` | `5432` | -| | | | Username | `databases.keycloak.username` | `keycloak_user` | -| | | | Password | `databases.keycloak.password` | | -| | Keycloak Extension | PostgreSQL | | | | -| | | | Name | `databases.keycloakExtension.name` | `keycloak_extensions` | -| | | | Host | `databases.keycloakExtension.host` | `postgresql` | -| | | | Port | `databases.keycloakExtension.port` | `5432` | -| | | | Username | `databases.keycloakExtension.username` | `keycloak_extensions_user` | -| | | | Password | `databases.keycloakExtension.password` | | -| UMS | Notifications API | PostgreSQL | | | | -| | | | Name | `databases.umsNotificationsApi.name` | `notificationsapi` | -| | | | Host | `databases.umsNotificationsApi.host` | `postgresql` | -| | | | Port | `databases.umsNotificationsApi.port` | `5432` | -| | | | Username | `databases.umsNotificationsApi.username` | `notificationsapi_user` | -| | | | Password | `databases.umsNotificationsApi.password` | | -| | Self Service | PostgreSQL | | | | -| | | | Name | `databases.umsSelfservice.name` | `selfservice` | -| | | | Host | `databases.umsSelfservice.host` | `postgresql` | -| | | | Port | `databases.umsSelfservice.port` | `5432` | -| | | | Username | `databases.umsSelfservice.username` | `selfservice_user` | -| | | | Password | `databases.umsSelfservice.password` | | -| Nextcloud | Nextcloud | MariaDB | | | | -| | | | Name | `databases.nextcloud.name` | `nextcloud` | -| | | | Host | `databases.nextcloud.host` | `mariadb` | -| | | | Username | `databases.nextcloud.username` | `nextcloud_user` | -| | | | Password | `databases.nextcloud.password` | | -| OpenProject | OpenProject | PostgreSQL | | | | -| | | | Name | `databases.openproject.name` | `openproject` | -| | | | Host | `databases.openproject.host` | `postgresql` | -| | | | Port | `databases.openproject.port` | `5432` | -| | | | Username | `databases.openproject.username` | `openproject_user` | -| | | | Password | `databases.openproject.password` | | -| OX Appsuite | OX Appsuite | MariaDB | | | | -| | | | Name | `databases.oxAppsuite.name` | `CONFIGDB` | -| | | | Host | `databases.oxAppsuite.host` | `mariadb` | -| | | | Username | `databases.oxAppsuite.username` | `root` | -| | | | Password | `databases.oxAppsuite.password` | | -| XWiki | XWiki | MariaDB | | | | -| | | | Name | `databases.xwiki.name` | `xwiki` | -| | | | Host | `databases.xwiki.host` | `mariadb` | -| | | | Username | `databases.xwiki.username` | `xwiki_user` | -| | | | Password | `databases.xwiki.password` | | +| Element     | Synapse            | PostgreSQL |           |                                          |                            | +|             |                    |            | Name      | `databases.synapse.name` | `matrix` | +|             |                    |            | Host      | `databases.synapse.host` | `postgresql` | +|             |                    |            | Port      | `databases.synapse.port` | `5432` | +|             |                    |            | Username  | `databases.synapse.username` | `matrix_user` | +|             |                    |            | Password  | `databases.synapse.password` |                            | +| Keycloak    | Keycloak           | PostgreSQL |           |                                          |                            | +|             |                    |            | Name      | `databases.keycloak.name` | `keycloak` | +|             |                    |            | Host      | `databases.keycloak.host` | `postgresql` | +|             |                    |            | Port      | `databases.keycloak.port` | `5432` | +|             |                    |            | Username  | `databases.keycloak.username` | `keycloak_user` | +|             |                    |            | Password  | `databases.keycloak.password` |                            | +|             | Keycloak Extension | PostgreSQL |           |                                          |                            | +|             |                    |            | Name      | `databases.keycloakExtension.name` | `keycloak_extensions` | +|             |                    |            | Host      | `databases.keycloakExtension.host` | `postgresql` | +|             |                    |            | Port      | `databases.keycloakExtension.port` | `5432` | +|             |                    |            | Username  | `databases.keycloakExtension.username` | `keycloak_extensions_user` | +|             |                    |            | Password  | `databases.keycloakExtension.password` |                            | +| UMS         | Notifications API  | PostgreSQL |           |                                          |                            | +|             |                    |            | Name      | `databases.umsNotificationsApi.name` | `notificationsapi` | +|             |                    |            | Host      | `databases.umsNotificationsApi.host` | `postgresql` | +|             |                    |            | Port      | `databases.umsNotificationsApi.port` | `5432` | +|             |                    |            | Username  | `databases.umsNotificationsApi.username` | `notificationsapi_user` | +|             |                    |            | Password  | `databases.umsNotificationsApi.password` |                            | +|             | Self Service       | PostgreSQL |           |                                          |                            | +|             |                    |            | Name      | `databases.umsSelfservice.name` | `selfservice` | +|             |                    |            | Host      | `databases.umsSelfservice.host` | `postgresql` | +|             |                    |            | Port      | `databases.umsSelfservice.port` | `5432` | +|             |                    |            | Username  | `databases.umsSelfservice.username` | `selfservice_user` | +|             |                    |            | Password  | `databases.umsSelfservice.password` |                            | +| Nextcloud   | Nextcloud          | MariaDB    |           |                                          |                            | +|             |                    |            | Name      | `databases.nextcloud.name` | `nextcloud` | +|             |                    |            | Host      | `databases.nextcloud.host` | `mariadb` | +|             |                    |            | Username  | `databases.nextcloud.username` | `nextcloud_user` | +|             |                    |            | Password  | `databases.nextcloud.password` |                            | +| OpenProject | OpenProject        | PostgreSQL |           |                                          |                            | +|             |                    |            | Name      | `databases.openproject.name` | `openproject` | +|             |                    |            | Host      | `databases.openproject.host` | `postgresql` | +|             |                    |            | Port      | `databases.openproject.port` | `5432` | +|             |                    |            | Username  | `databases.openproject.username` | `openproject_user` | +|             |                    |            | Password  | `databases.openproject.password` |                            | +| OX Appsuite | OX Appsuite        | MariaDB    |           |                                          |                            | +|             |                    |            | Name      | `databases.oxAppsuite.name` | `CONFIGDB` | +|             |                    |            | Host      | `databases.oxAppsuite.host` | `mariadb` | +|             |                    |            | Username  | `databases.oxAppsuite.username` | `root` | +|             |                    |            | Password  | `databases.oxAppsuite.password` |                            | +| XWiki       | XWiki              | MariaDB    |           |                                          |                            | +|             |                    |            | Name      | `databases.xwiki.name` | `xwiki` | +|             |                    |            | Host      | `databases.xwiki.host` | `mariadb` | +|             |                    |            | Username  | `databases.xwiki.username` | `xwiki_user` | +|             |                    |            | Password  | `databases.xwiki.password` |                            | # Object storage -When deploying this suite to production, you need to configure the applications to use your production grade object +When deploying this suite to production, you need to configure the applications to use your production-grade object storage service. -| Component | Name | Parameter | Key | Default | +| Component   | Name        | Parameter       | Key                                      | Default            | |-------------|-------------|-----------------|------------------------------------------|--------------------| -| OpenProject | OpenProject | | | | -| | | Backend | `objectstores.openproject.backend` | `minio` | -| | | Bucket | `objectstores.openproject.bucket` | `openproject` | -| | | Endpoint | `objectstores.openproject.endpoint` | | -| | | Provider | `objectstores.openproject.provider` | `AWS` | -| | | Region | `objectstores.openproject.region` | | -| | | Secret | `objectstores.openproject.secret` | | -| | | Username | `objectstores.openproject.username` | `openproject_user` | -| | | Use IAM profile | `objectstores.openproject.useIAMProfile` | | +| OpenProject | OpenProject |                 |                                          |                    | +|             |             | Backend         | `objectstores.openproject.backend` | `minio` | +|             |             | Bucket          | `objectstores.openproject.bucket` | `openproject` | +|             |             | Endpoint        | `objectstores.openproject.endpoint` |                    | +|             |             | Provider        | `objectstores.openproject.provider` | `AWS` | +|             |             | Region          | `objectstores.openproject.region` |                    | +|             |             | Secret          | `objectstores.openproject.secret` |                    | +|             |             | Username        | `objectstores.openproject.username` | `openproject_user` | +|             |             | Use IAM profile | `objectstores.openproject.useIAMProfile` |                    | # Cache -When deploying this suite to production, you need to configure the applications to use your production grade cache +When deploying this suite to production, you need to configure the applications to use your production-grade cache service. -| Component | Name | Type | Parameter | Key | Default | +| Component        | Name             | Type      | Parameter | Key                          | Default          | |------------------|------------------|-----------|-----------|------------------------------|------------------| -| Intercom Service | Intercom Service | Redis | | | | -| | | | Host | `cache.intercomService.host` | `redis-headless` | -| | | | Port | `cache.intercomService.port` | `6379` | -| Nextcloud | Nextcloud | Redis | | | | -| | | | Host | `cache.nextcloud.host` | `redis-headless` | -| | | | Port | `cache.nextcloud.port` | `6379` | -| OpenProject | OpenProject | Memcached | | | | -| | | | Host | `cache.openproject.host` | `memcached` | -| | | | Port | `cache.openproject.port` | `11211` | -| UMS | Self Service | Memcached | | | | -| | | | Host | `cache.umsSelfservice.host` | `memcached` | -| | | | Port | `cache.umsSelfservice.port` | `11211` | +| Intercom Service | Intercom Service | Redis     |           |                              |                  | +|                  |                  |           | Host      | `cache.intercomService.host` | `redis-headless` | +|                  |                  |           | Port      | `cache.intercomService.port` | `6379` | +| Nextcloud        | Nextcloud        | Redis     |           |                              |                  | +|                  |                  |           | Host      | `cache.nextcloud.host` | `redis-headless` | +|                  |                  |           | Port      | `cache.nextcloud.port` | `6379` | +| OpenProject      | OpenProject      | Memcached |           |                              |                  | +|                  |                  |           | Host      | `cache.openproject.host` | `memcached` | +|                  |                  |           | Port      | `cache.openproject.port` | `11211` | +| UMS              | Self Service     | Memcached |           |                              |                  | +|                  |                  |           | Host      | `cache.umsSelfservice.host` | `memcached` | +|                  |                  |           | Port      | `cache.umsSelfservice.port` | `11211` | diff --git a/docs/getting-started.md b/docs/getting-started.md index 88c741ce..8d2b0e61 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -5,7 +5,7 @@ SPDX-License-Identifier: Apache-2.0

Getting started

-This documentation should enable you to create your own evaluation instance of openDesk on your Kubernetes cluster. +This documentation lets you create an openDesk evaluation instance on your Kubernetes cluster. * [Requirements](#requirements) @@ -22,7 +22,7 @@ This documentation should enable you to create your own evaluation instance of o * [Volumes](#volumes) * [Connectivity](#connectivity) * [Ports](#ports) - * [Web based user interface](#web-based-user-interface) + * [Web-based user interface](#web-based-user-interface) * [Mail clients](#mail-clients) * [Mail/SMTP configuration](#mailsmtp-configuration) * [TURN configuration](#turn-configuration) @@ -36,40 +36,39 @@ This documentation should enable you to create your own evaluation instance of o * [Uninstall](#uninstall) -Thanks for looking into the openDesk Getting started guide. This documents covers essentials configuration steps to -deploy openDesk onto your kubernetes infrastructure. +Thanks for looking into the openDesk Getting Started guide. This document covers essential configuration steps to +deploy openDesk onto your Kubernetes infrastructure. # Requirements -Detailed system requirements are covered on [requirements](requirements.md) page. +Detailed system requirements are covered on the [requirements](requirements.md) page. # Customize environment -Before deploying openDesk, you have to configure the deployment to suit your environment. -To keep your deployment up to date, we recommend customizing in `dev`, `test` or `prod` and not in `default` environment +Before deploying openDesk, you must configure the deployment to fit your environment. +To keep your deployment up to date, we recommend customizing in `dev`, `test`, or `prod` and not in `default` environment files. > All configuration options and their default values can be found in files at `helmfile/environments/default/` -For the following guide, we will use `dev` as environment, where variables can be set in +For the following guide, we will use `dev` as environment where variables can be set in `helmfile/environments/dev/values.yaml.gotmpl`. ## DNS The deployment is designed to deploy each application/service under a dedicated subdomain. -For your convenience, we recommend to create a `*.domain.tld` A-Record to your cluster ingress controller, -otherwise you need to create an A-Record for each 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. -| Record name | Type | Value | Additional information | +| 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.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 @@ -79,15 +78,15 @@ All subdomains can be customized. For example, _Nextcloud_ can be changed to `fi ```yaml global: - hosts: - nextcloud: "files" +  hosts: +    nextcloud: "files" ``` -The domain have to be set either via `dev` environment +The domain has to be set either via `dev` environment ```yaml global: - domain: "domain.tld" +  domain: "domain.tld" ``` or via environment variable @@ -98,58 +97,58 @@ export DOMAIN=domain.tld ### Apps -All available apps and their default value can be found in `helmfile/environments/default/workplace.yaml`. +All available apps and their default value are in `helmfile/environments/default/workplace.yaml`. -| Component | Name | Default | Description | +| Component            | Name                        | Default | Description                    | | -------------------- | --------------------------- | ------- | ------------------------------ | -| Certificates | `certificates.enabled` | `true` | TLS certificates | -| ClamAV (Distributed) | `clamavDistributed.enabled` | `false` | Antivirus engine | -| ClamAV (Simple) | `clamavSimple.enabled` | `true` | Antivirus engine | -| Collabora | `collabora.enabled` | `true` | Weboffice | -| CryptPad | `cryptpad.enabled` | `true` | Weboffice | -| Dovecot | `dovecot.enabled` | `true` | Mail backend | -| Element | `element.enabled` | `true` | Secure communications platform | -| Jitsi | `jitsi.enabled` | `true` | Videoconferencing | -| MariaDB | `mariadb.enabled` | `true` | Database | -| Memcached | `memcached.enabled` | `true` | Cache Database | -| MinIO | `minio.enabled` | `true` | Object Storage | -| Nextcloud | `nextcloud.enabled` | `true` | File share | -| Nubus | `nubus.enabled` | `true` | Identity Management & Portal | -| OpenProject | `openproject.enabled` | `true` | Project management | -| OX Appsuite | `oxAppsuite.enabled` | `true` | Groupware | -| Postfix | `postfix.enabled` | `true` | MTA | -| PostgreSQL | `postgresql.enabled` | `true` | Database | -| Redis | `redis.enabled` | `true` | Cache Database | -| XWiki | `xwiki.enabled` | `true` | Knowledge management | +| Certificates         | `certificates.enabled` | `true` | TLS certificates               | +| ClamAV (Distributed) | `clamavDistributed.enabled` | `false` | Antivirus engine               | +| ClamAV (Simple)      | `clamavSimple.enabled` | `true` | Antivirus engine               | +| Collabora            | `collabora.enabled` | `true` | Weboffice                      | +| CryptPad             | `cryptpad.enabled` | `true` | Weboffice                      | +| Dovecot              | `dovecot.enabled` | `true` | Mail backend                   | +| Element              | `element.enabled` | `true` | Secure communications platform | +| Jitsi                | `jitsi.enabled` | `true` | Videoconferencing              | +| MariaDB              | `mariadb.enabled` | `true` | Database                       | +| Memcached            | `memcached.enabled` | `true` | Cache Database                 | +| MinIO                | `minio.enabled` | `true` | Object Storage                 | +| Nextcloud            | `nextcloud.enabled` | `true` | File share                     | +| Nubus                | `nubus.enabled` | `true` | Identity Management & Portal   | +| OpenProject          | `openproject.enabled` | `true` | Project management             | +| OX Appsuite          | `oxAppsuite.enabled` | `true` | Groupware                      | +| Postfix              | `postfix.enabled` | `true` | MTA                            | +| PostgreSQL           | `postgresql.enabled` | `true` | Database                       | +| Redis                | `redis.enabled` | `true` | Cache Database                 | +| XWiki                | `xwiki.enabled` | `true` | Knowledge management           | Exemplary, Jitsi can be disabled like: ```yaml jitsi: - enabled: false +  enabled: false ``` ## Private registries -By default Helm charts and container images are fetched from OCI registries. These registries can be found for most cases +By default, Helm charts and container images are fetched from OCI registries. These registries can be found in most cases in the [openDesk/component section on Open CoDE](https://gitlab.opencode.de/bmi/opendesk/components). -For untouched upstream artifacts that do not belong to a functional component's core we use upstream registries +For untouched upstream artifacts that do not belong to a functional component's core, we use upstream registries like Docker Hub. -Doing a test deployment will most likely 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 anyway you can configure such for +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 [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. ```yaml global: - imageRegistry: "my_private_registry.domain.tld" +  imageRegistry: "my_private_registry.domain.tld" ``` -alternatively you can use an environment variable: +alternatively, you can use an environment variable: ```shell export PRIVATE_IMAGE_REGISTRY_URL=my_private_registry.domain.tld @@ -159,16 +158,16 @@ or control repository override fine-granular per registry: ```yaml repositories: - image: - dockerHub: "my_private_registry.domain.tld/docker.io/" - registryOpencodeDe: "my_private_registry.domain.tld/registry.opencode.de/" +  image: +    dockerHub: "my_private_registry.domain.tld/docker.io/" +    registryOpencodeDe: "my_private_registry.domain.tld/registry.opencode.de/" ``` -If authentication is required, you can reference imagePullSecrets as following: +If authentication is required, you can reference `imagePullSecrets` as follows: ```yaml global: - imagePullSecrets: +  imagePullSecrets: - "external-registry" ``` @@ -178,13 +177,13 @@ global: Some apps, like Jitsi or 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 +You can configure whether `NodePort` (for on-premise), `LoadBalancer` (for cloud), or `ClusterIP` (to disable) should be used: ```yaml cluster: - service: - type: "NodePort" +  service: +    type: "NodePort" ``` ### Networking @@ -193,16 +192,16 @@ If your cluster has not the default `cluster.local` domain configured, you need ```yaml cluster: - networking: - domain: "acme.internal" +  networking: +    domain: "acme.internal" ``` -If your cluster has not the default `10.0.0.0/8` CIDR configured, you need to provide the CIDR via: +If your cluster has not the default `10.0.0.0/8` CIDR configured, you need to provide the CIDR via the following: ```yaml cluster: - networking: - cidr: +  networking: +    cidr: - "127.0.0.0/8" ``` @@ -211,132 +210,131 @@ explicitly configure the related IPs or IP ranges: ```yaml cluster: - networking: - incomingCIDR: +  networking: +    incomingCIDR: - "172.16.0.0/12" ``` ### Ingress -By default, the `ingressClassName` is empty to choose your default ingress controller. You may want to customize it by +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 clusters default ingress. +[requirements.md](./requirements.md)) for reference) within your deployment if that is not the cluster's default ingress. ```yaml ingress: - ingressClassName: "name-of-my-nginx-ingress" +  ingressClassName: "name-of-my-nginx-ingress" ``` ### Container runtime -Some apps require specific configuration for the container runtime. You can set your container runtime like `cri-o`, +Some apps require specific configurations for the container runtime. You can set your container runtime like `cri-o`, `containerd` or `docker` by: ```yaml cluster: - container: - engine: "containerd" +  container: +    engine: "containerd" ``` ### Volumes -When your cluster has a `ReadWriteMany` volume provisioner, you can benefit from distributed or scaling of apps. By +When your cluster has a `ReadWriteMany` volume provisioner, you can benefit from the distribution or scaling of apps. By default, only `ReadWriteOnce` is enabled. To enable `ReadWriteMany` you can set: ```yaml cluster: - persistence: - readWriteMany: true +  persistence: +    readWriteMany: true ``` The **StorageClass** can be set by: ```yaml persistence: - storageClassNames: - RWX: "my-read-write-many-class" - RWO: "my-read-write-once-class" +  storageClassNames: +    RWX: "my-read-write-many-class" +    RWO: "my-read-write-once-class" ``` ## Connectivity ### Ports -**Note:** If you use `NodePort` for service exposure, you need to check your deployment for the actual ports. +**Note:** If you use `NodePort` for service exposure, you must check your deployment for the actual ports. -#### Web based user interface +#### Web-based user interface -To use the openDesk functionality with its web based user interface you need to publicly expose the following ports: +To use the openDesk functionality with its web-based user interface, you need to expose the following ports publicly: -| Component | Description | Port | Type | +| Component          | Description             |  Port | Type | | ------------------ | ----------------------- | ----: | ---: | -| openDesk | Kubernetes Ingress | 80 | TCP | -| openDesk | Kubernetes Ingress | 443 | TCP | -| Jitsi Video Bridge | ICE Port for video data | 10000 | UDP | +| openDesk           | Kubernetes Ingress      |    80 |  TCP | +| openDesk           | Kubernetes Ingress      |   443 |  TCP | +| Jitsi Video Bridge | ICE Port for video data | 10000 |  UDP | #### Mail clients To connect with mail clients like [Thunderbird](https://www.thunderbird.net/), the following ports need public exposure: -| Component | Description | Port | Type | +| Component          | Description             |  Port | Type | | ------------------ | ----------------------- | ----: | ---: | -| Dovecot | IMAPS | 993 | TCP | -| | POP3S | 995 | TCP | -| Postfix | SMTP | 25 | TCP | -| | SMTPS | 587 | TCP | +| Dovecot            | IMAPS                   |   993 |  TCP | +|                    | POP3S                   |   995 |  TCP | +| Postfix            | SMTP                    |    25 |  TCP | +|                    | SMTPS                   |   587 |  TCP | ### Mail/SMTP configuration -To use the full potential of the openDesk, you need to set up an SMTP relay which allows sending emails from +To use the full potential of the openDesk, you need to set up an SMTP relay that allows sending emails from the whole subdomain. ```yaml smtp: - host: "mail.open.desk" - username: "openDesk" - password: "secret" +  host: "mail.open.desk" +  username: "openDesk" +  password: "secret" ``` Enabling DKIM signing of emails helps to reduce spam and increases trust. -openDesk ships dkimpy-milter as Postfix milter for signing mails. +openDesk ships dkimpy-milter as Postfix milter for signing emails. ```yaml dkimpy: - enable: true - dkim: - key: - value: | - HzZs08QF1O7UiAkcM9T3U7rePPECtSFvWZIvyKqdg8E= - selector: "default" - useED25519: true # when false, RSA is used +  enable: true +  dkim: +    key: +      value: "HzZs08QF1O7UiAkcM9T3U7rePPECtSFvWZIvyKqdg8E=" +    selector: "default" +    useED25519: true # when false, RSA is used ``` ### TURN configuration -Some components (Jitsi, Element) use for direct communication a TURN server. You can configure your own TURN server with +Some components (Jitsi, Element) use a TURN server for direct communication. You can configure your own TURN server with these options: ```yaml turn: - transport: "udp" # or tcp - credentials: "secret" - server: - host: "turn.open.desk" - port: "3478" - tls: - host: "turns.open.desk" - port: "5349" +  transport: "udp" # or tcp +  credentials: "secret" +  server: +    host: "turn.open.desk" +    port: "3478" +  tls: +    host: "turns.open.desk" +    port: "5349" ``` ### Certificate issuer -As mentioned in [requirements](requirements.md#certificate-management) you can provide your own valid certificate. A TLS -secret with name `opendesk-certificates-tls` needs to be present in application namespace. For deployment, you can -disable `Certificate` resource creation by: +As mentioned in [requirements](requirements.md#certificate-management), you can provide your own valid certificate. A TLS +secret named `opendesk-certificates-tls` must be present in the application namespace. For deployment, you can +turn off `Certificate` resource creation by: ```yaml certificates: - enabled: false +  enabled: false ``` If you want to leverage the `cert-manager.io` to handle certificates, like `Let's encrypt`, you need to provide the @@ -344,29 +342,29 @@ configured cluster issuer: ```yaml certificate: - issuerRef: - name: "letsencrypt-prod" +  issuerRef: +    name: "letsencrypt-prod" ``` Additionally, it is possible to request wildcard certificates by: ```yaml certificate: - wildcard: true +  wildcard: true ``` ## Password seed -All secrets are generated from a single master password via Master Password (algorithm). -To prevent others from using your openDesk instance, we highly recommend setting an individual master password via: +All secrets are generated from a master password via [Master Password (algorithm)](https://en.wikipedia.org/wiki/Master_Password_(algorithm)). +To prevent others from using your openDesk instance, you must set your individual master password via: ```shell -export MASTER_PASSWORD="openDesk" +export MASTER_PASSWORD="your_individual_master_password" ``` ## Install -After setting your environment specific values in `dev` environment, you can start deployment by: +After setting your environment-specific values in `dev` environment, you can start deployment by: ```shell helmfile apply -e dev -n [-l