Zum Hauptinhalt springen
Version: 9.1

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.

important

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.

hinweis

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.

  1. Complete the steps in Before You Start.
  2. Follow the steps in Upgrade from 8.x.x.
  3. Check the Breaking Changes that apply to your deployment.
  4. 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.

important

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 YAMLThumbnails
run the OpenCloud services in separate containersSeparate Containers
want to enable guest linksGuest Links
set GRAPH_SPACES_DEFAULT_QUOTASpace Quota
use customized email templatesEmail Templates
use apps or web extensionsWeb Extensions
use an external reverse proxy with custom routesReverse 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.

vorsicht

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 variableNew variable
THUMBNAILS_RESOLUTIONSWEBDAV_THUMBNAILS_RESOLUTIONS
THUMBNAILS_MAX_INPUT_IMAGE_FILE_SIZEOC_THUMBNAILS_MAX_INPUT_IMAGE_FILE_SIZE
THUMBNAILS_TXT_FONTMAP_FILEWEBDAV_THUMBNAILS_TXT_FONTMAP_FILE
THUMBNAILS_FILESYSTEMSTORAGE_ROOTWEBDAV_THUMBNAILS_CACHE_DIR
  • If both THUMBNAILS_MAX_INPUT_IMAGE_FILE_SIZE and OC_THUMBNAILS_MAX_INPUT_IMAGE_FILE_SIZE are set, the old variable takes precedence. Remove the old variable when you set the new one.
  • THUMBNAILS_FILESYSTEMSTORAGE_ROOT pointed to the parent of the files folder. WEBDAV_THUMBNAILS_CACHE_DIR points to the cache directory itself.

The following variables are no longer used by the thumbnails service and are ignored:

  • THUMBNAILS_DATA_ENDPOINT
  • THUMBNAILS_TRANSFER_TOKEN
  • THUMBNAILS_WEBDAVSOURCE_INSECURE
  • THUMBNAILS_CS3SOURCE_INSECURE
  • THUMBNAILS_GRPC_ADDR
  • THUMBNAILS_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.

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

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 WidthxHeight are 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_WIDTH and THUMBNAILS_MAX_OUTPUT_HEIGHT on 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
warnung

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.

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:

  1. Migrate the configuration as described in Step 2: Migrate the Configuration.
  2. Set OC_ENABLE_GUEST_LINKS=true for the OpenCloud container.
  3. Configure SMTP for the notifications service and enable the notifications service. Guests receive their invitation link and PIN by email.
  4. 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.

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.tmpl keep 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 to webdav: 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.

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.