Zum Hauptinhalt springen
Version: 9.1

Upgrading to OpenCloud 9.1.x

OpenCloud 9.1.x is the new Production release. This guide describes the direct upgrade from the previous Production release 7.2.x to 9.1.x.

An interim upgrade to the Rolling release 8.x.x is not required. This guide includes all changes from 8.x.x and 9.x.x that are relevant for the upgrade.

Upgrade Paths​

Current versionUpgrade path
7.2.xUpgrade directly to 9.1.x with this guide.
4.xUpgrade to 7.2.x first as described in Upgrade 7.2.x. Then upgrade to 9.1.x with this guide.
important

A direct upgrade from 4.x to 9.1.x is not supported. Upgrade to 7.2.x first and verify that the deployment works before you continue with 9.1.x.

Use this guide together with the Standard Upgrade Guide, which describes the general upgrade procedure. For more information about the release channels, see the Release Lifecycle.

hinweis

If you run the Rolling release 8.x.x, follow the Upgrade 9.x.x guide instead.

Before You Start​

  • Make sure that your deployment runs OpenCloud 7.2.x. If you run 4.x, see Upgrade Paths. Check the version that is currently running:

    docker compose images opencloud
  • Create a complete backup of your configuration and data, see Back Up Configuration and Data.

  • Review the OpenCloud release notes.

  • Read the breaking changes if you use custom settings in opencloud.yaml, custom thumbnail settings, custom email templates, web extensions, or an external reverse proxy.

Step 1: Update the opencloud-compose Checkout​

If you use the opencloud-compose repository, fetch the latest changes and switch from the previous Production branch to the new one:

cd /opencloud-compose
git fetch origin
git switch stable-9.1
git pull --ff-only

Running git pull while you are still on stable-7.2 only updates that branch and does not switch the checkout to the 9.1 release. Skip this step if you run OpenCloud with plain Docker.

Step 2: Verify the New Version​

After updating the opencloud-compose checkout, check which OpenCloud image Docker Compose resolves:

docker compose config --images | grep '^opencloudeu/opencloud'

If the output already shows the Production image with the intended 9.1.x release tag, no change to your .env file is required.

If the output still shows the previous version or the Rolling image, set the Production image and the exact new version in your .env file:

OC_DOCKER_IMAGE=opencloudeu/opencloud
OC_DOCKER_TAG=9.1.x

Replace 9.1.x with the exact image tag of the version you want to install. Available tags are listed on Docker Hub.

Run the check again and verify that Docker Compose now resolves the intended Production image. Then pull all images referenced by the updated Compose configuration:

docker compose pull

Step 3: Migrate the Configuration​

OpenCloud 9.1.x adds new settings to opencloud.yaml. Create and apply the configuration patch with the 9.1.x image before you start OpenCloud.

Stop OpenCloud:

docker compose down

Open a shell in a temporary container with your configuration volume:

docker run --rm -it --user 1000:1000 --entrypoint /bin/sh \
-v <opencloud-config-volume>:/etc/opencloud \
opencloudeu/opencloud:9.1.x

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

Inside the container, create the configuration diff:

cd /etc/opencloud
opencloud init --diff

If the command reports no changes, your config is up to date, run exit and continue with Step 4: Start OpenCloud.

Otherwise, review the generated patch carefully, especially if you use custom settings in opencloud.yaml. Among other changes, the patch adds the auth_guest.service_account settings that are required for guest links.

The patch can also remove the existing thumbnails.thumbnail section. This is expected because the thumbnail configuration changed in OpenCloud 9.1.x. If you customized these settings, migrate them as described in Thumbnails before you apply the patch.

Test and apply the patch:

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

For a detailed description of these steps, see Verify Configuration Changes.

Step 4: Start OpenCloud​

Start OpenCloud with the new version:

docker compose up -d --remove-orphans

Check that OpenCloud is running:

docker compose ps opencloud

Step 5: Rebuild the Search Index​

As of OpenCloud 8.x.x, OpenCloud uses a new, versioned search index. After the upgrade, files that existed before are not found until you rebuild the index.

Rebuild the index:

docker compose exec opencloud opencloud search index --all-spaces --force-rescan

Verify that older files can be found in the Web Client. Then remove the old, unversioned Bleve index:

docker compose exec opencloud rm -r /var/lib/opencloud/search/bleve

If you configured a custom SEARCH_ENGINE_BLEVE_DATA_PATH, replace /var/lib/opencloud/search with the configured path.

vorsicht

Re-indexing can take considerable time on installations with many files. During this process, search results may remain incomplete, and the additional CPU, memory, and disk I/O load can temporarily affect system performance.

Run the re-indexing during a period of low activity and monitor the OpenCloud host and, if applicable, the OpenSearch backend. Do not remove the old index until the rebuild has completed and older files can be found in the Web Client.

Step 6: Apply the Breaking Changes​

Check the following list and apply the changes that are relevant for your deployment:

If you …See
use an external Nginx reverse proxyReverse Proxy
set thumbnail settings via environment variables or YAMLThumbnails
run the OpenCloud services in separate containersSeparate Containers
want to enable guest linksGuest Links
set GRAPH_SPACES_DEFAULT_QUOTASpace Quota
rely on the search results for personal space roots or .space foldersSearch
use customized email templatesEmail Templates
use apps or web extensionsWeb Extensions

If none of these apply, no further changes are required.

Reverse Proxy​

Real-time collaborative editing in the OpenCloud Editor requires the Yjs service. If you have enabled Yjs and use an external Nginx reverse proxy, forward the /yjs WebSocket route.

Also check that WebDAV and the Office integration are still forwarded correctly.

For the required Nginx configuration, see Proxy Config.

Space Quota​

If GRAPH_SPACES_DEFAULT_QUOTA is set, rename it to OC_SPACES_DEFAULT_QUOTA. The value is set in bytes:

OC_SPACES_DEFAULT_QUOTA=10000000000

The old name is deprecated. The quota is still applied, but the spaces.default_quota capability reads only the new name. If you keep the old name, clients display the default of 1 GB instead of your configured value.

Step 7: Verify the Upgrade​

Check that OpenCloud is running and that no errors are logged:

docker compose ps
docker compose logs --tail=200 opencloud

Then test the following functions:

  • Sign in to the Web Client.
  • Open, upload, and download files.
  • Open Spaces, shares, and public links.
  • Search for existing files.
  • Check that previews are displayed.
  • If enabled, invite a guest and check that the invitation email is delivered.

Troubleshooting​

The OpenCloud Container Keeps Restarting​

Check the logs:

docker compose logs --tail=40 opencloud

If the log contains guestlinks: service_account_id must not be empty, guest links are enabled but the configuration has not been migrated. Migrate the configuration as described in Step 3: Migrate the Configuration.

Rebuild the search index as described in Step 5: Rebuild the Search Index.

If a rebuild is already running, wait for it to complete. If expected files are still missing afterward, trigger the rebuild once more. Do not start another rebuild while the previous one is still running.

If files remain missing after the second rebuild, check the OpenCloud logs and the health of the configured search backend.

Previews Are Not Displayed​

See Previews Are Not Displayed in the Upgrade 9.x.x guide.

The Upgrade Cannot Be Completed​

Restore your backup and start OpenCloud 7.2.x again. If the issue persists, check the common issues or open an issue on GitHub.