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

fix(docs): Update and streamline README.md and migrations.md.

Browse Source
This commit is contained in:
Thorsten Roßner
2024-10-15 08:19:44 +02:00
parent bc0ca8b4c1
commit a86c0afdbb
3 changed files with 100 additions and 57 deletions
Download Patch File Download Diff File Expand all files Collapse all files

46
README.md
View File

@@ -8,16 +8,16 @@ SPDX-License-Identifier: Apache-2.0
<!-- TOC -->
* [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)
<!-- TOC -->
# 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.

109
docs/migrations.md
View File

@@ -3,20 +3,23 @@ SPDX-FileCopyrightText: 2024 Zentrum für Digitale Souveränität der Öffentlic
SPDX-License-Identifier: Apache-2.0
-->
<h1>Upgrade migrations</h1>
<h1>Updates & Upgrades</h1>
* [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:**<br>
> 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**<br>
> 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.<your_domain>`
#### 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**<br>
> 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:

2
helmfile/environments/default/global.generated.yaml
View File

@@ -3,5 +3,5 @@
---
global:
systemInformation:
releaseVersion: "v1.0.0"
releaseVersion: "v1.0.1"
...