sheppy/opendesk
1
0
Fork 0
mirror of https://gitlab.opencode.de/bmi/opendesk/deployment/opendesk.git synced 2025-12-06 23:41:43 +01:00
Code Issues Packages Projects Releases Wiki Activity

fix(docs): Various updates.

Browse Source
This commit is contained in:
Thorsten Roßner
2024-08-08 18:08:42 +02:00
parent ce03400043
commit 8aa1a7fa7d
4 changed files with 68 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/enhanced-configuration/idp-federation.md
View File

@@ -44,9 +44,9 @@ We will provide additional documents regarding user provisioning in the future,
- UDM REST API: - 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). - 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. - The API gives you full control over the contents of the IAM in order to create, update or delete users and groups.
- Directory Connector: - Nubus Directory Importer:
- It is based on a Python one-way directory synchronization for users and groups. - It is based on a Python one-way directory synchronization for users and groups.
- We will provide more details on this approach soon one the tool is made publicly available. - 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) - 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. - 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. - Ad-hoc provisioning creates an user account on the fly during a users first login.

18
docs/enhanced-configuration/separate-mail-matrix-domain.md
View File

@@ -9,6 +9,10 @@ SPDX-License-Identifier: Apache-2.0
* [Example configuration](#example-configuration) * [Example configuration](#example-configuration)
* [Mail domain](#mail-domain) * [Mail domain](#mail-domain)
* [Matrix domain](#matrix-domain) * [Matrix domain](#matrix-domain)
* [DNS](#dns)
* [Webserver](#webserver)
* [Content Security Policy](#content-security-policy)
* [.well-known](#well-known)
# Use case # Use case
@@ -59,7 +63,9 @@ or via environment variable
export MATRIX_DOMAIN=my_organization.tld export MATRIX_DOMAIN=my_organization.tld
``` ```
This setup requires also a different DNS setup: ### DNS
The following changes apply to the standard DNS:
| Record name | Type | Value | Comment | | Record name | Type | Value | Comment |
| -------------------------------- | ---- | -------------------------------------- | ---------------------------------------------------------------------------------- | | -------------------------------- | ---- | -------------------------------------- | ---------------------------------------------------------------------------------- |
@@ -67,6 +73,14 @@ This setup requires also a different DNS setup:
*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 where synapse TLS port is listening to.
### Webserver
#### Content Security Policy
The webserver of `my_organization.tld` should add `*.opendesk.domain.tld` to it's CSP header.
#### .well-known
If you want to use other Matrix clients, If you want to use other Matrix clients,
e.g., Element Messenger for [iOS](https://apps.apple.com/de/app/element-messenger/id1083446067) e.g., Element Messenger for [iOS](https://apps.apple.com/de/app/element-messenger/id1083446067)
or [Android](https://play.google.com/store/apps/details?id=im.vector.app), or [Android](https://play.google.com/store/apps/details?id=im.vector.app),
@@ -82,4 +96,4 @@ you need to create a JSON file with the following contents that is served from
``` ```
This ensures clients know where to find the Matrix protocol endpoint when users specify `my_organization.tld` This ensures clients know where to find the Matrix protocol endpoint when users specify `my_organization.tld`
as their homeserver. as their homeserver.

13
docs/getting-started.md
View File

@@ -52,7 +52,7 @@ files.
> All configuration options and their default values can be found in files at `helmfile/environments/default/` > 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`. `helmfile/environments/dev/values.yaml.gotmpl`.
## DNS ## DNS
@@ -115,13 +115,13 @@ All available apps and their default value can be found in `helmfile/environment
| Memcached | `memcached.enabled` | `true` | Cache Database | | Memcached | `memcached.enabled` | `true` | Cache Database |
| MinIO | `minio.enabled` | `true` | Object Storage | | MinIO | `minio.enabled` | `true` | Object Storage |
| Nextcloud | `nextcloud.enabled` | `true` | File share | | Nextcloud | `nextcloud.enabled` | `true` | File share |
| Nubus | `nubus.enabled` | `true` | Identity Management & Portal |
| OpenProject | `openproject.enabled` | `true` | Project management | | OpenProject | `openproject.enabled` | `true` | Project management |
| OX Appsuite | `oxAppsuite.enabled` | `true` | Groupware | | OX Appsuite | `oxAppsuite.enabled` | `true` | Groupware |
| Provisioning | `oxConnector.enabled` | `true` | Backend provisioning | | Provisioning | `oxConnector.enabled` | `true` | Backend provisioning |
| Postfix | `postfix.enabled` | `true` | MTA | | Postfix | `postfix.enabled` | `true` | MTA |
| PostgreSQL | `postgresql.enabled` | `true` | Database | | PostgreSQL | `postgresql.enabled` | `true` | Database |
| Redis | `redis.enabled` | `true` | Cache Database | | Redis | `redis.enabled` | `true` | Cache Database |
| Nubus | `nubus.enabled` | `true` | Identity Management & Portal |
| XWiki | `xwiki.enabled` | `true` | Knowledge management | | XWiki | `xwiki.enabled` | `true` | Knowledge management |
Exemplary, Jitsi can be disabled like: Exemplary, Jitsi can be disabled like:
@@ -201,16 +201,15 @@ cluster:
### Ingress ### 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 choose your default ingress controller. You may want to customize it by
setting: 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.
```yaml ```yaml
ingress: ingress:
ingressClassName: "cilium" ingressClassName: "name-of-my-nginx-ingress"
``` ```
**Note:** Please check the [requirements.md](./requirements.md) for the supported Ingress controllers.
### Container runtime ### Container runtime
Some apps require specific configuration for the container runtime. You can set your container runtime like `cri-o`, Some apps require specific configuration for the container runtime. You can set your container runtime like `cri-o`,

62
docs/migrations.md
View File

@@ -6,14 +6,17 @@ SPDX-License-Identifier: Apache-2.0
<h1>Upgrade migrations</h1> <h1>Upgrade migrations</h1>
* [Disclaimer](#disclaimer) * [Disclaimer](#disclaimer)
* [From v0.9.0](#from-v090) * [Releases upgrades](#releases-upgrades)
* [Automated migrations](#automated-migrations) * [From v0.9.0](#from-v090)
* [Updated IAM component Nubus](#updated-iam-component-nubus) * [Automated migrations](#automated-migrations)
* [Manual cleanup](#manual-cleanup) * [Updated IAM component Nubus](#updated-iam-component-nubus)
* [From v0.8.1](#from-v081) * [Manual cleanup](#manual-cleanup)
* [Updated `cluster.networking.cidr`](#updated-clusternetworkingcidr) * [From v0.8.1](#from-v081)
* [Updated customizable template attributes](#updated-customizable-template-attributes) * [Updated `cluster.networking.cidr`](#updated-clusternetworkingcidr)
* [`migrations` S3 bucket](#migrations-s3-bucket) * [Updated customizable template attributes](#updated-customizable-template-attributes)
* [`migrations` S3 bucket](#migrations-s3-bucket)
* [Related components and artefacts](#related-components-and-artefacts)
* [Development](#development)
# Disclaimer # Disclaimer
@@ -24,14 +27,16 @@ Though we try to ease the pain when it comes to 0.x upgrades. That is what this
Limitations: Limitations:
- We assume that the PV reclaim policy is set to `delete`, so expect that PVs get deleted as soon as the related PVC was deleted and will cover an explicit delete for PVs. - We assume that the PV reclaim policy is set to `delete`, so expect that PVs get deleted as soon as the related PVC was deleted and will cover an explicit delete for PVs.
# From v0.9.0 # Releases upgrades
## Automated migrations ## From v0.9.0
### Updated IAM component Nubus ### Automated migrations
openDesk is integrating the latest [Nubus](https://www.univention.de/produkte/nubus/) development from Univention. The new redundant and scalable LDAP requires migration activities. These have been automated to avoid manual interaction. The `run_2` of the openDesk #### Updated IAM component Nubus
upgrade migrations executes the following steps
openDesk is integrating the latest [Nubus](https://www.univention.de/produkte/nubus/) development from Univention. The now redundant and scalable LDAP requires migration activities. These have been automated to avoid manual interaction. The `run_2` of the openDesk
upgrade migrations executes the following steps:
- Stage PRE: - Stage PRE:
- Delete service `ums-keycloak`, as it will be recreated headless. - Delete service `ums-keycloak`, as it will be recreated headless.
@@ -40,7 +45,7 @@ upgrade migrations executes the following steps
- Stage POST: - Stage POST:
- Restart Keycloak. - Restart Keycloak.
#### Manual cleanup ##### Manual cleanup
Currently we do not execute possible cleanup steps as part of the migrations POST stage. So you might want to remove the no longer used PVCs after successful upgrade: Currently we do not execute possible cleanup steps as part of the migrations POST stage. So you might want to remove the no longer used PVCs after successful upgrade:
``` ```
@@ -49,14 +54,14 @@ kubectl -n ${NAMESPACE} delete pvc shared-data-ums-ldap-server-0
kubectl -n ${NAMESPACE} delete pvc shared-run-ums-ldap-server-0 kubectl -n ${NAMESPACE} delete pvc shared-run-ums-ldap-server-0
``` ```
# From v0.8.1 ## From v0.8.1
## Updated `cluster.networking.cidr` ### Updated `cluster.networking.cidr`
- Action: `cluster.networking.cidr` is now an array (was a string until 0.8.1), please update your setup accordingly if you explicitly set this value. - Action: `cluster.networking.cidr` is now an array (was a string until 0.8.1), please update your setup accordingly if you explicitly set this value.
- Reference:[cluster.yaml](https://gitlab.opencode.de/bmi/opendesk/deployment/opendesk/-/blob/main/helmfile/environments/default/cluster.yaml) - Reference:[cluster.yaml](https://gitlab.opencode.de/bmi/opendesk/deployment/opendesk/-/blob/main/helmfile/environments/default/cluster.yaml)
## Updated customizable template attributes ### Updated customizable template attributes
- Action: Please ensure you update you custom deployment values according with the updated default value structure. - Action: Please ensure you update you custom deployment values according with the updated default value structure.
- References: - References:
@@ -65,7 +70,28 @@ kubectl -n ${NAMESPACE} delete pvc shared-run-ums-ldap-server-0
- `monitoring.` prefix for `prometheus.*` and `graphana.*`, see [monitoring.yaml](https://gitlab.opencode.de/bmi/opendesk/deployment/opendesk/-/blob/main/helmfile/environments/default/monitoring.yaml). - `monitoring.` prefix for `prometheus.*` and `graphana.*`, see [monitoring.yaml](https://gitlab.opencode.de/bmi/opendesk/deployment/opendesk/-/blob/main/helmfile/environments/default/monitoring.yaml).
- `smtp.` prefix for `localpartNoReply`, see [smtp.yaml](https://gitlab.opencode.de/bmi/opendesk/deployment/opendesk/-/blob/main/helmfile/environments/default/smtp.yaml). - `smtp.` prefix for `localpartNoReply`, see [smtp.yaml](https://gitlab.opencode.de/bmi/opendesk/deployment/opendesk/-/blob/main/helmfile/environments/default/smtp.yaml).
## `migrations` S3 bucket ### `migrations` S3 bucket
- Action: For self managed/external S3/object storages, please ensure you add a bucket `migrations` to your S3. - Action: For self managed/external S3/object storages, please ensure you add a bucket `migrations` to your S3.
- Reference: `objectstores.migrations` in [objectstores.yaml](https://gitlab.opencode.de/bmi/opendesk/deployment/opendesk/-/blob/main/helmfile/environments/default/objectstores.yaml) - Reference: `objectstores.migrations` in [objectstores.yaml](https://gitlab.opencode.de/bmi/opendesk/deployment/opendesk/-/blob/main/helmfile/environments/default/objectstores.yaml)
# Related components and artefacts
openDesk comes with two upgrade steps as part of the deployment, they can be found in the folder [/helmfile/apps](../helmfile/apps/) as all other components:
- `migrations-pre`: Is the very first app that gets deployed.
- `migrations-post`: Is the last app that gets deployed.
Both migrations have to be deployed exclusively at their first/last position and not in parallel with other components.
The status of the upgrade migrations is tracked in the ConfigMap `migrations-status`, more details can be found in the [README.md of the related container image](https://gitlab.opencode.de/bmi/opendesk/components/platform-development/images/opendesk-migrations/README.md).
## Development
When a new upgrade migration is required, ensure to address the following list:
- Update the generated release version file [`global.generated.yaml`](../helmfile/environments/default/global.generated.yaml) at least on the patch level to test the upgrade in your feature branch as well as trigger it in the `develop` branch after the feature branch was merged. The set value gets overwritten during the release process with the release's actual version number.
- You have to implement the migration logic as a runner script in the [`opendesk-migrations`](https://gitlab.opencode.de/bmi/opendesk/components/platform-development/images/opendesk-migrations) image. Please find more instructions in the linked repository.
- You most likely have to update the [`opendesk-migrations` Helm chart](https://gitlab.opencode.de/bmi/opendesk/components/platform-development/charts/opendesk-migrations) within the `rules` section of the [`role.yaml`](https://gitlab.opencode.de/bmi/opendesk/components/platform-development/charts/opendesk-migrations/-/blob/main/charts/opendesk-migrations/templates/role.yaml) to provide the permissions required for the execution of your migration's logic.
- You have to set the runner's ID you want to execute in the [migrations.yaml.gotmpl](../helmfile/shared/migrations.yaml.gotmpl). See also the `migrations.*` section of [the Helm chart's README.md](https://gitlab.opencode.de/bmi/opendesk/components/platform-development/charts/opendesk-migrations/-/blob/main/charts/opendesk-migrations/README.md).
- Update the [`charts.yaml`](../helmfile/environments/default/charts.yaml) and [`images.yaml`](../helmfile/environments/default/images.yaml) to reflect the newer releases of the `opendesk-migrations` Helm chart and container image.