fix(docs): Various updates

.gitlab-ci.yml

@@ -1,4 +1,5 @@
 # SPDX-FileCopyrightText: 2023 Bundesministerium des Innern und für Heimat, PG ZenDiS "Projektgruppe für Aufbau ZenDiS"
+# SPDX-FileCopyrightText: 2024 Zentrum für Digitale Souveränität der Öffentlichen Verwaltung (ZenDiS) GmbH
 # SPDX-License-Identifier: Apache-2.0
 ---
 include:
@@ -42,14 +43,15 @@ variables:
     description: "The name of namespaces to deploy to."
     value: ""
   CLUSTER:
-    description: "Define which cluster to use. Cluster must be defined in gitlab/environments.yaml of
+    description: "Which cluster to use. Cluster must be defined in `gitlab/environments.yaml` of the
-      sovereign-workplace-env included above."
+        repo that is included above using the env var `PROJECT_PATH_CUSTOM_ENVIRONMENT_CONFIG`:
+        ${PROJECT_PATH_CUSTOM_ENVIRONMENT_CONFIG}"
     value: "dev"
   MASTER_PASSWORD_WEB_VAR:
-    description: "Optional: Provide a passphrase to be used for password generation."
+    description: "Optional: Provide a seed to be used for generation of all internal secrets. Same seed will result in same secrets."
     value: ""
   ENV_STOP_BEFORE:
-    description: "Stop environment/delete namespace for the deployment"
+    description: "Stop environment/delete namespace for the deployment."
     value: "no"
     options:
       - "yes"
@@ -452,7 +454,7 @@ avscan-prepare:
           $CI_PIPELINE_SOURCE =~ "push|merge_request_event"
       when: "always"
     - when: "never"
-  image: "external-registry.souvap-univention.de/docker-remote/mikefarah/yq"
+  image: "${CI_DEPENDENCY_PROXY_DIRECT_GROUP_IMAGE_PREFIX}/mikefarah/yq"
   script:
     - |
       cat << 'EOF' > dynamic-scans.yml
@@ -566,7 +568,7 @@ release:
     - |
       echo -e "\n[INFO] Writing data to helm value file..."
       cat <<EOF >helmfile/environments/default/global.generated.yaml
-      # SPDX-FileCopyrightText: 2024 Bundesministerium des Innern und für Heimat, PG ZenDiS "Projektgruppe für Aufbau ZenDiS"
+      # SPDX-FileCopyrightText: 2024 Zentrum für Digitale Souveränität der Öffentlichen Verwaltung (ZenDiS) GmbH
       # SPDX-License-Identifier: Apache-2.0
       ---
       global:

docs/components.md

@@ -1,5 +1,6 @@
 <!--
 SPDX-FileCopyrightText: 2023 Bundesministerium des Innern und für Heimat, PG ZenDiS "Projektgruppe für Aufbau ZenDiS"
+SPDX-FileCopyrightText: 2024 Zentrum für Digitale Souveränität der Öffentlichen Verwaltung (ZenDiS) GmbH
 SPDX-License-Identifier: Apache-2.0
 -->
 <h1>Components</h1>
@@ -34,7 +35,6 @@ they need to be replaced in production deployments.
 | ClamAV (Simple)             | Antivirus engine               | Eval       |
 | Collabora                   | Weboffice                      | Functional |
 | CryptPad                    | Weboffice                      | Functional |
-| Dovecot                     | Mail backend                   | Functional |
 | Element                     | Secure communications platform | Functional |
 | Intercom Service            | Cross service data exchange    | Functional |
 | Jitsi                       | Videoconferencing              | Functional |
@@ -44,7 +44,8 @@ they need to be replaced in production deployments.
 | Nextcloud                   | File share                     | Functional |
 | OpenProject                 | Project management             | Functional |
 | OX Appsuite                 | Groupware                      | Functional |
-| Provisioning                | Backend provisioning           | Functional |
+| OX Dovecot                  | Mail backend (IMAP)            | Functional |
+| Provisioning (OX Connector) | Groupware provisioning         | Functional |
 | Postfix                     | MTA                            | Eval       |
 | PostgreSQL                  | Database                       | Eval       |
 | Redis                       | Cache Database                 | Eval       |

