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

fix(docs): Spell check and streamline.

Browse Source
This commit is contained in:
Thorsten Roßner
2024-05-17 11:52:05 +02:00
parent 6e4972107e
commit 4d99bf3bf0
14 changed files with 142 additions and 130 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
.reuse/dep5
View File

@@ -1,7 +1,7 @@
Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/ Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
Upstream-Name: openDesk Upstream-Name: openDesk - der Souveräne Arbeitsplatz
Upstream-Contact: <git+bmi-souveraener-arbeitsplatz-cla-1339-29pr0g9pj4or9yi6wfly6pbhg-issue@opencode.de> Upstream-Contact: <opendesk@zendis.de>
Source: https://gitlab.opencode.de/bmi/souveraener_arbeitsplatz/deployment/sovereign-workplace Source: https://gitlab.opencode.de/bmi/opendesk/deployment/opendesk
Files: helmfile/environments/default/theme/* Files: helmfile/environments/default/theme/*
Copyright: 2023 Bundesministerium des Innern und für Heimat, PG ZenDiS "Projektgruppe für Aufbau ZenDiS" Copyright: 2023 Bundesministerium des Innern und für Heimat, PG ZenDiS "Projektgruppe für Aufbau ZenDiS"
@@ -10,3 +10,7 @@ License: Apache-2.0
Files: helmfile/files/gpg-pubkeys/* Files: helmfile/files/gpg-pubkeys/*
Copyright: 2023 Bundesministerium des Innern und für Heimat, PG ZenDiS "Projektgruppe für Aufbau ZenDiS" Copyright: 2023 Bundesministerium des Innern und für Heimat, PG ZenDiS "Projektgruppe für Aufbau ZenDiS"
License: CC0-1.0 License: CC0-1.0
Files: cspell.json
Copyright: 2024 Zentrum für Digitale Souveränität der Öffentlichen Verwaltung (ZenDiS) GmbH
License: Apache-2.0

11
README.md
View File

@@ -31,7 +31,7 @@ openDesk currently features the following functional main components:
| Function | Functional Component | Component<br/>Version | Upstream Documentation | | Function | Functional Component | Component<br/>Version | Upstream Documentation |
| -------------------- | --------------------------- | -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | -------------------- | --------------------------- | -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| Chat & collaboration | Element ft. Nordeck widgets | [1.11.59](https://github.com/element-hq/element-desktop/releases/tag/v1.11.59) | [For the most recent release](https://element.io/user-guide) | | Chat & collaboration | Element ft. Nordeck widgets | [1.11.59](https://github.com/element-hq/element-desktop/releases/tag/v1.11.59) | [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/) | | 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 | [28.0.5](https://nextcloud.com/de/changelog/#28-0-5) | [Nextcloud 28](https://docs.nextcloud.com/) | | File management | Nextcloud | [28.0.5](https://nextcloud.com/de/changelog/#28-0-5) | [Nextcloud 28](https://docs.nextcloud.com/) |
| Groupware | OX App Suite | [8.23](https://documentation.open-xchange.com/appsuite/releases/8.23/) | Online documentation available from within the installed application; [Additional resources](https://www.open-xchange.com/resources/oxpedia) | | Groupware | OX App Suite | [8.23](https://documentation.open-xchange.com/appsuite/releases/8.23/) | Online documentation available from within the installed application; [Additional resources](https://www.open-xchange.com/resources/oxpedia) |
| Knowledge management | XWiki | [15.10.8](https://www.xwiki.org/xwiki/bin/view/Blog/XWiki15108Released) | [For the most recent release](https://www.xwiki.org/xwiki/bin/view/Documentation) | | Knowledge management | XWiki | [15.10.8](https://www.xwiki.org/xwiki/bin/view/Blog/XWiki15108Released) | [For the most recent release](https://www.xwiki.org/xwiki/bin/view/Documentation) |
@@ -41,7 +41,7 @@ openDesk currently features the following functional main components:
| Weboffice | Collabora | [23.05.10.1.1](https://www.collaboraoffice.com/collabora-online-23-05-release-notes/) | Online documentation available from within the installed application; [Additional resources](https://sdk.collaboraonline.com/) | | Weboffice | Collabora | [23.05.10.1.1](https://www.collaboraoffice.com/collabora-online-23-05-release-notes/) | Online documentation available from within the installed application; [Additional resources](https://sdk.collaboraonline.com/) |
While not all components are perfectly shaped for the execution inside containers, one of the project's objectives is to While not all components are perfectly shaped for the execution inside containers, one of the project's objectives is to
align the applications with best practises regarding container design and operations. align the applications with best practices regarding container design and operations.
This documentation aims to give you all that is needed to set up your own instance of the openDesk. This documentation aims to give you all that is needed to set up your own instance of the openDesk.
@@ -91,7 +91,7 @@ Gitlab provides an
[overview on the releases](https://gitlab.opencode.de/bmi/opendesk/deployment/sovereign-workplace/-/releases) [overview on the releases](https://gitlab.opencode.de/bmi/opendesk/deployment/sovereign-workplace/-/releases)
of this project. of this project.
Please find a list of the artefacts related to the release either in the source code archive attached to the release or Please find a list of the artifacts related to the release either in the source code archive attached to the release or
in the files from the release's git-tag: in the files from the release's git-tag:
- `./helmfile/environments/default/images.yaml` - `./helmfile/environments/default/images.yaml`
- `./helmfile/environments/default/charts.yaml` - `./helmfile/environments/default/charts.yaml`
@@ -123,8 +123,7 @@ Copyright (C) 2024 Zentrum für Digitale Souveränität der Öffentlichen Verwal
# Footnotes # Footnotes
[^1]: Nubus is the Cloud Portal and IAM from Univention. [^1]: Nubus is the Cloud Portal and IAM from Univention.
It is currently integrated as a product preview within openDesk therefore, It is currently integrated as a product preview within openDesk therefore, not all resources like documentation
not all resources like documentation and structured release notes are available, and structured release notes are available, while the
while the
[source code can already be found on Open CoDE](https://gitlab.opencode.de/bmi/opendesk/component-code/crossfunctional/univention). [source code can already be found on Open CoDE](https://gitlab.opencode.de/bmi/opendesk/component-code/crossfunctional/univention).
Please find updates regarding the Nubus at https://nubus.io. Please find updates regarding the Nubus at https://nubus.io.

67
cspell.json Normal file
View File

@@ -0,0 +1,67 @@
{
"version": "0.2",
"ignorePaths": [],
"dictionaryDefinitions": [],
"dictionaries": [],
"words": [
"openDesk",
"AppSuite",
"Collabora",
"Digitale",
"Jitsi",
"Nextcloud",
"Öffentlichen",
"OpenProject",
"Souveränität",
"Verwaltung",
"Zentrum",
"Keycloak",
"NATS",
"slapadd",
"slapcat",
"RDBMS",
"Velero",
"Univention",
"OIDC",
"kcadmin",
"DMARC",
"homeserver",
"Bundesministerium",
"Innern",
"Heimat",
"Projektgruppe",
"Aufbau",
"Filepicker",
"Weboffice",
"Xchange",
"opencode",
"seccomp",
"psql",
"databasename",
"helmfile",
"gotmpl",
"containerd",
"letsencrypt",
"CNCF",
"kubespray",
"ICAP",
"Ceph",
"Coturn",
"Minio",
"Kyverno",
"Otterize",
"IBAC",
"pubkeys",
"Grundschutz",
"Kubescape",
"Gitflow",
"hadolint",
"explorative",
"Nordeck",
"Nubus",
"Souveräne",
"Arbeitsplatz"
],
"ignoreWords": [],
"import": []
}

36
docs/components.md
View File

@@ -14,11 +14,9 @@ This section covers the internal system requirements as well as external service
* [Filepicker](#filepicker) * [Filepicker](#filepicker)
* [Central Navigation](#central-navigation) * [Central Navigation](#central-navigation)
* [(Read \& write) Central contacts](#read--write-central-contacts) * [(Read \& write) Central contacts](#read--write-central-contacts)
* [OpenProject Filestore](#openproject-filestore) * [OpenProject file store](#openproject-file-store)
* [Identity data flows](#identity-data-flows) * [Identity data flows](#identity-data-flows)
* [Provisioning](#provisioning) * [Provisioning](#provisioning)
* [Component specific documentation](#component-specific-documentation)
* [Links to component docs](#links-to-component-docs)
<!-- TOC --> <!-- TOC -->
# Overview # Overview
@@ -50,7 +48,7 @@ they need to be replaced in production deployments.
| PostgreSQL | Database | Eval | | PostgreSQL | Database | Eval |
| Redis | Cache Database | Eval | | Redis | Cache Database | Eval |
| Univention Management Stack | Identity Management & Portal | Functional | | Univention Management Stack | Identity Management & Portal | Functional |
| XWiki | Knowledgebase | Functional | | XWiki | Knowledge Management | Functional |
# Component integration # Component integration
@@ -66,7 +64,7 @@ flowchart TD
OXAppSuiteBackend-->|Filepicker|Nextcloud OXAppSuiteBackend-->|Filepicker|Nextcloud
Nextcloud-->|CentralNavigation|Portal Nextcloud-->|CentralNavigation|Portal
OpenProject-->|CentralNavigation|Portal OpenProject-->|CentralNavigation|Portal
OpenProject-->|Filestore|Nextcloud OpenProject-->|File store|Nextcloud
XWiki-->|CentralNavigation|Portal XWiki-->|CentralNavigation|Portal
Nextcloud-->|CentralContacts|OXAppSuiteBackend Nextcloud-->|CentralContacts|OXAppSuiteBackend
OXAppSuiteFrontend-->|Filepicker|OXAppSuiteBackend OXAppSuiteFrontend-->|Filepicker|OXAppSuiteBackend
@@ -106,10 +104,10 @@ Open-Xchange App Suite is used to manage contacts within openDesk. There is an A
Nextcloud to lookup contacts as well as to create contacts. This is maybe done when a file is shared with a not yet Nextcloud to lookup contacts as well as to create contacts. This is maybe done when a file is shared with a not yet
available personal contact. available personal contact.
## OpenProject Filestore ## OpenProject file store
By default, Nextcloud is a configured option for storing attachments in OpenProject. By default, Nextcloud is a configured option for storing attachments in OpenProject.
The Filestore can be enabled on a per-project level in OpenProject's project admin section. The file store can be enabled on a per-project level in OpenProject's project admin section.
# Identity data flows # Identity data flows
@@ -157,27 +155,3 @@ deleting activities for the following objects to the OX AppSuite using the AppSu
- Groups - Groups
- Functional Mailboxes - Functional Mailboxes
- Resources - Resources
# Component specific documentation
We want to provide more information per component in separate, component-specific markdown file.
To establish a common view on the components, we are going to cover various aspects:
- **Component overview**: Shall provide a quick introduction including the components prerequisites and subcomponents (f.e. pods).
- **Resources**: Will contain a link to the component upstream documentation, the helm chart and image locations.
- **Operational Capabilities**
- **Install**: The components install within the SWP.
- **Restart**: Deleting and restarting pods works seamlessly.
- **Update**: Redeploying the component with a different configuration works as expected. The component makes use of the updates configuration afterwards.
- **Upgrade**: Component allows upgrading existing deployments with more current versions of itself.
- **Secrets**: The component uses K8s secrets.
- **Logging**: Only logging to STDOUT, no logs inside the container.
- **Monitoring**: Application provides based on kube-prometheus-stack CRD: ServiceMonitor and PrometheusRule. Optional: Grafana Dashboard.
- **Scale**: If supported (as we use community products) the component should be manually scalable. Optional: Autoscaling.
- **Network policies**: Deny by default, allow application related traffic.
- **Uninstall**: Documented and working complete uninstallation of the component.
- **Debugging**: Some helpful information when it comes to debugging a component, e.g. setting log level.
# Links to component docs
- [Intercom-Service](./components/intercom-service.md)

43
docs/components/intercom-service.md
View File

@@ -1,43 +0,0 @@
<!--
SPDX-FileCopyrightText: 2023 Bundesministerium des Innern und für Heimat, PG ZenDiS "Projektgruppe für Aufbau ZenDiS"
SPDX-License-Identifier: Apache-2.0
-->
**Content / Quick navigation**
[[_TOC_]]
# Component overview
The Intercom Service (ICS) is used to address integrational use cases where the frontend of one application has to call APIs from another application.
# Resources
- External documentation: https://docs.software-univention.de/intercom-service/latest/index.html
- Helm chart: https://gitlab.opencode.de/bmi/souveraener_arbeitsplatz/components/charts/sovereign-workplace-intercom-service
- Image: not yet published on Open CoDE, image will be provided through external artifactory.
# Operational Capabilities
## Install
## Restart
## Update
## Upgrade
## Secrets
## Logging
## Monitoring
## Scale
## Network policies
## Uninstall
# Debugging
ICS does not have a debug level option yet. But please refer to the most current documentation of the component. You just want to look into the standard log output of the component.

16
docs/debugging.md
View File

@@ -31,10 +31,10 @@ environments you may want to make use of them in a very thoughtful and selective
# Enable debugging # Enable debugging
Set `debug.enable` to `true` in [`debug.yaml`](../helmfile/environments/default/debug.yaml) to set the Set `debug.enable` to `true` in [`debug.yaml`](../helmfile/environments/default/debug.yaml) to set the
component's loglevel to debug and it get some features like: component's log level to debug and it get some features like:
- The `/admin` console is routed for Keycloak. - The `/admin` console is routed for Keycloak.
- An ingress for `http://minio-console.<your_domain>` is configured. - An ingress for `http://minio-console.<your_domain>` is configured.
and set the loglevel for components to "Debug". and set the log level for components to "Debug".
**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!
@@ -46,11 +46,11 @@ This can be a challenge the more security hardened container images are, because
Adding a container to a Pod can ease the pain. 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 detailled resources out in the wild. 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.
## Adding a container to a pod/deployment - Dev/Test only ## 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 comforable with tools like [Lens](https://k8slens.dev/). 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's `registry.opencode.de/bmi/opendesk/components/platform-development/images/opendesk-debugging-image:1.0.0`. - Select the container you want to make use of as debugging container, in the example below it's `registry.opencode.de/bmi/opendesk/components/platform-development/images/opendesk-debugging-image:1.0.0`.
- Ensure the `shareProcessNamespace` option is enabled for the Pod. - Ensure the `shareProcessNamespace` option is enabled for the Pod.
@@ -92,8 +92,8 @@ Sometimes you do not want to add a container permanently to your existing deploy
For the commands further down this section we set some environment variables first: 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. - `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 prementioned namespace. - `DEPLOYMENT_NAME`: The name of the deployment 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 prementioned 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. - `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. - `DEBUG_IMAGE`: The image you want to make use of for debugging purposes.
@@ -101,9 +101,9 @@ e.g.
``` ```
export EPH_CONTAINER_NAME=debugging export EPH_CONTAINER_NAME=debugging
export NAMESPACE=my_testdeployment export NAMESPACE=my_test_deployment
export DEPLOYMENT_NAME=opendesk-nextcloud-php export DEPLOYMENT_NAME=opendesk-nextcloud-php
export POD_NAME=opendesk-nextcloud-php-6686d47cfb-7vtmf 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:1.0.0
``` ```

39
docs/development.md
View File

@@ -11,11 +11,12 @@ But contributions will be possible soon once the CLA process is sorted out.
* [Overview](#overview) * [Overview](#overview)
* [Default branch, `develop` and other branches](#default-branch-develop-and-other-branches) * [Default branch, `develop` and other branches](#default-branch-develop-and-other-branches)
* [External artefacts - `charts.yaml` and `images.yaml`](#external-artefacts---chartsyaml-and-imagesyaml) * [External artifacts - `charts.yaml` and `images.yaml`](#external-artifacts---chartsyaml-and-imagesyaml)
* [Linting](#linting) * [Linting](#linting)
* [Disable linting selectively](#disable-linting-selectively)
* [Renovate](#renovate) * [Renovate](#renovate)
* [Mirroring](#mirroring) * [Mirroring](#mirroring)
* [Get new artefacts mirrored](#get-new-artefacts-mirrored) * [Get new artifacts mirrored](#get-new-artifacts-mirrored)
* [Creating new charts / images](#creating-new-charts--images) * [Creating new charts / images](#creating-new-charts--images)
# Overview # Overview
@@ -40,7 +41,7 @@ The `helmfile.yaml` in the root folder is the basis for the whole deployment. It
global values files in `./environments/default`. It allows you to overwrite defaults by using one of the three predefined environments `dev`, `test` global values files in `./environments/default`. It allows you to overwrite defaults by using one of the three predefined environments `dev`, `test`
and `prod`. and `prod`.
Before you look into any app specifc configuration it is recommended to review the contents of `./environments/default` to get an understanding of what 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. details are maintained in there, as they are usually referenced by the app configurations.
# Default branch, `develop` and other branches # Default branch, `develop` and other branches
@@ -54,17 +55,17 @@ 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. 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. The merge request will of course target the `develop` branch, be in status `draft` and have you as assignee.
In case you do not plan to actually merge from the branch you have pushed, please close or delete the autocreated MR. In case you do not plan to actually merge from the branch you have pushed, please close or delete the auto-created MR.
# External artefacts - `charts.yaml` and `images.yaml` # External artifacts - `charts.yaml` and `images.yaml`
The `charts.yaml` and `images.yaml` are the central place to reference external artefacts that are used for the deployment. The `charts.yaml` and `images.yaml` are the central place to reference external artifacts that are used for the deployment.
Beside the deployment automation itself some tools work with the contents of the files: Beside the deployment automation itself some tools work with the contents of the files:
- **Linting**: Ensures consistency of the file contents for the other tools. - **Linting**: Ensures consistency of the file contents for the other tools.
- **Renovate**: Automatically create MRs that update the components to their latest version. - **Renovate**: Automatically create MRs that update the components to their latest version.
- **Mirror**: Mirror artefacts to Open CoDE. - **Mirror**: Mirror artifacts to Open CoDE.
Please find details on these tools below. Please find details on these tools below.
@@ -95,12 +96,22 @@ Example:
tag: "v1.91.2@sha256:1d19508db417bb2b911c8e086bd3dc3b719ee75c6f6194d58af59b4c32b11322" 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.
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)).
**Note:** The string has to be removed before merging your feature branch into `develop`.
- Use the related git push option `git push -o ci.skip` ([details](https://docs.gitlab.com/ee/user/project/push_options.html#push-options-for-gitlab-cicd)).
## Renovate ## Renovate
Uses a regular expression to match the values of the following attributes: Uses a regular expression to match the values of the following attributes:
- `# upstreamRegistry` *required*: Attribute's value must be prefixed with `https://` for Renovate. - `# upstreamRegistry` *required*: Attribute's value must be prefixed with `https://` for Renovate.
- `# upstreamrepository` *required* - `# upstreamRepository` *required*
- `tag` *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 artefact and creates a MR containing the newest version's tag (and digest).
@@ -111,19 +122,19 @@ Checks for newer versions of the given artefact and creates a MR containing the
**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 artefacts available on Open CoDE so there is the mirroring process openDesk strives to make all relevant artifacts available on Open CoDE so there is the mirroring process
configured to pull artefacts that do not originate from Open CoDE into projects called `*-Mirror` within the 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). [openDesk Components section](https://gitlab.opencode.de/bmi/opendesk/components).
The mirror script takes the information on what artefacts to mirror from the annotation inside the two yaml files: 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 - `# upstreamRegistry` *required*: To identify the source registry
- `# upstreamRepository` *required*: To identify the source repository - `# 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`. - `# 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 artefacts beginning with a specific version. You must use capturing groups - `# 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 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. element here to define the version the mirror should start with.
### Get new artefacts mirrored ### 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 to be mirrored that are not yet included in one of the yaml files there are two options:
@@ -134,7 +145,7 @@ You include them in your branch with all required annotations and either
# 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 Practises](https://gitlab.opencode.de/bmi/opendesk/components/platform-development/charts/opendesk-best-practises) [openDesk Best Practices](https://gitlab.opencode.de/bmi/opendesk/components/platform-development/charts/opendesk-best-practises)
for Helm charts. for Helm charts.
You may also want to make use of our [standard CI](https://gitlab.opencode.de/bmi/opendesk/tooling/gitlab-config) to You may also want to make use of our [standard CI](https://gitlab.opencode.de/bmi/opendesk/tooling/gitlab-config) to

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

@@ -39,7 +39,7 @@ We will provide additional documents regarding user provisioning in the future,
- 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/tooling/user-import) that utilizes the UDM REST API for user account creation.
- Downsides: Managing groups and deleting accounts needs to be done manually. - Downsides: Managing groups and deleting accounts needs to be done manually.
- Automated Pre-provisioning: - Automated Pre-provisioning:
- Pre-provisioning users and groups including de-provisioning (deleting) accounts is the best practise 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 as it ensures that openDesk is in sync with your organization's IAM.
- There are at least two ways of implementing the pre-provisioning: - There are at least two ways of implementing the pre-provisioning:
- 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).
@@ -90,7 +90,7 @@ For the following configuration steps login with user `kcadmin` and grab the pas
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. 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.
Please let us know about your experiences or differences you came accross. Please let us know about your experiences or differences you came across.
### Separate realm ### Separate realm
@@ -146,12 +146,12 @@ The following configuration is taking place in the Keycloak realm `opendesk`.
- *Client ID*: Use the client ID you took form your organization's IdP config (`opendesk-federation-client` in this example) - *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 - *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) - 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)
- *Backchannel logout*: `On` - *Back-channel logout*: `On`
- *Disable user info*: `On` - *Disable user info*: `On`
- *First login flow override*: `auto-federate-flow` - *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 organizations IdP (disabling login with local openDesk accounts):
- *Authentication* > `2fa-browser` - *Authentication* > `2fa-browser`
- Click on the cogwheel next to the *Identitify Provider Redirector* - Click on the cogwheel next to the *Identity Provider Re-director*
- *Alias*: `auto-federate-idp` - *Alias*: `auto-federate-idp`
- *Default Identity Provider*: `auto-federate-idp` - *Default Identity Provider*: `auto-federate-idp`

8
docs/external-services.md
View File

@@ -9,7 +9,7 @@ This document will cover the additional configuration to use external services l
<!-- TOC --> <!-- TOC -->
* [Database](#database) * [Database](#database)
* [Objectstore](#objectstore) * [Object storage](#object-storage)
* [Cache](#cache) * [Cache](#cache)
<!-- TOC --> <!-- TOC -->
@@ -72,10 +72,10 @@ service.
| | | | Username | `databases.xwiki.username` | `xwiki_user` | | | | | Username | `databases.xwiki.username` | `xwiki_user` |
| | | | Password | `databases.xwiki.password` | | | | | | Password | `databases.xwiki.password` | |
# Objectstore # Object storage
When deploying this suite to production, you need to configure the applications to use your production grade objectstore When deploying this suite to production, you need to configure the applications to use your production grade object
service. storage service.
| Component | Name | Parameter | Key | Default | | Component | Name | Parameter | Key | Default |
|-------------|-------------|-----------------|------------------------------------------|--------------------| |-------------|-------------|-----------------|------------------------------------------|--------------------|

8
docs/getting-started.md
View File

@@ -132,7 +132,7 @@ jitsi:
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 for most cases
in the [openDesk/component section on Open CoDE](https://gitlab.opencode.de/bmi/opendesk/components). in the [openDesk/component section on Open CoDE](https://gitlab.opencode.de/bmi/opendesk/components).
For untouched upstream artefacts 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. 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 Doing a test deployment will most likely be fine with this setup. In case you want to deploy multiple times a day
@@ -206,7 +206,7 @@ ingress:
### Container runtime ### Container runtime
Some apps require specific configuration for container runtimes. 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`,
`containerd` or `docker` by: `containerd` or `docker` by:
```yaml ```yaml
@@ -239,7 +239,7 @@ persistence:
### Mail/SMTP configuration ### Mail/SMTP configuration
To use the full potential of the openDesk, you need to set up an SMTP Smarthost/Relay which allows to send emails from To use the full potential of the openDesk, you need to set up an SMTP relay which allows to send emails from
the whole subdomain. the whole subdomain.
```yaml ```yaml
@@ -367,7 +367,7 @@ section provide you with the desired information to login with the two default u
| Username | Password | Description | | Username | Password | Description |
|-----------------|--------------------------------------------|------------------| |-----------------|--------------------------------------------|------------------|
| `default.user` | `40615..............................e9e2f` | Application user | | `default.user` | `40615..............................e9e2f` | Application user |
| `default.admin` | `bdbbb..............................04db6` | Administrator | | `default.admin` | `17027..............................04db6` | Administrator |
# Uninstall # Uninstall

10
docs/requirements.md
View File

@@ -20,7 +20,7 @@ This section covers the internal system requirements as well as external service
# tl;dr # tl;dr
openDesk is a Kubernetes only solution and requires an existing Kubernetes (K8s) cluster. openDesk is a Kubernetes only solution and requires an existing Kubernetes (K8s) cluster.
- K8s cluster >= 1.24, [CNCF Certified Kubernetes Distro](https://www.cncf.io/certification/software-conformance/) - K8s cluster >= 1.24, [CNCF Certified Kubernetes distribution](https://www.cncf.io/certification/software-conformance/)
- Domain and DNS Service - Domain and DNS Service
- Ingress controller (supported are nginx-ingress, HAProxy) - Ingress controller (supported are nginx-ingress, HAProxy)
- [Helm](https://helm.sh/) >= v3.9.0 - [Helm](https://helm.sh/) >= v3.9.0
@@ -42,7 +42,7 @@ The following minimal requirements are thought for initial evaluation deployment
# Kubernetes # Kubernetes
Any self-hosted or managed K8s cluster >= 1.24 listed in Any self-hosted or managed K8s cluster >= 1.24 listed in
[CNCF Certified Kubernetes Distros](https://www.cncf.io/certification/software-conformance/) should be supported. [CNCF Certified Kubernetes distributions](https://www.cncf.io/certification/software-conformance/) should be supported.
The deployment is tested against [kubespray](https://github.com/kubernetes-sigs/kubespray) based clusters. The deployment is tested against [kubespray](https://github.com/kubernetes-sigs/kubespray) based clusters.
@@ -78,13 +78,13 @@ openDesk certificate management disabled.
Evaluation the openDesk deployment does not require any external service to start, but features may be limited. Evaluation the openDesk deployment does not require any external service to start, but features may be limited.
| Group | Type | Version | Tested against | | Group | Type | Version | Tested against |
|----------|---------------------|---------|-----------------------| | -------- | ------------------- | ------- | --------------------- |
| Cache | Memached | `1.6.x` | Memached | | Cache | Memcached | `1.6.x` | Memcached |
| | Redis | `7.x.x` | Redis | | | Redis | `7.x.x` | Redis |
| Database | MariaDB | `10.x` | MariaDB | | Database | MariaDB | `10.x` | MariaDB |
| | PostgreSQL | `15.x` | PostgreSQL | | | PostgreSQL | `15.x` | PostgreSQL |
| Mail | Mail Transfer Agent | | Postfix | | Mail | Mail Transfer Agent | | Postfix |
| | PKI/CI (SMIME) | | | | | PKI/CI (S/MIME) | | |
| Security | AntiVirus/ICAP | | ClamAV | | Security | AntiVirus/ICAP | | ClamAV |
| Storage | K8s ReadWriteOnce | | Ceph / Cloud specific | | Storage | K8s ReadWriteOnce | | Ceph / Cloud specific |
| | K8s ReadWriteMany | | Ceph / NFS | | | K8s ReadWriteMany | | Ceph / NFS |

2
docs/scaling.md
View File

@@ -16,7 +16,7 @@ This document should cover the abilities to scale apps.
The Replicas can be increased of almost any component, but is only effective for high-availability or load-balancing for The Replicas can be increased of almost any component, but is only effective for high-availability or load-balancing for
apps with a check-mark in `Scaling (effective)` column. apps with a check-mark in `Scaling (effective)` column.
Verified positive effects are marke with a check-mark in `Scaling (verified)` column, apps which are not yet tested are Verified positive effects are marked with a check-mark in `Scaling (verified)` column, apps which are not yet tested are
marked with a gear. marked with a gear.

2
docs/theming.md
View File

@@ -26,7 +26,7 @@ theme:
# Colors # Colors
The primary color and their derivates with lesser opacity be customized by: The primary color and their derives with lesser opacity be customized by:
```yaml ```yaml
theme: theme:

12
docs/workflow.md
View File

@@ -46,7 +46,7 @@ The following section should provide a high-level view of the involved parties i
- **Open source product suppliers** - **Open source product suppliers**
- Focus areas - Focus areas
- Development of upstream products - Development of upstream products
- Development of integrational functionality relevant to openDesk and others - Development of integrative functionality relevant to openDesk and others
- Providing source code and the artifacts required to install openDesk to Open CoDE - Providing source code and the artifacts required to install openDesk to Open CoDE
- Hand over to _openDesk platform development_ - Hand over to _openDesk platform development_
- Helm charts - Helm charts
@@ -151,7 +151,7 @@ As the way to mark the license header as a comment differs between the various f
### Disclaimer ### Disclaimer
openDesk consists only of community products, so there is no SLA to receive service updates or backports of critical security fixes. This has two consequences: openDesk consists only of community products, so there is no SLA to receive service updates or backport of critical security fixes. This has two consequences:
- In production scenarios, you should replace the community versions of the functional components with supported, SLA-backed paid versions. - In production scenarios, you should replace the community versions of the functional components with supported, SLA-backed paid versions.
- openDesk aims to always update to the latest available releases of the community components and we therefore have rolling technical releases. - openDesk aims to always update to the latest available releases of the community components and we therefore have rolling technical releases.
@@ -230,7 +230,7 @@ The Standard Quality Gate addresses quality assurance steps that should be execu
1. Linting 1. Linting
- Blocking - Blocking
- Licening: [reuse](https://github.com/fsfe/reuse-tool) - Licensing: [reuse](https://github.com/fsfe/reuse-tool)
- openDesk specific: Especially `images.yaml` and `charts.yaml`, find more details in the [development](./development.md) docu - openDesk specific: Especially `images.yaml` and `charts.yaml`, find more details in the [development](./development.md) docu
- Non Blocking - Non Blocking
- Security: [Kyverno policy check](../.kyverno) addressing some IT-Grundschutz requirements - Security: [Kyverno policy check](../.kyverno) addressing some IT-Grundschutz requirements
@@ -249,7 +249,7 @@ The Standard Quality Gate addresses quality assurance steps that should be execu
Steps #1 to #3 from above are executed as GitLab CI and therefore documented within GitLab. Steps #1 to #3 from above are executed as GitLab CI and therefore documented within GitLab.
Step #4 is focussed on security and was not fully implemented yet. Its main objective is to check for regressions. That step is just the second step of a security check and monitoring chain as shown below. While some checks can be executed against the static artefacts (e.g. container images) other might require an up-and-running instance. These are especially located in the third step below which is not yet implemented. Step #4 is focussed on security and was not fully implemented yet. Its main objective is to check for regressions. That step is just the second step of a security check and monitoring chain as shown below. While some checks can be executed against the static artifacts (e.g. container images) other might require an up-and-running instance. These are especially located in the third step below which is not yet implemented.
```mermaid ```mermaid
flowchart TD flowchart TD
@@ -258,7 +258,7 @@ flowchart TD
e.g. based on openDesk e.g. based on openDesk
reference implementation 'gitlab-config'. reference implementation 'gitlab-config'.
>> Can the artefact be integrated? << >> Can the artefact be integrated? <<
] -->|integrate Artefacts| B[<u><b>Deployment automation</b></u> SQG ] -->|integrate artifacts| B[<u><b>Deployment automation</b></u> SQG
based on GitLab CI during based on GitLab CI during
technical release process. technical release process.
>> Can the platform be released? << >> Can the platform be released? <<
@@ -311,7 +311,7 @@ This branch type requires the most activities on top of the actual development:
- This is the actual interface between the platform development workflow and the supplier work package workflow. - This is the actual interface between the platform development workflow and the supplier work package workflow.
- The openDesk QA team validates the change, ideally based on the acceptance criteria defined in the supplier's work package definition. - The openDesk QA team validates the change, ideally based on the acceptance criteria defined in the supplier's work package definition.
- If improvements are needed QA passes on the feedback to the developer/supplier. - If improvements are needed QA passes on the feedback to the developer/supplier.
- If the QA was successful test cases for the testautomation of the feature are defined. - If the QA was successful test cases for the test automation of the feature are defined.
- QA should also evaluate if there is a need for end-user documentation of the feature. - QA should also evaluate if there is a need for end-user documentation of the feature.
- `Develop Test`: The test cases are implemented by the openDesk platform development and added to the openDesk end-to-end test suite. - `Develop Test`: The test cases are implemented by the openDesk platform development and added to the openDesk end-to-end test suite.
- `Documentation`: When required the documentation team has to update the end-user documentation. - `Documentation`: When required the documentation team has to update the end-user documentation.