feat(docs): Update various chapters and structure

.gitlab-ci.yml

@@ -27,8 +27,8 @@ variables:
       - "develop"
       - "hubble"
       - "prototype"
-  TLD:
+  BASE_DOMAIN:
-    description: "Define the Cluster Domain (TLD)."
+    description: "Define the Cluster Base Domain."
     value: "souvap-univention.de"
     options:
       - "souvap-univention.de"
@@ -116,8 +116,8 @@ variables:
       - "yes"
       - "no"
   # please use the following set of variables with normalized names:
-  DOMAIN: "${NAMESPACE}.${CLUSTER}.${TLD}"
+  DOMAIN: "${NAMESPACE}.${CLUSTER}.${BASE_DOMAIN}"
-  ISTIO_DOMAIN: "${NAMESPACE}.istio.${CLUSTER}.${TLD}"
+  ISTIO_DOMAIN: "${NAMESPACE}.istio.${CLUSTER}.${BASE_DOMAIN}"
 
 .deploy-common:
   cache: {}

README.md

@@ -40,6 +40,10 @@ Especially check out the section
 ["Mitwirkung und Beteiligung"](https://gitlab.opencode.de/bmi/souveraener_arbeitsplatz/info/-/blob/main/OVERVIEW.md#mitwirkung-und-beteiligung)
 if you are missing something or you have questions. We appreciate your feedback to improve product and documentation.
 
+# Deployment
+
+**Note for project members:** You can use the project's `dev` K8s cluster to setup your own development instance. Please see the project `sovereign-workplace-env` on the internal Gitlab for more details.
+
 ## Prerequisites
 
 ### Mandatory technical prerequisites
@@ -68,15 +72,15 @@ You need to expose following variables to run the installation.
 
 | name                | default                      | description                                       |
 |---------------------|------------------------------|---------------------------------------------------|
-| `DOMAIN`            | `souvap-univention.de`       | External reachable TLD                            |
+| `DOMAIN`            | `souvap-univention.de`       | External reachable domain                         |
-| `ISTIO_DOMAIN`      | `istio.souvap-univention.de` | External reachable TLD for Istio Gateway          |
+| `ISTIO_DOMAIN`      | `istio.souvap-univention.de` | External reachable domain for Istio Gateway       |
 | `MASTER_PASSWORD`   | `sovereign-workplace`        | The password that seeds the autogenerated secrets |
 | `SMTP_PASSWORD`     |                              | Password for STMP relay gateway                   |
 | `TURN_CREDENTIALS`  |                              | Credentials for coturn server                     |
 
 Please ensure you have set DNS records pointing to the respective loadbalancer/IP for `DOMAIN` and `ISTIO_DOMAIN`.
 
-If you want inbound mail also MX records that point to the Postfix's pods public IP.
+If you want inbound mail also use MX records that point to the Postfix's pods public IP.
 
 More details on the DNS options incl. SPF/DKIM and autodiscovery options to come...
 
@@ -91,9 +95,7 @@ All of these requirements are optional as long as you do not want to make use of
 | S/MIME Support               | OX AppSuite8   | PKI / CI                    |
 | Improved videoconferencing   | Jitsi          | STUN/TURN server            |
 
-## Deployments
+## CI based deployment
-
-### CI based
 
 The project includes a `.gitlab-ci.yml` that allows you to execute the deployment from a Gitlab instance of your choice.
 
@@ -101,18 +103,18 @@ Please ensure you provide the variables listed in the `Required input variables`
 
 When starting the CI through the Gitlab UI you will be queried for some of the variables plus the following ones:
 
-- `TLD`: The base domain the SWP will be installed at e.g. `souvap.cloud`
+- `BASE_DOMAIN`: The base domain the SWP will be installed at e.g. `souvap.cloud`
 - `NAMESPACE`: Defines into which namespace of your K8s cluster the SWP will be installed
 - `MASTER_PASSWORD_WEB_VAR`: Overwrite value of `MASTER_PASSWORD`
 
 Based on your input the following variables will be set:
-- `DOMAIN` = `NAMESPACE`.`TLD`
+- `DOMAIN` = `NAMESPACE`.`BASE_DOMAIN`
 - `ISTIO_DOMAIN` = istio.`DOMAIN`
 - `MASTER_PASSWORD` = `MASTER_PASSWORD_WEB_VAR` if that is not given `MASTER_PASSWORD` will be used, that could be set as masked CI variable in Gitlab or as a fallback the default value of `MASTER_PASSWORD`.
 
 You might want to set password / credential variables in the projects `Settings` > `CI/CD` > `Variables`.
 
-### Local
+## Local deployment
 
 Please ensure you have set the `Required input variables` (see section above) and have also read the `Helmfile` section below for non default configurations. Then go with
 
@@ -133,11 +135,11 @@ Off the shelf you get two accounts with passwords you can lookup in the `univent
 | default.user       | DEFAULT_ACCOUNT_USER_PASSWORD  |
 | default.admin      | DEFAULT_ACCOUNT_ADMIN_PASSWORD |
 
-## Helmfile
+# Helmfile
 
-### Custom Configuration
+## Custom Configuration
 
-#### Deployment selection
+### Deployment selection
 
 By default all components are deployed. The components of type `Eval` are used for development and evaluation
 purposes only and need to be replaced in production deployments. These components are grouped together in the
@@ -214,7 +216,7 @@ In case you don't got for a develop or evaluation environment you want to point
 |             |                    |            | Username  | `databases.xwiki.username`             | `xwiki_user`               |
 |             |                    |            | Password  | `databases.xwiki.password`             |                            |
 
-#### Scaling
+### Scaling
 
 Replicas for components can be increased, while we still have to look in the actual scalability of the
 components (see column `Scales at least to 2`).
@@ -238,7 +240,50 @@ components (see column `Scales at least to 2`).
 | Postfix     | `replicas.postfix`     | `1`     | :white_check_mark: | :x:                | not tested           |
 | XWiki       | `replicas.xwiki`       | `1`     | :white_check_mark: | :white_check_mark: | not tested           |
 
-## Identity data flows
+
+# Component integration
+
+## Functional use cases
+
+### Overview
+
+Some use cases require inter component integration.
+
+```mermaid
+flowchart TD
+  OXAppSuiteFrontend-->|SilentLogin, Filepicker, CentralNavigation|IntercomService
+  IntercomService-->|SilentLogin, TokenExchange|Keycloak
+  IntercomService-->|Filepicker|Nextcloud
+  IntercomService-->|CentralNavigation|Portal
+  OXAppSuiteBackend-->|Filepicker|Nextcloud
+  Nextcloud-->|CentralNavigation|Portal
+  OpenProject-->|CentralNavigation|Portal
+  XWiki-->|CentralNavigation|Portal
+  Nextcloud-->|CentralContacts|OXAppSuiteBackend
+  OXAppSuiteFrontend-->|Filepicker|OXAppSuiteBackend
+```
+
+#### Intercom Service (ICS)
+
+The UCS Intercom Service's role is to enable cross application integration based on browser interaction. Handling authentication when frontend of application A is using API from application B is often a challenge. For more details on the ICS please refer to it's separate [README.md](./helmfile/apps/intercom-service/README.md) - (**TODO**)
+
+In order to establish a session with the ICS the application makes use of the ICS must initiate a silent login.
+
+Currently only OX AppSuite is using the frontend based integration and therefore it's the only consumer of the ICS API endpoints.
+
+### Filepicker
+
+The Nextcloud filepicker is integrated into the OX AppSuite allows you for adding attachments or links to files from and saving attachments to Nextcloud. The filepicker is using frontend based integration (OX AppSuite in the browser talking to Intercom service) as well as backend to backend integration e.g. (OX AppSuite middleware talking to Nextcloud). The latter one especially when adding a file to an email or storing an file into Nextcloud.
+
+### Central Navigation
+
+The central navigation is based on an API endpoint in the portal that provides the contents of the portal for a user in order to allow components to render the menu showing all available SWP applications for the user.
+
+### (Read & write) Central contacts
+
+Open-Xchange App Suite is the place to manage contacts within the SWP. There is a standard API in the AppSuite that is being used by Nextcloud to lookup contacts as well as to create contacts e.g. if a file is shared with a not yet available personal contact.
+
+# Identity data flows
 
 An overview on
 - components that consume data from the ldap, in most cases using a dedicated ldap search account and
@@ -255,7 +300,6 @@ flowchart TD
     P[Portal/Admin]-->L
     O[OpenProject]-->|in 2023|L
     X[XWiki]-->|in 2023|L
-    F[Postfix]-->D
     A-->K
     N-->K
     D-->K
@@ -264,9 +308,44 @@ flowchart TD
     P-->|SAML|K
     E[Element]-->K
     J[Jitsi]-->K
+    I[IntercomService]-->K
     C[Collabora]-->N
+    F[Postfix]-->D
 ```
 
+# Provisioning
+
+Currently active provisioning is only done for OX AppSuite. The OX-Connector synchronizes create, modify and delete acitivities for the following objects to the OX AppSuite using the AppSuite's SOAP API:
+
+- Contexts
+- Users
+- Groups
+- Functional Mailboxes
+- Resources
+
+# Component specific documentation
+
+We want to provide more information per component in separate, component specific `README.md` files. In order to establish a common view on the components we are going to cover various aspects:
+
+- **Component overview**: Should provide a quick introduction with the components prerequisites and subcomponents (f.e. pods).
+- **Resources**: Will contain link to the components upstream documentation, the helm chart and image locations.
+- **Operational Capabilities**
+  - **Install**: The components installs 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 to upgrade 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 README.mds
+
+- [Intercom-Service](./helmfile/apps/intercom-service/README.md)
+
 # Footnotes
 
 [^1] Required for scaling components Nextcloud, Dovecot and ClamAV Distributed.

helmfile/apps/intercom-service/README.md

@@ -0,0 +1,43 @@
+<!--
+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.