docs/development.md

@@ -1,5 +1,6 @@
 <!--
 SPDX-FileCopyrightText: 2024 Bundesministerium des Innern und für Heimat, PG ZenDiS "Projektgruppe für Aufbau ZenDiS"
+SPDX-FileCopyrightText: 2024 Zentrum für Digitale Souveränität der Öffentlichen Verwaltung (ZenDiS) GmbH
 SPDX-License-Identifier: Apache-2.0
 -->
 
@@ -32,7 +33,7 @@ flowchart TD
     D-->G[images.yaml]
     D-->H[global.*]
     D-->I[secrets.yaml\nreplicas.yaml\nresources.yaml\n...]
-    A-->|overwrite defaults with\nyour environment specific values|E[./helmfile/environments/*your_environment*/values.yaml.gotmpl]
+    A-->|overwrite defaults with your\ndeployment/environment specific values|E[./helmfile/environments/*your_environment*/values.yaml.gotmpl]
 ```
 
 The `helmfile.yaml` in the root folder is the basis for the whole deployment. It references the app specific `helmfile.yaml` files as well as some
@@ -96,13 +97,13 @@ Example:
 
 ## Renovate
 
-- See also: https://gitlab.opencode.de/bmi/opendesk/tooling/renovate-opencode
+Uses a regular expression to match the values of the following attributes:
 
-Uses a regular expression to match the values of the attributes
+- `registry`
-- `# upstreamRegistry`
+- `repository`
-- `# upstreamRepository`
 - `tag`
-check for newer versions of the given artefact and create 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).
 
 ## Mirroring
 

docs/workflow.md

@@ -1,5 +1,6 @@
 <!--
 SPDX-FileCopyrightText: 2023 Bundesministerium des Innern und für Heimat, PG ZenDiS "Projektgruppe für Aufbau ZenDiS"
+SPDX-FileCopyrightText: 2024 Zentrum für Digitale Souveränität der Öffentlichen Verwaltung (ZenDiS) GmbH
 SPDX-License-Identifier: Apache-2.0
 -->
 
