diff --git a/README.md b/README.md index 4b465374..bac81da9 100644 --- a/README.md +++ b/README.md @@ -8,16 +8,16 @@ SPDX-License-Identifier: Apache-2.0 * [Overview](#overview) +* [Upgrades](#upgrades) * [Requirements](#requirements) * [Getting started](#getting-started) * [Advanced customization](#advanced-customization) -* [Development](#development) -* [Releases](#releases) * [Components](#components) +* [Releases](#releases) * [Feedback](#feedback) +* [Development](#development) * [License](#license) * [Copyright](#copyright) -* [Footnotes](#footnotes) # Overview @@ -31,8 +31,8 @@ openDesk currently features the following functional main components: | -------------------- | --------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | Chat & collaboration | Element ft. Nordeck widgets | [1.11.67](https://github.com/element-hq/element-desktop/releases/tag/v1.11.67) | [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/) | -| File management | Nextcloud | [29.0.7](https://nextcloud.com/de/changelog/#29-0-7) | [SNextcloud 29](https://docs.nextcloud.com/) | -| Groupware | OX App Suite | [8.28](https://documentation.open-xchange.com/appsuite/releases/8.28/) | Online documentation available from within the installed application; [Additional resources](https://documentation.open-xchange.com/ | +| File management | Nextcloud | [29.0.7](https://nextcloud.com/de/changelog/#29-0-7) | [Nextcloud 29](https://docs.nextcloud.com/) | +| Groupware | OX App Suite | [8.28](https://documentation.open-xchange.com/appsuite/releases/8.28/) | Online documentation available from within the installed application; [Additional resources](https://documentation.open-xchange.com/) | | Knowledge management | XWiki | [16.4.4](https://www.xwiki.org/xwiki/bin/view/ReleaseNotes/Data/XWiki/16.4.4/) | [For the most recent release](https://www.xwiki.org/xwiki/bin/view/Documentation) | | Portal & IAM | Nubus | [1.0](https://www.univention.de/produkte/nubus/) | [Univention's documentation website](https://docs.software-univention.de/n/en/nubus.html) | | Project management | OpenProject | [14.6.1](https://www.openproject.org/docs/release-notes/14-6-1/) | [For the most recent release](https://www.openproject.org/docs/user-guide/) | @@ -46,13 +46,23 @@ This documentation aims to give you all that is needed to set up your own instan Basic knowledge of Kubernetes and DevOps processes is required though. +# Upgrades + +You want to upgrade an existing openDesk installation? + +⟶ Visit our detailed documentation about [Updates & Upgrades](./docs/migrations.md). + # Requirements -⟶ Visit our detailed [Requirements](./docs/requirements.md) overview. +You want to understand what is required to install openDesk yourself? + +⟶ Visit our [Requirements](./docs/requirements.md) overview. # Getting started -⟶ Visit our detailed [Getting started](./docs/getting-started.md) guide. +You would like to install openDesk in your own infrastructure? + +⟶ Visit our detailed [Getting started guide](./docs/getting-started.md). # Advanced customization @@ -63,9 +73,9 @@ Basic knowledge of Kubernetes and DevOps processes is required though. - [Monitoring](./docs/monitoring.md) - [Theming](./docs/theming.md) -# Development +# Components -⟶ To understand the repository contents from a developer perspective please read the [Development](./docs/development.md) guide. +More information on openDesk's components and their integration can be found in our detailed [Component docs](./docs/components.md). # Releases @@ -80,11 +90,7 @@ in the files from the release's git-tag: - `./helmfile/environments/default/images.yaml` - `./helmfile/environments/default/charts.yaml` -⟶ Visit our detailed [Workflow](./docs/workflow.md) docs. - -# Components - -⟶ Visit our detailed [Component](./docs/components.md) docs. +Find more information in our [Workflow documentation](./docs/workflow.md). # Feedback @@ -96,6 +102,10 @@ please use the [issues within this project](https://gitlab.opencode.de/bmi/opend If you want to address other topics, please check the section ["Rückmeldungen und Beteiligung" in the OVERVIEW.md](https://gitlab.opencode.de/bmi/opendesk/info/-/blob/main/OVERVIEW.md#rückmeldungen-und-beteiligung) of the [openDesk Info Repository](https://gitlab.opencode.de/bmi/opendesk/info). +# Development + +If you want to join or contribute to the development of openDesk please read the [Development guide](./docs/development.md). + # License This project uses the following license: Apache-2.0 @@ -103,11 +113,3 @@ This project uses the following license: Apache-2.0 # Copyright Copyright (C) 2024 Zentrum für Digitale Souveränität der Öffentlichen Verwaltung (ZenDiS) GmbH - -# Footnotes - -[^1]: Nubus is the Cloud Portal and IAM from Univention. -It is currently integrated as a product preview within openDesk therefore, not all resources like documentation -and structured release notes are available, while the -[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. diff --git a/docs/migrations.md b/docs/migrations.md index e724dead..6c31400d 100644 --- a/docs/migrations.md +++ b/docs/migrations.md @@ -3,20 +3,23 @@ SPDX-FileCopyrightText: 2024 Zentrum für Digitale Souveränität der Öffentlic SPDX-License-Identifier: Apache-2.0 --> -

Upgrade migrations

+

Updates & Upgrades

* [Disclaimer](#disclaimer) -* [Releases upgrades](#releases-upgrades) +* [openDesk supported upgrade path](#opendesk-supported-upgrade-path) +* [Releases upgrade details](#releases-upgrade-details) * [From v0.9.0](#from-v090) - * [Changed openDesk defaults](#changed-opendesk-defaults) - * [Removal of unnecessary OX-Profiles in Nubus](#removal-of-unnecessary-ox-profiles-in-nubus) - * [Matrix ID localpart update](#matrix-id-localpart-update) - * [File-share configurability](#file-share-configurability) - * [Updated default subdomains in `global.hosts`](#updated-default-subdomains-in-globalhosts) - * [Updated `global.imagePullSecrets`](#updated-globalimagepullsecrets) - * [Dedicated group for access to the UDM REST API](#dedicated-group-for-access-to-the-udm-rest-api) + * [Pre-upgrade: Manual steps](#pre-upgrade-manual-steps) + * [Configuration Cleanup: Removal of unnecessary OX-Profiles in Nubus](#configuration-cleanup-removal-of-unnecessary-ox-profiles-in-nubus) + * [Configuration Cleanup: Updated `global.imagePullSecrets`](#configuration-cleanup-updated-globalimagepullsecrets) + * [Changed openDesk defaults: Matrix ID](#changed-opendesk-defaults-matrix-id) + * [Changed openDesk defaults: File-share configurability](#changed-opendesk-defaults-file-share-configurability) + * [Changed openDesk defaults: Updated default subdomains in `global.hosts`](#changed-opendesk-defaults-updated-default-subdomains-in-globalhosts) + * [Changed openDesk defaults: Dedicated group for access to the UDM REST API](#changed-opendesk-defaults-dedicated-group-for-access-to-the-udm-rest-api) * [Automated migrations](#automated-migrations) - * [Manual cleanup](#manual-cleanup) + * [Post-upgrade: Manual steps](#post-upgrade-manual-steps) + * [Configuration Improvement: Separate user permission for using Video Conference component](#configuration-improvement-separate-user-permission-for-using-video-conference-component) + * [Optional Cleanup](#optional-cleanup) * [From v0.8.1](#from-v081) * [Updated `cluster.networking.cidr`](#updated-clusternetworkingcidr) * [Updated customizable template attributes](#updated-customizable-template-attributes) @@ -26,20 +29,39 @@ SPDX-License-Identifier: Apache-2.0 # Disclaimer -With openDesk 1.0, we aim to offer hassle-free updates. Though some situations may require manual interaction, these are described in this document. +With openDesk 1.0, we aim to offer hassle-free updates/upgrades. + +But openDesk requires a defined upgrade path that is described in the section [openDesk supported upgrade path](#opendesk-supported-upgrade-path). + +Some upgrades even require manual interaction, which are referenced in the aforementioned section and described further down this document. > **Known limitations:**
> We assume that the PV reclaim policy is set to `delete`, resulting in PVs getting deleted as soon as the related PVC was deleted; we will not address explicit deletion for PVs. -# Releases upgrades +# openDesk supported upgrade path + +When updating your openDesk installation you have to install the releases listed below in the sequential order from +the lowest version number you are already on to the more current version you are looking to install. + +Explanation of the table's columns: +- *Coming from*: Check the column for the release you are currently on. +- *Mandatory release*: Defines which release(s) support the upgrade from your currently installed version. +- *Automatic migration*: Summary of, or link to openDesk's automatic migration details. +- *Manual activities*: Reference to required manual steps to upgrade your openDesk installation to the *Mandatory release*. + +| Coming from | Mandatory (minimum) release | Automatic migration | Manual activities | +| ------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | +| v0.9.0 | v1.x.x | [run_2.py](https://gitlab.opencode.de/bmi/opendesk/components/platform-development/images/opendesk-migrations/-/blob/main/odmigs-python/odmigs_runs/run_2.py) | See [From v0.9.0](#from-v090) | +| v0.8.1 | v0.9.0 | Initializes migration system | See [From v0.8.1](#from-v081) | +| not supported | v0.8.1 | First release that supporting updates | | + +# Releases upgrade details ## From v0.9.0 -Before openDesk 1.0, we faced significant changes in some components and the overall platform configuration. Therefore, please review the +### Pre-upgrade: Manual steps -### Changed openDesk defaults - -#### Removal of unnecessary OX-Profiles in Nubus +#### Configuration Cleanup: Removal of unnecessary OX-Profiles in Nubus > **Warning**
> The upgrade will fail if you do not address this section for your current deployment. @@ -66,7 +88,20 @@ You can review and update other accounts as follows: - "Login disabled" if the user should not use the Groupware module. - Update the user account with the green "SAVE" button at the top of the page. -#### Matrix ID localpart update +#### Configuration Cleanup: Updated `global.imagePullSecrets` + +Without using a custom registry, you can pull all the openDesk images without authentication. +Thus defining not existing imagePullSecrets creates unnecessary errors, so we removed them. + +You can keep the current settings by setting the `external-registry` in your custom environment values: + +```yaml +global: + imagePullSecrets: + - "external-registry" +``` + +#### Changed openDesk defaults: Matrix ID Until 0.9.0 openDesk used the LDAP entryUUID of a user to generate the user's Matrix ID. Due to restrictions on the Matrix protocol, an update of a Matrix ID is not possible; therefore, it was technically convenient to use the UUID @@ -99,7 +134,7 @@ functional: useImmutableIdentifierForLocalpart: true ``` -#### File-share configurability +#### Changed openDesk defaults: File-share configurability Now, we provide some configurability regarding the sharing capabilities of the Nextcloud component. @@ -118,7 +153,7 @@ functional: activeByDefault: false ``` -#### Updated default subdomains in `global.hosts` +#### Changed openDesk defaults: Updated default subdomains in `global.hosts` We have streamlined the subdomain names in openDesk to be more user-friendly and to avoid the use of specific product names. @@ -174,20 +209,7 @@ In case you would like to update an existing deployment to the new hostnames, pl - In Nextcloud: *Administration* > *OpenProject* > *OpenProject server* - Update the *OpenProject host* to `projects.` -#### Updated `global.imagePullSecrets` - -Without using a custom registry, you can pull all the openDesk images without authentication. -Thus defining not existing imagePullSecrets creates unnecessary errors, so we removed them. - -You can keep the current settings by setting the `external-registry` in your custom environment values: - -```yaml -global: - imagePullSecrets: - - "external-registry" -``` - -#### Dedicated group for access to the UDM REST API +#### Changed openDesk defaults: Dedicated group for access to the UDM REST API Prerequisite: You allow the use of the [IAM's API](https://docs.software-univention.de/developer-reference/5.0/en/udm/rest-api.html) with the following settings: @@ -216,7 +238,26 @@ The permissions required to execute the migrations can be found in the migration The actual actions are described as code comments in the related run module [`run_2.py](https://gitlab.opencode.de/bmi/opendesk/components/platform-development/images/opendesk-migrations/-/blob/main/odmigs-python/odmigs_runs/run_2.py). -#### Manual cleanup +### Post-upgrade: Manual steps + +#### Configuration Improvement: Separate user permission for using Video Conference component + +With openDesk 1.0 the user permission for authenticated access to the Chat and Video Conference components was split into two separate permissions. + +Therefore the newly added *Video Conference* permission has to be added to users that should have continued access to the component. + +This can be done as IAM admin: +- Open the *user* module. +- Select all users that should get the permission for *Video Conference* using the select box left from the users entry. +- In top bar of the user table click on *Edit*. +- Select the *openDesk* section the the left-hand menu. +- Check the check box for *Video Conference* and the directly below check box for *Overwrite*. +- Click on the green *Save* button on top of the screen to apply the change. + +> **Hint**
+> If you have a lot of users andd want to update (almost) all them, you can select all users by clicking the check box in the user's table header and then de-selecting the users you do not want to update. + +#### Optional Cleanup 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 a successful upgrade: diff --git a/helmfile/environments/default/global.generated.yaml b/helmfile/environments/default/global.generated.yaml index 4958ee66..8c4464f0 100644 --- a/helmfile/environments/default/global.generated.yaml +++ b/helmfile/environments/default/global.generated.yaml @@ -3,5 +3,5 @@ --- global: systemInformation: - releaseVersion: "v1.0.0" + releaseVersion: "v1.0.1" ...