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 version | Upgrade path |
|---|---|
| 7.2.x | Upgrade directly to 9.1.x with this guide. |
| 4.x | Upgrade to 7.2.x first as described in Upgrade 7.2.x. Then upgrade to 9.1.x with this guide. |
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.
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:
- Using Named Volumes
- Using Bind Mounts
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.
docker run --rm -it --user 1000:1000 --entrypoint /bin/sh \
-v <path-to-your-config-directory>:/etc/opencloud \
opencloudeu/opencloud:9.1.x
Replace <path-to-your-config-directory> with the host directory that contains your opencloud.yaml.
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.
- Bleve (default)
- OpenSearch
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.
Follow these steps only if your OpenCloud 7.2.x installation already used OpenSearch. If it used the default Bleve backend, follow the Bleve instructions instead.
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. If you use OpenSearch from opencloud-compose, list the existing indexes and remove the old one from within the OpenSearch container:
docker compose exec opensearch \
curl "http://localhost:9200/_cat/indices/opencloud-resources*?v"
docker compose exec opensearch \
curl -X DELETE "http://localhost:9200/opencloud-resources"
If you changed OPENSEARCH_RESOURCE_INDEX, replace opencloud-resources with the configured index name. If you use an external OpenSearch instance, run the requests against its configured URL and include any required authentication and TLS options.
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 proxy | Reverse Proxy |
| set thumbnail settings via environment variables or YAML | Thumbnails |
| run the OpenCloud services in separate containers | Separate Containers |
| want to enable guest links | Guest Links |
set GRAPH_SPACES_DEFAULT_QUOTA | Space Quota |
rely on the search results for personal space roots or .space folders | Search |
| use customized email templates | Email Templates |
| use apps or web extensions | Web 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.
Older Files Are Not Found by the Search
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.