Upgrading from 4.0.x to 5.0.0

Introduction

This document describes the necessary steps when upgrading Infinite Scale from release 4.0.x to 5.0.0.

Read the important notes in the Upgrading Infinite Scale documentation before you start.
Check below, if you are affected by breaking changes and prepare all steps mentioned before you start the upgrade.

Upgrade Steps

  1. Shut down the Infinite Scale instance.

  2. Update Infinite Scale via:

Manage Breaking Changes

  • All environment variables that were marked for deprecation in Infinite Scale release 4.0.0 have finally been removed.

  • The default service registry has been changed.

  • Service accounts are now needed for some backend operations.

  • The structure of the theme.json file has changed.

  • Resharing will be disabled and removed from the product.

How to Identify if You Are Affected

  • If you are using deprecated environment variables in your config.

  • You must set service account environment variables for existing instances.

  • If you have changed the default configuration for the MICRO_REGISTRY environment variable.

  • If you have used custom theming in your Infinite Scale instance:

    • by providing a custom theme.json file.

    • by uploading a custom logo without additional changes to the theme.

  • If you have used resharing

In all other cases, there is nothing that needs to be done as the new defaults for client pool selectors will be used automatically.

How to Manage the Change

  • Manage deprecated variables

    • Environment variables that have been deprecated without successor can safely be removed from the configuration. These envvars do not harm as they are not used anymore.

    • Environment variables that have been deprecated with a successor need to be updated accordingly.

  • The MICRO_REGISTRY environment variable

    • We changed the service registry to use the natsjs key-value store from the nats service as a storage.

      Default used value, new and old

      Global envvar

      New value

      Old value

      MICRO_REGISTRY

      nats-js-kv

      memory

      MICRO_REGISTRY_ADDR

      127.0.0.1:9233

      <was not set>

    • If you have more than one container or process for the Infinite Scale deployment:

      You need to make the same service registry available to all Infinite Scale processes and expose the micro registry in the container or process where you have the nats service running and use that from the other processes as a shared registry.

      Docker compose example with an app provider:

      ---
version: "3.7"

services:
  ocis:
    environment:
      NATS_NATS_HOST: 0.0.0.0 # bind on all interfaces to expose the nats service
  ...
  ocis-appprovider-collabora:
    environment:
      # use the shared registry from the ocis container
      MICRO_REGISTRY_ADDRESS: ocis:9233

  • We introduced service accounts in the area of service-to-service communication. This change was needed to properly authenticate backend calls which are not triggered by user interaction like search indexing, auto accepting of shares or timed trashbin cleanup jobs. Instances which are migrated from Infinite Scale 4.x need manual steps to avoid becoming non functional.

    Two new global environment variables have been introduced to manually configure the instance: OCIS_SERVICE_ACCOUNT_ID and OCIS_SERVICE_ACCOUNT_SECRET. Please set the first one to a random uuid and create a strong secret value for the second one.

    OCIS_SERVICE_ACCOUNT_ID=<some-uuid-v4>
OCIS_SERVICE_ACCOUNT_SECRET=<some-secret-string>
    For new deployments starting with Infinite Scale 5.0.0, these values are autogenerated by running the 'ocis init' command.

    If no values are provided during an upgrade, Infiinite Scale will not start and log a fatal error like:

    The service account id has not been configured for graph. Make sure your ...

  • We have changed the structure of the theme.json file which was done for several reasons:

    • To be able to support multiple client platforms,

    • to be able to create a fallback chain of theming information and

    • to reduce the amount of configuration needed for theming.

    If you have a custom theme.json file, you need to update it to the new structure.

    The most important adjustment is the fact, that the old structure only supported multiple themes on a single platform (web). The new structure defines a common and a clients section on the root level of the file.

    • The common section provides defaults for all client platforms.

    • The clients section provides platform specific general theming information and a list of themes.

    Note that the "Desktop", "Android" and "iOS" platforms currently lack support for the themes provided by Infinite Scale.

    The theming data from your old theme.json file needs to be moved to the web section of the new theme.json file. This can be done with copy & paste and only small adjustments, since the structure of a single, web-specific theme within the theme.json remains mostly unchanged.

    If you have uploaded a custom logo without additional changes to the theme, Infinite Scale internally created a custom 'theme.json' anyway which now needs to be deleted. Otherwise any logo upload attempt will fail.

  • Resharing

    Because resharing is deprecated and will be removed in a subsequent release, the environment variables enabling resharing should be set to false respectively removed from the config. Doing so, resharing will be disabled. Note that existing reshares will continue to be visible to the original resource owner.

    The environment variables responsible for resharing are:

    • (global) OCIS_ENABLE_RESHARING

      • (local) FRONTEND_ENABLE_RESHARING

      • (local) GRAPH_ENABLE_RESHARING

      • (local) SHARING_ENABLE_RESHARING

    How to disable resharing

    • If you have set any of the local environment variables manually, remove it from your configuration.

    • Manually set OCIS_ENABLE_RESHARING to false.
      Note that this environment variable can safely be removed from the config when resharing has been removed in a subsequent release. A removal notification will be provided.

Deprecations

  • Service Registries
    We deprecated some service registries. If your MICRO_REGISTRY config is set to one of these values mdns, nats, kubernetes, etcd, consul please use nats-js-kv in the future (memory is only intended for testing environments).

  • Micro caches and stores
    We deprecated some micro caches and stores. If one of your *_CACHE_STORE variables is using one of there values redis-sentinel, redis, etcd, nats or ocmem, use nats-js-kv in the future. Note that memory is only intended for testing environments.