diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 59cf9fe2..985a13f9 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -86,12 +86,6 @@ variables: options: - "yes" - "no" - DEPLOY_KEYCLOAK: - description: "Enable Keycloak deployment." - value: "no" - options: - - "yes" - - "no" DEPLOY_OX: description: "Enable OX AppSuite8 deployment." value: "no" @@ -255,31 +249,6 @@ ums-deploy: variables: COMPONENT: "univention-management-stack" -keycloak-deploy: - stage: "component-deploy-stage-1" - extends: ".deploy-common" - rules: - - if: > - $CI_PIPELINE_SOURCE =~ "web|schedules|triggers" && - $NAMESPACE =~ /.+/ && - ($DEPLOY_ALL_COMPONENTS != "no" || $DEPLOY_KEYCLOAK != "no") - when: "always" - variables: - COMPONENT: "keycloak" - -keycloak-bootstrap-deploy: - stage: "component-deploy-stage-1" - extends: ".deploy-common" - timeout: "30m" - rules: - - if: > - $CI_PIPELINE_SOURCE =~ "web|schedules|triggers" && - $NAMESPACE =~ /.+/ && - ($DEPLOY_ALL_COMPONENTS != "no" || $DEPLOY_KEYCLOAK != "no") - when: "always" - variables: - COMPONENT: "keycloak-bootstrap" - ox-deploy: stage: "component-deploy-stage-1" extends: ".deploy-common" @@ -461,7 +430,7 @@ run-tests: \"DEPLOY_ELEMENT\": \"${DEPLOY_ELEMENT}\", \ \"DEPLOY_ICS\": \"${DEPLOY_ICS}\", \ \"DEPLOY_JITSI\": \"${DEPLOY_JITSI}\", \ - \"DEPLOY_KEYCLOAK\": \"${DEPLOY_KEYCLOAK}\", \ + \"DEPLOY_KEYCLOAK\": \"${DEPLOY_UMS}\", \ \"DEPLOY_NEXTCLOUD\": \"${DEPLOY_NEXTCLOUD}\", \ \"DEPLOY_OPENPROJECT\": \"${DEPLOY_OPENPROJECT}\", \ \"DEPLOY_OX\": \"${DEPLOY_OX}\", \ diff --git a/COMPONENTS-SERVICE.md b/COMPONENTS-SERVICE.md index 7e686bf4..0221f86b 100644 --- a/COMPONENTS-SERVICE.md +++ b/COMPONENTS-SERVICE.md @@ -21,7 +21,9 @@ This services is used by: ## Database - PostgreSQL This services is used by: -- Keycloak +- Univention Management Stack + - Self Service + - Keycloak - OpenProject ## Redis @@ -33,11 +35,12 @@ This service is used by: ## Postfix This service is used by: -- Keycloak (e.g. new device login notification) - Nextcloud (e.g. share file notifictions) - Open-Xchange (emails) - OpenProject (general notifications) -- UMS (e.g. password reset emails) +- Univention Management Stack + - Self Service (e.g. password reset emails) + - Keycloak (e.g. new device login notification) - XWiki (e.g. change notifications) ## TURN Server diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9f742bd5..0b5aaa94 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -52,8 +52,6 @@ Valid commit scopes: - `collabora` - `ìntercom-service` - `jitsi` -- `keycloak` -- `keycloak-bootstrap` - `nextcloud` - `open-xchange` - `openproject` diff --git a/README.md b/README.md index 15b6c9ef..00ea5056 100644 --- a/README.md +++ b/README.md @@ -67,19 +67,19 @@ If you want to address other topics, please check the section # Requirements -⟶ Visit our detailed [Requirements](docs/requirements.md) overview. +⟶ Visit our detailed [Requirements](./docs/requirements.md) overview. # Getting started -⟶ Visit our detailed [Getting started](docs/getting-started.md) guide. +⟶ Visit our detailed [Getting started](./docs/getting-started.md) guide. # Advanced customization -- [External services](docs/external-services.md) -- [Security](docs/security.md) -- [Scaling](docs/scaling.md) -- [Monitoring](docs/monitoring.md) -- [Theming](docs/theming.md) +- [External services](./docs/external-services.md) +- [Security](./docs/security.md) +- [Scaling](./docs/scaling.md) +- [Monitoring](./docs/monitoring.md) +- [Theming](./docs/theming.md) # Releases @@ -95,7 +95,7 @@ The following release artefacts are provided beside the default source code asse # Components -⟶ Visit our detailed [Component](docs/getting-started.md) docs. +⟶ Visit our detailed [Component](./docs/components.md) docs. # License diff --git a/docs/ci.md b/docs/ci.md index eff7bda0..f89b5405 100644 --- a/docs/ci.md +++ b/docs/ci.md @@ -7,11 +7,11 @@ SPDX-License-Identifier: Apache-2.0 This page will cover openDesk automation via Gitlab CI. - * [Deployment](#deployment) - * [Tests](#tests) +* [Deployment](#deployment) +* [Tests](#tests) -## Deployment +# Deployment The project includes a `.gitlab-ci.yml` that allows you to execute the deployment from a Gitlab instance of your choice. @@ -30,8 +30,7 @@ Based on your input, the following variables will be set: You might want to set credential variables in the Gitlab project at `Settings` > `CI/CD` > `Variables`. - -## Tests +# Tests The gitlab-ci pipeline contains a job named `run-tests` that can trigger a test suite pipeline on another gitlab project. The `DEPLOY_`-variables are used to determine which components should be tested. diff --git a/docs/components.md b/docs/components.md index b18010c8..0d0cd438 100644 --- a/docs/components.md +++ b/docs/components.md @@ -7,20 +7,20 @@ SPDX-License-Identifier: Apache-2.0 This section covers the internal system requirements as well as external service requirements for productive use. - * [Overview](#overview) - * [Component integration](#component-integration) - * [Intercom Service (ICS)](#intercom-service-ics) - * [Filepicker](#filepicker) - * [Central Navigation](#central-navigation) - * [(Read & write) Central contacts](#read--write-central-contacts) - * [OpenProject Filestore](#openproject-filestore) - * [Identity data flows](#identity-data-flows) - * [Provisioning](#provisioning) - * [Component specific documentation](#component-specific-documentation) - * [Links to component docs](#links-to-component-docs) +* [Overview](#overview) +* [Component integration](#component-integration) + * [Intercom Service (ICS)](#intercom-service-ics) + * [Filepicker](#filepicker) + * [Central Navigation](#central-navigation) + * [(Read \& write) Central contacts](#read--write-central-contacts) + * [OpenProject Filestore](#openproject-filestore) +* [Identity data flows](#identity-data-flows) +* [Provisioning](#provisioning) +* [Component specific documentation](#component-specific-documentation) +* [Links to component docs](#links-to-component-docs) -## Overview +# Overview openDesk consists out of a variety of open-source projects. Here is a list with the description and type. @@ -38,7 +38,6 @@ they need to be replaced in production deployments. | Element | Secure communications platform | Functional | | Intercom Service | Cross service data exchange | Functional | | Jitsi | Videoconferencing | Functional | -| Keycloak | Identity Provider | Functional | | MariaDB | Database | Eval | | Memcached | Cache Database | Eval | | MinIO | Object Storage | Eval | @@ -49,18 +48,17 @@ they need to be replaced in production deployments. | Postfix | MTA | Eval | | PostgreSQL | Database | Eval | | Redis | Cache Database | Eval | -| Univention Corporate Server | Identity Management & Portal | Functional | -| Univention Management Stack | Identity Management & Portal | Eval | +| Univention Management Stack | Identity Management & Portal | Functional | | XWiki | Knowledgebase | Functional | -## Component integration +# Component integration Some use cases require inter component integration. ```mermaid flowchart TD OXAppSuiteFrontend-->|SilentLogin, Filepicker, CentralNavigation|IntercomService - IntercomService-->|SilentLogin, TokenExchange|Keycloak + IntercomService-->|SilentLogin, TokenExchange|IdP IntercomService-->|Filepicker|Nextcloud IntercomService-->|CentralNavigation|Portal OXAppSuiteBackend-->|Filepicker|Nextcloud @@ -71,7 +69,7 @@ flowchart TD OXAppSuiteFrontend-->|Filepicker|OXAppSuiteBackend ``` -### Intercom Service (ICS) +## Intercom Service (ICS) The UCS Intercom Service's role is to enable cross-application integration based on browser interaction. Handling authentication when the frontend of an application is using the API from another application is often a @@ -84,7 +82,7 @@ login. Currently only OX AppSuite is using the frontend-based integration, and therefore it is right now the only consumer of the ICS API. -### Filepicker +## Filepicker The Nextcloud filepicker which is integrated into the OX AppSuite allows you to add attachments or links to files from and saving attachments to Nextcloud. @@ -94,34 +92,33 @@ Frontend-based integration means that OX AppSuite in the browser is communicatin While using backend-based integration, OX AppSuite middleware is communicating with Nextcloud, which is especially used when adding a file to an email or storing a file into Nextcloud. -### Central Navigation +## Central Navigation Central navigation is based on an API endpoint in the portal that provides the contents of the portal for a user to allow components to render the menu showing all available SWP applications for the user. -### (Read & write) Central contacts +## (Read & write) Central contacts Open-Xchange App Suite is used to manage contacts within openDesk. There is an API in the AppSuite that is being used by 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. -### OpenProject Filestore +## OpenProject Filestore 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. - -## Identity data flows +# Identity data flows An overview of - components that consume the LDAP service. Mostly by using a dedicated LDAP search account. -- components using Keycloak as identity provider. If not otherwise denoted based on the OAuth2 / OIDC flows. +- components using Univention Keycloak as identity provider (IdP). If not otherwise denoted based on the OAuth2 / OIDC flows. Some components trust others to handle authentication for them. ```mermaid flowchart TD - K[Keycloak]-->L[LDAP] + K[IdP]-->L[LDAP] N[Nextcloud]-->L O[OpenProject] --> L A[OX AppSuite]-->L @@ -142,7 +139,7 @@ flowchart TD F[Postfix]-->D ``` -## Provisioning +# 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: @@ -153,7 +150,7 @@ deleting activities for the following objects to the OX AppSuite using the AppSu - Functional Mailboxes - Resources -## Component specific documentation +# 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: @@ -173,6 +170,6 @@ To establish a common view on the components, we are going to cover various aspe - **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 +# Links to component docs - [Intercom-Service](./components/intercom-service.md) diff --git a/docs/external-services.md b/docs/external-services.md index e05b146f..1a4a36ef 100644 --- a/docs/external-services.md +++ b/docs/external-services.md @@ -8,12 +8,12 @@ SPDX-License-Identifier: Apache-2.0 This document will cover the additional configuration to use external services like databases, caches or buckets. - * [Database](#database) - * [Objectstore](#objectstore) - * [Cache](#cache) +* [Database](#database) +* [Objectstore](#objectstore) +* [Cache](#cache) -## Database +# Database When deploying this suite to production, you need to configure the applications to use your production grade database service. @@ -72,7 +72,7 @@ service. | | | | Username | `databases.xwiki.username` | `xwiki_user` | | | | | Password | `databases.xwiki.password` | | -## Objectstore +# Objectstore When deploying this suite to production, you need to configure the applications to use your production grade objectstore service. @@ -89,7 +89,7 @@ service. | | | Username | `objectstores.openproject.username` | `openproject_user` | | | | Use IAM profile | `objectstores.openproject.useIAMProfile` | | -## Cache +# Cache When deploying this suite to production, you need to configure the applications to use your production grade cache service. diff --git a/docs/getting-started.md b/docs/getting-started.md index 9a674d64..b644bc79 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -8,38 +8,38 @@ SPDX-License-Identifier: Apache-2.0 This documentation should enable you to create your own evaluation instance of openDesk on your Kubernetes cluster. - * [Requirements](#requirements) - * [Customize environment](#customize-environment) - * [Domain](#domain) +* [Requirements](#requirements) +* [Customize environment](#customize-environment) + * [Domain](#domain) * [Apps](#apps) - * [Private Image registry](#private-image-registry) - * [Private Helm registry](#private-helm-registry) - * [Cluster capabilities](#cluster-capabilities) - * [Service](#service) - * [Networking](#networking) - * [Ingress](#ingress) - * [Container runtime](#container-runtime) - * [Volumes](#volumes) - * [Connectivity](#connectivity) - * [Mail/SMTP configuration](#mailsmtp-configuration) - * [TURN configuration](#turn-configuration) - * [Certificate issuer](#certificate-issuer) - * [Password seed](#password-seed) + * [Private Image registry](#private-image-registry) + * [Private Helm registry](#private-helm-registry) + * [Cluster capabilities](#cluster-capabilities) + * [Service](#service) + * [Networking](#networking) + * [Ingress](#ingress) + * [Container runtime](#container-runtime) + * [Volumes](#volumes) + * [Connectivity](#connectivity) + * [Mail/SMTP configuration](#mailsmtp-configuration) + * [TURN configuration](#turn-configuration) + * [Certificate issuer](#certificate-issuer) + * [Password seed](#password-seed) * [Install](#install) - * [Install single app](#install-single-app) - * [Install single release/chart](#install-single-releasechart) - * [Access deployment](#access-deployment) - * [Uninstall](#uninstall) + * [Install single app](#install-single-app) + * [Install single release/chart](#install-single-releasechart) +* [Access deployment](#access-deployment) +* [Uninstall](#uninstall) Thanks for looking into the openDesk Getting started guide. This documents covers essentials configuration steps to deploy openDesk onto your kubernetes infrastructure. -## Requirements +# Requirements Detailed system requirements are covered on [requirements](requirements.md) page. -## Customize environment +# 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 @@ -50,7 +50,7 @@ files. For the following guide, we will use `dev` as environment, where variables can be set in `helmfile/environments/dev/values.yaml`. -### Domain +## Domain The deployment is designed to deploy each app under a subdomains. 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. @@ -107,7 +107,6 @@ All available apps and their default value can be found in `helmfile/environment | Element | `element.enabled` | `true` | Secure communications platform | | Intercom Service | `intercom.enabled` | `true` | Cross service data exchange | | Jitsi | `jitsi.enabled` | `true` | Videoconferencing | -| Keycloak | `keycloak.enabled` | `true` | Identity Provider | | MariaDB | `mariadb.enabled` | `true` | Database | | Memcached | `memcached.enabled` | `true` | Cache Database | | MinIO | `minio.enabled` | `true` | Object Storage | @@ -128,7 +127,7 @@ jitsi: enabled: false ``` -### Private Image registry +## Private Image registry By default, all OCI artifacts are proxied via the project's image registry, which should get replaced soon by the OCI registries provided by Open CoDE. @@ -153,7 +152,7 @@ global: - "external-registry" ``` -### Private Helm registry +## Private Helm registry Some apps use OCI style registry and some use Helm chart museum style registries. In `helmfile/environments/default/charts.yaml` you can find all helm charts used and modify their registry, repository @@ -180,10 +179,9 @@ The following environment variables have to be exposed when using the example: | `OD_PRIVATE_HELM_REGISTRY_USERNAME` | Username | | `OD_PRIVATE_HELM_REGISTRY_PASSWORD` | Password | +## Cluster capabilities -### Cluster capabilities - -#### Service +### Service Some apps, like Jitsi or Dovecot, require HTTP and external TCP connections. These apps create a Kubernetes service object. @@ -196,7 +194,7 @@ cluster: type: "NodePort" ``` -#### Networking +### Networking If your cluster has not the default `cluster.local` domain configured, you need to provide the domain via: @@ -214,7 +212,7 @@ cluster: cidr: "127.0.0.0/8" ``` -#### Ingress +### Ingress By default, the `ingressClassName` is empty to choose your default ingress controller, you may want to customize it by setting: @@ -224,7 +222,7 @@ ingress: ingressClassName: "cilium" ``` -#### Container runtime +### Container runtime Some apps require specific configuration for container runtimes. You can set your container runtime like `cri-o`, `containerd` or `docker` by: @@ -235,7 +233,7 @@ cluster: engine: "containerd" ``` -#### Volumes +### Volumes When your cluster has a `ReadWriteMany` volume provisioner, you can benefit from distributed or scaling of apps. By default, only `ReadWriteOnce` is enabled. To enable `ReadWriteMany` you can set: @@ -255,9 +253,9 @@ persistence: RWO: "my-read-write-once-class" ``` -### Connectivity +## Connectivity -#### 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 the whole subdomain. @@ -269,7 +267,7 @@ smtp: password: "secret" ``` -#### TURN configuration +### TURN configuration Some components (Jitsi, Element) use for direct communication a TURN server. You can configure your own TURN server with these options: @@ -286,7 +284,7 @@ turn: port: "5349" ``` -#### Certificate issuer +### 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 @@ -313,7 +311,7 @@ certificate: wildcard: true ``` -### Password seed +## 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: @@ -337,7 +335,7 @@ helmfile apply -e dev -n [-l