Skip to main content
Version: 7.2

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.0.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 deployment is running on OpenCloud 6.x (rolling) or OpenCloud 4.0.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​

If your configuration and data are stored in directories on the host, create a copy of these directories.

Example:

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.

Update the opencloud-compose Checkout​

If you use the opencloud-compose repository, update your local copy of the repository.

cd /opencloud-compose
git pull

Skip this step if you run OpenCloud with plain Docker.

Stop OpenCloud​

Stop the currently running OpenCloud instance.

docker compose stop

Pull the OpenCloud 7.x.x Image​

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.

docker pull opencloudeu/opencloud:7.x.x

Apply the Configuration Migration​

OpenCloud 7.x.x includes a breaking configuration change that must be applied before starting the upgraded instance.

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.

docker run --rm -it --entrypoint /bin/sh -v "<opencloud-config-volume>:/etc/opencloud" opencloudeu/opencloud:7.x.x

Replace <opencloud-config-volume> with the Docker volume or bind mount that contains your OpenCloud configuration.

Generate the Configuration Diff​

Inside the temporary container, run:

opencloud init --diff

Example output:

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:

/etc/opencloud/opencloud.config.patch

Apply the Configuration Patch​

Change to the configuration directory:

cd /etc/opencloud

Verify that the patch file was created:

ls

Example output:

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:

patch --dry-run opencloud.yaml < opencloud.config.patch

Expected output:

checking file opencloud.yaml

Apply the patch:

patch opencloud.yaml < opencloud.config.patch

Expected output:

patching file opencloud.yaml

Verify that the following configuration entries exist in opencloud.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.

exit

Start OpenCloud​

Start OpenCloud with the upgraded image.

docker compose up -d --remove-orphans

--remove-orphans removes containers for services that are no longer defined in the current Compose configuration. This helps clean up obsolete containers after upgrades where services have been removed or integrated into another service.

⏳ First Startup After Upgrading to OpenCloud 7.x.x​

After upgrading to OpenCloud 7.x.x, the first startup may take several minutes before all Spaces become fully available.

During this period, some Space-related functionality is temporarily restricted:

  • Space member lists may be incomplete or incorrect.
  • Space memberships cannot be modified.
  • Creating or deleting Spaces is not possible.
  • Share-related operations may be unavailable until the migration has completed.

Background​

OpenCloud 7.x.x introduced a new backend mechanism for managing Space memberships. When upgrading from an earlier release, the sharing service automatically migrates existing memberships to the new format.

Depending on the number of Spaces and members in your installation, this process may take several minutes to complete.

Monitoring Migration Progress​

To monitor the migration progress, configure the sharing service log level to info before starting the upgrade:

OC_LOG_LEVEL=info

or

SHARING_LOG_LEVEL=info

With the log level set to info, the sharing service writes migration progress information to the logs while the migration is running.

Migration Completed​

Once the migration has finished successfully, the sharing service writes a completion message to the logs indicating that the migration has been completed.

Note: Migration progress and completion messages are only available when the sharing service log level is configured to info.

After the completion message appears in the logs, all Space functionality, including member management, sharing operations, and Space creation or deletion, is available again.

Required Configuration Changes​

The upgrade also requires a configuration change for the sharing service.

Please follow the instructions in the Upgrade Guide and apply the required configuration updates before starting the upgraded version of 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

After upgrading, rebuild the search index.

docker exec -it 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:

Download the latest extension versions and follow the web applications installation guide.

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​