diff --git a/docs/admin/maintenance/upgrade/index.md b/docs/admin/maintenance/upgrade/index.md index 81b170b7..b49c20da 100644 --- a/docs/admin/maintenance/upgrade/index.md +++ b/docs/admin/maintenance/upgrade/index.md @@ -13,5 +13,6 @@ This section collects the guides you need when upgrading OpenCloud. ## Guides - [Standard Upgrade Guide](./upgrade.md) +- [Upgrade 7.x.x](./upgrade-7.x.x.md) - [Upgrade 4.0.x](./upgrade-4.0.0.md) - [Release notes](./release-notes.md) diff --git a/docs/admin/maintenance/upgrade/release-notes.md b/docs/admin/maintenance/upgrade/release-notes.md index d9fedda9..3eff738f 100644 --- a/docs/admin/maintenance/upgrade/release-notes.md +++ b/docs/admin/maintenance/upgrade/release-notes.md @@ -1,5 +1,5 @@ --- -sidebar_position: 3 +sidebar_position: 4 id: release-notes title: Release Notes description: Release Notes diff --git a/docs/admin/maintenance/upgrade/upgrade-7.x.x.md b/docs/admin/maintenance/upgrade/upgrade-7.x.x.md new file mode 100644 index 00000000..0dbff89c --- /dev/null +++ b/docs/admin/maintenance/upgrade/upgrade-7.x.x.md @@ -0,0 +1,338 @@ +--- +sidebar_position: 4 +id: upgrade-7.x.x +title: Upgrade 7.x.x +description: Upgrading to OpenCloud 7.x.x +draft: false +--- + +import Tabs from '@theme/Tabs' +import TabItem from '@theme/TabItem' + +# Upgrading to OpenCloud 7.x.x + +This guide describes how to upgrade an existing OpenCloud deployment to OpenCloud 7.x.x. + +The guide applies to upgrades from: + +- OpenCloud 6.x rolling +- OpenCloud 4.x stable + +It covers the required configuration migration, optional OpenSearch index rebuild, and web extension updates introduced with OpenCloud 7.x.x. + +## Before You Start + +- Make sure your current OpenCloud deployment runs OpenCloud 6.x rolling or OpenCloud 4.x stable. +- Create a complete backup of your configuration and data. +- Make sure you have access to your current `opencloud.yaml`. +- Verify that your current deployment is healthy before upgrading. +- Review the OpenCloud 7.x.x release notes before starting the upgrade. + +## Back Up Configuration and Data + +:::important + +Always create a backup before upgrading to prevent data loss. + +::: + + + + +If your configuration and data are stored in host directories, create a copy of these directories. + +Example: + +```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 checkout before pulling the new container image. + +```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 OpenCloud 7.x.x Image + +Pull the OpenCloud 7.x.x image. + +```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. + +Reference: [Migration PR](https://github.com/opencloud-eu/opencloud/pull/2760) + +### Open a Temporary OpenCloud Container + +Open a shell in a temporary OpenCloud 7.x.x container and mount your OpenCloud configuration directory or configuration volume to `/etc/opencloud`. + + + + +```bash +docker run --rm -it --entrypoint /bin/sh -v ":/etc/opencloud" opencloudeu/opencloud:7.x.x +``` + +Replace `` with the Docker volume that contains your OpenCloud configuration. + + + + + +```bash +docker run --rm -it --entrypoint /bin/sh -v ":/etc/opencloud" opencloudeu/opencloud:7.x.x +``` + +Replace `` with the host directory that contains your `opencloud.yaml`. + + + + +### 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 + +Start OpenCloud with the upgraded image. + + + + +```bash +docker compose up -d +``` + + + + + +```bash +docker start opencloud +``` + + + + +## Rebuild the OpenSearch Index + +:::note + +This step is only required for instances that use OpenSearch. + +::: + +OpenCloud 7.x.x introduces a new OpenSearch index structure. + +Reference: [OpenSearch Index PR](https://github.com/opencloud-eu/opencloud/pull/2514) + +After upgrading, rebuild the search index. + + + + +```bash +docker exec -it opencloud opencloud search index --all-spaces +``` + + + + + +```bash +docker compose exec opencloud opencloud search index --all-spaces +``` + + + + +The indexing process can take longer on larger installations. + +## Update Web Extensions + +OpenCloud 7.x.x introduces breaking changes in the web client architecture. + +Older web extension versions are no longer compatible with OpenCloud 7.x.x and must be updated. + +New extension versions are available from: + +- The App Store inside the OpenCloud web interface +- [OpenCloud Web Extensions on GitHub](https://github.com/opencloud-eu/web-extensions/releases) + +Download the latest extension versions and follow the [web applications installation guide](../../configuration/web-applications.md). + +## Verify the Upgrade + +After starting OpenCloud, verify that the instance works as expected. + +- Users can log in. +- Existing shares are still available. +- Public links work as expected. +- Project spaces show the correct members and permissions. +- Search returns expected results after rebuilding the OpenSearch index. +- The container logs do not show upgrade-related errors. + +## Troubleshooting + +If issues occur during or after the upgrade: + +- Review the OpenCloud container logs. +- Verify the generated changes in `opencloud.yaml`. +- Re-run the configuration diff if required. +- Restore the backup if the instance cannot be recovered. +- Check the troubleshooting documentation. +- Open an issue on GitHub if the issue persists. + +## Useful Resources + +- [OpenCloud Troubleshooting Guide](../../resources/common-issues.md) +- [OpenCloud GitHub Issues](https://github.com/opencloud-eu/opencloud/issues) +- [OpenCloud Web Extensions Releases](https://github.com/opencloud-eu/web-extensions/releases)