Upgrading to OpenCloud 9.x.x
OpenCloud 9.x.x introduces guest links and a new thumbnail architecture. It also renames some settings and changes the default behavior of the search and the email templates. Some of these changes require manual steps during the upgrade.
This guide describes the version-specific steps for upgrading to OpenCloud 9.x.x. Use it together with the Standard Upgrade Guide, which describes the general upgrade procedure.
OpenCloud 9.x.x is a Rolling release and is not intended for production environments. For more information, see the Release Lifecycle.
How to Use This Guide
This guide describes the upgrade from the Rolling release 8.x.x to 9.x.x.
If you run the Production release 7.2.x, follow the Upgrade 9.1.x guide instead. It describes the direct upgrade from 7.2.x to the Production release 9.1.x.
- Complete the steps in Before You Start.
- Follow the steps in Upgrade from 8.x.x.
- Check the Breaking Changes that apply to your deployment.
- Verify the upgrade.
Before You Start
-
Create a complete backup of your configuration and data, see Back Up Configuration and Data.
-
Check the version that is currently running:
docker compose images opencloud -
Review the OpenCloud 9.0.0 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.
Upgrade from 8.x.x
Step 1: Upgrade to 9.x.x
Set the new version in your .env file:
OC_DOCKER_TAG=9.0.0
Pull the new image and restart OpenCloud:
docker compose pull opencloud
docker compose up -d
OpenCloud 9.x.x starts with the existing 8.x.x configuration. Guest links stay disabled until you enable them.
Step 2: Migrate the Configuration
OpenCloud 9.x.x adds new settings to opencloud.yaml. Create and apply the configuration patch with the 9.x.x image as described in Verify Configuration Changes in the Standard Upgrade Guide.
In short, 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-rolling:9.0.0
Replace <opencloud-config-volume> with the Docker volume or bind mount that contains your OpenCloud configuration.
Inside the container, create the patch, test it, and apply it:
cd /etc/opencloud
opencloud init --diff
patch --dry-run opencloud.yaml < opencloud.config.patch
patch opencloud.yaml < opencloud.config.patch
The patch adds the auth_guest.service_account settings. Review the patch before you apply it, especially if you use custom thumbnail settings in opencloud.yaml.
The configuration migration is required before you enable guest links. Without the auth_guest.service_account settings, the auth-guest service does not start and the OpenCloud container keeps restarting.
Step 3: Apply the Breaking Changes
Check the following list and apply the changes that are relevant for your deployment:
| If you … | See |
|---|---|
| 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 |
| use customized email templates | Email Templates |
| use apps or web extensions | Web Extensions |
| use an external reverse proxy with custom routes | Reverse Proxy |
If none of these apply, no further changes are required.
Step 4: Verify the Upgrade
Test your deployment as described in Verify the Upgrade.
Breaking Changes
Thumbnails
OpenCloud 9.x.x uses a new thumbnail architecture. The webdav service now handles thumbnail requests, selects the size, and manages the cache. The thumbnails service only generates the images.
Existing previews keep working. No action is required if you use the default settings.
Cache Directory
The cache moves from thumbnails/files to thumbnails/cache and is created automatically. The cache starts empty after the upgrade and is refilled as previews are requested.
The old thumbnails/files folder is no longer used. After you have verified that previews are displayed, you can remove it:
docker compose exec opencloud rm -r /var/lib/opencloud/thumbnails/files
If you configured a custom OC_BASE_DATA_PATH, replace /var/lib/opencloud with the configured path.
If you mounted a separate volume directly at thumbnails/files, set WEBDAV_THUMBNAILS_CACHE_DIR to that mount point. Otherwise the new cache is written next to the volume.
Environment Variables
Old THUMBNAILS_* variable names are still read. We recommend to switch to the new names:
| Old variable | New variable |
|---|---|
THUMBNAILS_RESOLUTIONS | WEBDAV_THUMBNAILS_RESOLUTIONS |
THUMBNAILS_MAX_INPUT_IMAGE_FILE_SIZE | OC_THUMBNAILS_MAX_INPUT_IMAGE_FILE_SIZE |
THUMBNAILS_TXT_FONTMAP_FILE | WEBDAV_THUMBNAILS_TXT_FONTMAP_FILE |
THUMBNAILS_FILESYSTEMSTORAGE_ROOT | WEBDAV_THUMBNAILS_CACHE_DIR |
- If both
THUMBNAILS_MAX_INPUT_IMAGE_FILE_SIZEandOC_THUMBNAILS_MAX_INPUT_IMAGE_FILE_SIZEare set, the old variable takes precedence. Remove the old variable when you set the new one. THUMBNAILS_FILESYSTEMSTORAGE_ROOTpointed to the parent of thefilesfolder.WEBDAV_THUMBNAILS_CACHE_DIRpoints to the cache directory itself.
The following variables are no longer used by the thumbnails service and are ignored:
THUMBNAILS_DATA_ENDPOINTTHUMBNAILS_TRANSFER_TOKENTHUMBNAILS_WEBDAVSOURCE_INSECURETHUMBNAILS_CS3SOURCE_INSECURETHUMBNAILS_GRPC_ADDRTHUMBNAILS_HTTP_ROOT
Do not remove OC_REVA_GATEWAY or OC_INSECURE. These variables are no longer used by the thumbnails service, but other services still read them.
YAML Configuration
Thumbnail settings in opencloud.yaml are not read from the old location. Unknown keys are ignored without an error, so the default values are used instead. If you set thumbnail settings in opencloud.yaml, move them before restarting.
- Old location (8.x.x)
- New location (9.x.x)
thumbnails:
thumbnail:
resolutions: ['16x16', '32x32', '7680x4320']
max_input_image_file_size: 50MB
font_map_file: /etc/opencloud/fontmap.json
filesystem_storage:
root: /var/lib/opencloud/thumbnails
webdav:
thumbnails:
resolutions: ['16', '32', '2048']
max_input_image_file_size: 50MB
txt_fontmap_file: /etc/opencloud/fontmap.json
cache_dir: /var/lib/opencloud/thumbnails/cache
thumbnails:
thumbnail:
max_input_image_file_size: 50MB
max_input_image_file_size must be set in both places, because webdav and the thumbnail generator must use the same limit.
Resolutions
- Resolutions are now edge lengths. Each axis is rounded up separately, so the orientation of an image is preserved.
- The default maximum size is 2048 px instead of 8K. Larger requests receive a 2048 px preview.
- Legacy entries in the format
WidthxHeightare still accepted. Each side is limited to 2048 px. - For previews larger than 2048 px, add a plain length to the resolutions and raise
THUMBNAILS_MAX_OUTPUT_WIDTHandTHUMBNAILS_MAX_OUTPUT_HEIGHTon the thumbnails service accordingly.
Separate Containers
If the OpenCloud services run in separate containers, the webdav service must be able to reach the thumbnail generator and the cache directory.
By default, the thumbnails service listens on 127.0.0.1:9186 and can only be reached from the same container. Configure both services:
# thumbnails service
THUMBNAILS_HTTP_ADDR=0.0.0.0:9186
# webdav service
WEBDAV_THUMBNAILS_GENERATOR_URL=http://thumbnails:9186
The thumbnails service performs no authentication. Do not publish port 9186. Make it reachable only on an internal network.
No action is required for the default single-container deployment.
HEIC, HEIF, and AVIF Previews
The Web Client can display previews of HEIC, HEIF, and AVIF images. The OpenCloud image cannot decode these formats. They require an external imagor instance as thumbnail generator.
If you use opencloud-compose, update the repository and add thumbnails/imagor.yml to COMPOSE_FILE in your .env file. The module starts imagor on an internal network, sets WEBDAV_THUMBNAILS_GENERATOR_URL, and adds the image types to OC_THUMBNAILS_ADDITIONAL_SOURCE_TYPES.
For all thumbnail migration details, see the webdav MIGRATION.md.
Guest Links
OpenCloud 9.x.x introduces the auth-guest service. It allows users to share files and folders with external people by email address.
Guest links are disabled by default. You can upgrade to 9.x.x without enabling them.
To enable guest links:
- Migrate the configuration as described in Step 2: Migrate the Configuration.
- Set
OC_ENABLE_GUEST_LINKS=truefor the OpenCloud container. - Configure SMTP for the notifications service and enable the notifications service. Guests receive their invitation link and PIN by email.
- Restart OpenCloud.
Guest sessions are signed with a key derived from OC_JWT_SECRET. If you change OC_JWT_SECRET, all guest sessions become invalid.
For all configuration options, see the auth-guest service documentation.
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.
Search
By default, search results no longer include the root folder of personal spaces and the .space folder of spaces. These resources stay in the search index, so no re-indexing is required.
The new setting SEARCH_QUERY_TEMPLATE defines the query filter that is applied to every search. The default value is:
({{.QUERY}}) AND (NOT path:"./.space" AND NOT id:{{.SPACE_ROOT_PERSONAL}})
Change it only if you need a different search behavior.
Email Templates
The HTML emails of the notifications service use a new layout. The templates are now split into layout.html.tmpl, message.html.tmpl, and digest.html.tmpl in templates/html/.
- Custom template folders that contain only
email.html.tmplkeep working. - If you use customized templates, check the emails after the upgrade.
- Times in daily and weekly digests are displayed in UTC.
Web Extensions
Apps and web extensions can now declare the OpenCloud versions they support. If an installed extension does not support OpenCloud 9.x.x, its status is displayed in red in the admin overview.
After the upgrade, check your installed extensions and update them if required.
Reverse Proxy
If you use an external reverse proxy with custom routes, check after the upgrade that WebDAV, Office integration, and, if enabled, the /yjs WebSocket route are still forwarded correctly. For the required Nginx configuration, see Proxy Config.
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 and shares.
- 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 2: Migrate the Configuration, or disable guest links.
Previews Are Not Displayed
- If you set thumbnail settings in
opencloud.yaml, check that you moved them towebdav: thumbnails:. - If the services run in separate containers, check
WEBDAV_THUMBNAILS_GENERATOR_URL. - Check that the webdav service can write to the cache directory.
Clients Show a Default Space Quota of 1 GB
Rename GRAPH_SPACES_DEFAULT_QUOTA to OC_SPACES_DEFAULT_QUOTA and restart OpenCloud.
Older Files Are Not Found by the Search
If you upgraded from 7.x.x without upgrading to 8.x.x first, rebuild the search index as described in Upgrade 8.x.x.