@@ -139,17 +140,19 @@ As a standard, the openDesk platform development team uses [reuse.software](http
 
 openDesk uses Apache 2.0 as the license for their work. A typical reuse copyright and license header looks like this:
 ```
-# SPDX-FileCopyrightText: 2023 Bundesministerium des Innern und für Heimat, PG ZenDiS "Projektgruppe für Aufbau ZenDiS"
+# SPDX-FileCopyrightText: 2024 Zentrum für Digitale Souveränität der Öffentlichen Verwaltung (ZenDiS) GmbH
 # SPDX-License-Identifier: Apache-2.0
 ```
 As the way to mark the license header as a comment differs between the various filetypes, please find matching examples for the types all across the [deployment automation repository](https://gitlab.opencode.de/bmi/souveraener_arbeitsplatz/deployment/sovereign-workplace).
 
+**Remark**: If there is already an existing `SPDX-FileCopyrightText` please just add the one from the above example.
+
 ## Development workflow
 
 ### 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:
-- In production scenarios, you should replace the community versions of the functional components with supported, SLA-backend 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.
 
 ### Workflow
@@ -225,22 +228,28 @@ gitGraph
 
 The Standard Quality Gate addresses quality assurance steps that should be executed within each of the mentioned quality gates in the workflow.
 
+1. Linting
+   - Blocking
+     - Licening: [reuse](https://github.com/fsfe/reuse-tool)
+     - openDesk specific: Especially `images.yaml` and `charts.yaml`, find more details in the [development](./development.md) docu
+   - Non Blocking
+     - Security: [Kyverno policy check](../.kyverno) addressing some IT-Grundschutz requirements
+     - Formal: Yaml
 1. Deploy the full openDesk stack from scratch:
    - All deployment steps must be successful (green)
    - All tests from the end-to-end test set must be successful
-2. Update deployment[^3] of the full openDesk stack and apply the quality measures from the step #1:
+1. Update deployment[^3] of the full openDesk stack and apply the quality measures from the step #1:
    - Deploy the current merge target baseline (`develop` or `main`)
    - Update deploy from your QA branch into the instance from the previous step
-3. No showstopper found regarding
+1. No showstopper found regarding
    - SBOM compliance[^4]
    - Malware check
    - CVE check[^5]
    - Kubescape scan[^5]
-   - Kyverno policy check (also covering some basic requirements from IT-Grundschutz)[^5]
 
-Steps #1 and #2 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 #3 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 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.
 
 ```mermaid
 flowchart TD

helmfile/environments/default/charts.yaml

@@ -1,7 +1,9 @@
 # SPDX-FileCopyrightText: 2023 Bundesministerium des Innern und für Heimat, PG ZenDiS "Projektgruppe für Aufbau ZenDiS"
+# SPDX-FileCopyrightText: 2024 Zentrum für Digitale Souveränität der Öffentlichen Verwaltung (ZenDiS) GmbH
 # SPDX-License-Identifier: Apache-2.0
 #
 # Please read the /docs/development.md for information about structure and annotations used in this file.
+# yamllint disable rule:line-length
 ---
 charts:
   certificates:

helmfile/environments/default/global.yaml

@@ -1,4 +1,5 @@
 # SPDX-FileCopyrightText: 2023 Bundesministerium des Innern und für Heimat, PG ZenDiS "Projektgruppe für Aufbau ZenDiS"
+# SPDX-FileCopyrightText: 2024 Zentrum für Digitale Souveränität der Öffentlichen Verwaltung (ZenDiS) GmbH
 # SPDX-License-Identifier: Apache-2.0
 ---
 ## The global properties are used to configure multiple charts at once.
@@ -9,9 +10,7 @@ global:
   hosts:
     collabora: "collabora"
     cryptpad: "cryptpad"
-    dimension: "integration"
     element: "chat"
-    etherpad: "etherpad"
     intercomService: "ics"
     jitsi: "meet"
     keycloak: "id"

helmfile/environments/default/secrets.gotmpl

@@ -1,5 +1,6 @@
 {{/*
 SPDX-FileCopyrightText: 2023 Bundesministerium des Innern und für Heimat, PG ZenDiS "Projektgruppe für Aufbau ZenDiS"
+SPDX-FileCopyrightText: 2024 Zentrum für Digitale Souveränität der Öffentlichen Verwaltung (ZenDiS) GmbH
 SPDX-License-Identifier: Apache-2.0
 */}}
 ---
@@ -77,10 +78,8 @@ secrets:
     jicofoAuthPassword: {{ derivePassword 1 "long" (env "MASTER_PASSWORD" | default "sovereign-workplace") "jistiStandalone" "jicofoAuthPassword" | sha1sum | quote }}
     jicofoComponentPassword: {{ derivePassword 1 "long" (env "MASTER_PASSWORD" | default "sovereign-workplace") "jistiStandalone" "jicofoComponentPassword" | sha1sum | quote }}
     jvbAuthPassword: {{ derivePassword 1 "long" (env "MASTER_PASSWORD" | default "sovereign-workplace") "jistiStandalone" "jvbAuthPassword" | sha1sum | quote }}
-  etherpad:
-    apiKey: {{ derivePassword 1 "long" (env "MASTER_PASSWORD" | default "sovereign-workplace") "etherpad" "apiKey" | sha1sum | quote }}
   whiteboard:
-    apiKey: {{ derivePassword 1 "long" (env "MASTER_PASSWORD" | default "sovereign-workplace") "etherpad" "apiKey" | sha1sum | quote }}
+    apiKey: {{ derivePassword 1 "long" (env "MASTER_PASSWORD" | default "sovereign-workplace") "whiteboard" "apiKey" | sha1sum | quote }}
   centralnavigation:
     apiKey: {{ derivePassword 1 "long" (env "MASTER_PASSWORD" | default "sovereign-workplace") "centralnavigation" "api_key" | sha1sum | quote }}
   redis: