From 87743632498d6b93588e7ca5421af25c74a0a3ad Mon Sep 17 00:00:00 2001 From: Heiko Pohl Date: Mon, 15 Jun 2026 12:27:37 +0200 Subject: [PATCH 1/3] improvement standard upgrade guide --- docs/admin/maintenance/upgrade/upgrade.md | 182 ++++++++++++++++++++-- package.json | 2 +- pnpm-workspace.yaml | 3 + 3 files changed, 177 insertions(+), 10 deletions(-) create mode 100644 pnpm-workspace.yaml diff --git a/docs/admin/maintenance/upgrade/upgrade.md b/docs/admin/maintenance/upgrade/upgrade.md index 88cf3741..ae92878b 100644 --- a/docs/admin/maintenance/upgrade/upgrade.md +++ b/docs/admin/maintenance/upgrade/upgrade.md @@ -31,21 +31,72 @@ Stop the currently running OpenCloud instance: -## Backup Config and Data +## Back Up Configuration and Data -It is recommended to create a [backup](../backup) before proceeding with the upgrade. + + -## Pull the latest OpenCloud Compose +If your configuration and data are stored in directories on the host, create a copy of these directories. -If you are using Docker Compose with the `opencloud-compose` repository, update your local checkout before pulling the new container image. +Example: -Skip this step if you run OpenCloud with plain Docker (`docker run`): +```bash +cp -a /mnt/opencloud/config /mnt/opencloud/config-backup +cp -a /mnt/opencloud/data /mnt/opencloud/data-backup +``` + +Replace the paths with the directories used by your deployment. + + + + + +Create a backup directory and copy the configuration and data from the OpenCloud container. + +```bash +mkdir -p ~/opencloud-backups +docker cp opencloud-compose-opencloud-1:/etc/opencloud ~/opencloud-backups/config-backup +docker cp opencloud-compose-opencloud-1:/var/lib/opencloud ~/opencloud-backups/data-backup +``` + +Replace `opencloud-compose-opencloud-1` with the name of your OpenCloud container if it differs. + + + + +## Update the `opencloud-compose` Checkout + +If you use the `opencloud-compose` repository, update your local copy of the repository. ```bash cd /opencloud-compose git pull ``` +Skip this step if you run OpenCloud with plain Docker. + +## Stop OpenCloud + +Stop the currently running OpenCloud instance. + + + + +```bash +docker compose stop +``` + + + + + +```bash +docker stop opencloud +``` + + + + ## Pull the new Opencloud version ```bash @@ -56,21 +107,134 @@ docker pull opencloudeu/opencloud-rolling:{tag} # or opencloudeu/opencloud:{tag} If upgrading from an older release, check for required configuration changes: -Go inside the container: +### Open a Temporary OpenCloud Container + +Open a shell in a temporary OpenCloud container and mount your OpenCloud configuration directory or configuration volume to `/etc/opencloud`. + + + ```bash -docker run --rm -it --entrypoint /bin/sh -v /YOUR/OC_CONFIG/PATH:/etc/opencloud opencloudeu/opencloud-rolling:{tag} -# or opencloudeu/opencloud:{tag} depending on the version you're using +docker run --rm -it --entrypoint /bin/sh -v ":/etc/opencloud" opencloudeu/opencloud (or opencloud-rolling):"version-tag" ``` +Replace `` with the Docker volume or bind mount that contains your OpenCloud configuration. + + + + + ```bash -opencloud init --diff +docker run --rm -it --entrypoint /bin/sh -v ":/etc/opencloud" opencloudeu/opencloud (or opencloud-rolling):"version-tag" ``` +Replace `` with the host directory that contains your `opencloud.yaml`. + + + + If you see `no changes, your config is up to date`, no further action is needed. Otherwise, update your `opencloud.yaml` file accordingly and start OpenCloud. init -diff +### Generate the Configuration Diff + +Inside the temporary container, run: + +```bash +opencloud init --diff +``` + +Example output: + +```diff +diff -u /etc/opencloud/opencloud.yaml /etc/opencloud/opencloud.yaml.tmp +--- /etc/opencloud/opencloud.yaml ++++ /etc/opencloud/opencloud.yaml.tmp +@@ -90,6 +90,9 @@ + sharing: + events: + tls_insecure: false ++service_account: ++ service_account_id: 00000000-0000-0000-0000-000000000000 ++ service_account_secret: example-service-account-secret + storage_users: + events: + tls_insecure: false + +diff written to /etc/opencloud/opencloud.config.patch +``` + +The command creates the following patch file: + +```bash +/etc/opencloud/opencloud.config.patch +``` + +### Apply the Configuration Patch + +Change to the configuration directory: + +```bash +cd /etc/opencloud +``` + +Verify that the patch file was created: + +```bash +ls +``` + +Example output: + +```bash +banned-password-list.txt +csp.yaml +opencloud.config.patch +opencloud.yaml +opencloud.yaml.2026-05-19-15-45-44.backup +``` + +Test the patch before applying it: + +```bash +patch --dry-run opencloud.yaml < opencloud.config.patch +``` + +Expected output: + +```bash +checking file opencloud.yaml +``` + +Apply the patch: + +```bash +patch opencloud.yaml < opencloud.config.patch +``` + +Expected output: + +```bash +patching file opencloud.yaml +``` + +Verify that the following configuration entries exist in `opencloud.yaml`: + +```yaml +service_account: + service_account_id: 00000000-0000-0000-0000-000000000000 + service_account_secret: example-service-account-secret +``` + +### Exit the Temporary Container + +Exit the temporary container after applying the configuration patch. + +```bash +exit +``` + ## Start OpenCloud with updated image diff --git a/package.json b/package.json index 5043f019..7abdc161 100644 --- a/package.json +++ b/package.json @@ -59,5 +59,5 @@ "engines": { "node": ">=18.0" }, - "packageManager": "pnpm@9.15.4+sha512.b2dc20e2fc72b3e18848459b37359a32064663e5627a51e4c74b2c29dd8e8e0491483c3abb40789cfd578bf362fb6ba8261b05f0387d76792ed6e23ea3b1b6a0" + "packageManager": "pnpm@11.6.0" } diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml new file mode 100644 index 00000000..0b489198 --- /dev/null +++ b/pnpm-workspace.yaml @@ -0,0 +1,3 @@ +allowBuilds: + core-js: true + esbuild: true From 297cfcae34a06e7c652b990523831c7939fe544b Mon Sep 17 00:00:00 2001 From: Anja Barz Date: Mon, 15 Jun 2026 12:53:03 +0200 Subject: [PATCH 2/3] some improvements for better understanding --- docs/admin/maintenance/upgrade/upgrade.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/docs/admin/maintenance/upgrade/upgrade.md b/docs/admin/maintenance/upgrade/upgrade.md index ae92878b..e9cd3e1a 100644 --- a/docs/admin/maintenance/upgrade/upgrade.md +++ b/docs/admin/maintenance/upgrade/upgrade.md @@ -133,10 +133,6 @@ Replace `` with the host directory that contains -If you see `no changes, your config is up to date`, no further action is needed. Otherwise, update your `opencloud.yaml` file accordingly and start OpenCloud. - -init -diff - ### Generate the Configuration Diff Inside the temporary container, run: @@ -145,6 +141,14 @@ Inside the temporary container, run: opencloud init --diff ``` +If you see `no changes, your config is up to date`, no further action is needed. + +init -diff + +In that case, [exit the temporary container](#exit-the-temporary-container) and start OpenCloud. + +Otherwise, update your `opencloud.yaml` file accordingly and [apply the patch](#apply-the-configuration-patch). + Example output: ```diff From 8e33b5fdd8b4bc64ffe6e2d3d600846ff7b7ecc7 Mon Sep 17 00:00:00 2001 From: Anja Barz Date: Mon, 15 Jun 2026 13:00:55 +0200 Subject: [PATCH 3/3] add info about tags in standard upgrade guide and 7.x.x --- docs/admin/maintenance/upgrade/upgrade-7.x.x.md | 4 ++-- docs/admin/maintenance/upgrade/upgrade.md | 11 +++++++++-- 2 files changed, 11 insertions(+), 4 deletions(-) diff --git a/docs/admin/maintenance/upgrade/upgrade-7.x.x.md b/docs/admin/maintenance/upgrade/upgrade-7.x.x.md index 41bd2f6b..0e43df85 100644 --- a/docs/admin/maintenance/upgrade/upgrade-7.x.x.md +++ b/docs/admin/maintenance/upgrade/upgrade-7.x.x.md @@ -98,12 +98,12 @@ docker stop opencloud Pull the OpenCloud 7.x.x image. +Replace `7.x.x` with the exact image tag for the version you want to install. Available tags are listed on [Docker Hub](https://hub.docker.com/u/opencloudeu). + ```bash docker pull opencloudeu/opencloud:7.x.x ``` -Replace `7.x.x` with the exact OpenCloud version you want to upgrade to. - ## Apply the Configuration Migration OpenCloud 7.x.x includes a breaking configuration change that must be applied before starting the upgraded instance. diff --git a/docs/admin/maintenance/upgrade/upgrade.md b/docs/admin/maintenance/upgrade/upgrade.md index e9cd3e1a..342481e6 100644 --- a/docs/admin/maintenance/upgrade/upgrade.md +++ b/docs/admin/maintenance/upgrade/upgrade.md @@ -97,10 +97,17 @@ docker stop opencloud -## Pull the new Opencloud version +## Pull the new OpenCloud image + +Pull the image that matches the release channel you use: + +- `opencloudeu/opencloud-rolling:{tag}` for rolling releases +- `opencloudeu/opencloud:{tag}` for stable releases + +Replace `{tag}` with the image tag for the version you want to install. Available tags are listed on [Docker Hub](https://hub.docker.com/u/opencloudeu). ```bash -docker pull opencloudeu/opencloud-rolling:{tag} # or opencloudeu/opencloud:{tag} depending on the version you're using +docker pull opencloudeu/opencloud-rolling:{tag} ``` ## Verify Configuration Changes