docs: prepare ocis migration guide from 4 to 5

modules/ROOT/pages/deployment/services/env-var-changes.adoc

@@ -1,6 +1,6 @@
 # Changed Environment Variables in Versions
 :toc: right
-:description: This page contains tables with added and removed environment variables between Infinite Scale version 4.0.5 and 5.0.0.
+:description: This page contains tables with added and removed environment variables between Infinite Scale version 4.0.0 and 5.0.0.
 
 :source_path: {ocis-services-raw-url}{service_tab_1}{ocis-services-final-path}adoc/env-var-deltas/
 // https://raw.githubusercontent.com/owncloud/ocis/docs-stable-5.0/services/_includes/adoc/env-var-deltas/

modules/ROOT/pages/migration/upgrading-ocis.adoc

@@ -15,6 +15,24 @@ IMPORTANT: If not explicitly mentioned, any upgrade is forward only and a backst
 
 IMPORTANT: When upgrading from an older release to the desired one, *ALL* upgrade steps from each release must be taken in order and none can be skipped.  
 
+== Version 4.0.0 to 5.0.0
+
+=== Notable Changes Requiring Manual Intervention
+
+* The xref:deployment/container/orchestration/orchestration.adoc#using-our-helm-charts-with-infinite-scale[Helm Chart] has been upgraded.
+* The maintenance command `ocis storage-users uploads list` has been deprecated and will be removed in a later release. A successor with more capabilities has been implemented, see the xref:deployment/services/s-list/storage-users.adoc#manage-unfinished-uploads[Manage Unfinished Uploads] documentation for more details.
+
+=== Breaking Changes Requiring Manual Intervention
+
+* 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.
+* Resharing is now disabled by default and will be removed from the product.
+
+=== Upgrade Steps
+
+For a detailed description of the steps to upgrade, see the xref:migration/upgrading_4.0.0_5.0.0.adoc[Upgrading from 4.0.0 to 5.0.0] documentation.
+
 == Version 3.0.0 to 4.0.0
 
 === Notable Changes Requiring Manual Intervention

modules/ROOT/pages/migration/upgrading_3.0.0_4.0.0.adoc

@@ -132,7 +132,7 @@ When the instance has started successfully, check the logs for any unusual entri
 
 == Manage Breaking Changes
 
-* All environment variables that were marked for deprecation in Infinite Scale release 4.0.0 have finally been removed.
+* All environment variables that were marked for deprecation in Infinite Scale release 3.0.0 have finally been removed.
 * Client pool selectors have changed from IP addresses `127.0.0.1:9xxx` to service names `com.owncloud.api.*`. There is no need to configure them at the moment.
 
 === How to Identify if You Are Affected

modules/ROOT/pages/migration/upgrading_4.0.0_5.0.0.adoc

@@ -0,0 +1,149 @@
+= Upgrading from 4.0.x to 5.0.0
+:toc: right
+:description: This document describes the necessary steps when upgrading Infinite Scale from release 4.0.x to 5.0.0.
+
+== Introduction
+
+{description}
+
+IMPORTANT: Read the important notes in the xref:migration/upgrading-ocis.adoc#introduction[Upgrading Infinite Scale] documentation before you start.
+
+== Upgrade Steps
+
+. Shut down the Infinite Scale instance.
+. Update Infinite Scale via:
++
+--
+* Docker
++
+[source,bash]
+----
+docker pull owncloud/ocis:5.0.0
+----
+
+* or get the binary from {ocis-downloadpage-url}?sort=time&order=desc[download.owncloud.com,window=_blank].
+--
+
+== 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.
+* Resharing is now disabled by default and will be removed from the product.
+* The structure of the `theme.json` file has changed.
+
+=== How to Identify if You Are Affected
+
+* If you are using deprecated environment variables in your config.
+** See the xref:deployment/services/env-var-changes.adoc[Added and Removed Environment Variables] documentation.
+* If you have changed the default configuration for the xref:deployment/services/env-vars-special-scope.adoc#extended-environment-variables[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.
+
+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.
++
+--
+{empty}
+[width="100%",cols="40%,30%,20%"]
+|===
+3+^h| Default used value, new and old
+h| Global envvar
+h| New value
+h| Old value
+
+| xref:deployment/services/env-vars-special-scope.adoc#extended-environment-variables[MICRO_REGISTRY]
+| nats-js-kv
+| memory
+
+| xref:deployment/services/env-vars-special-scope.adoc#extended-environment-variables[MICRO_REGISTRY_ADDR]
+| 127.0.0.1:9233
+| <was not set>
+|===
+{empty}
+--
+
+** 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:
+
+[source,yaml]
+----
+---
+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.
+
+[source,plaintext]
+----
+OCIS_SERVICE_ACCOUNT_ID=<some-uuid-v4>
+OCIS_SERVICE_ACCOUNT_SECRET=<some-secret-string>
+----
+
+NOTE: For new deployments starting with Infinite Scale 5.0.0, these values are autogenerated by running the `'ocis init'` command.
+
+WARNING: If no values are provided during an upgrade, Infiinite Scale will not start and log a fatal error.
+--
+
+* 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 old structure can be found at: https://doc.owncloud.com/ocis/4.0/deployment/webui/webui-theming.html#example-theme[Infinite Scale 4.0 Example Theme, window=_blank].
+* The new structure can be found at: https://owncloud.dev/clients/web/theming/#example-theme[Infinite Scale 5.0 Example Theme, window=_blank].
+
+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.
+
+WARNING: 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.
+--
+
+=== 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.
+
+* Resharing +
+We have disabled the resharing feature by default. It will be removed from the product. Existing reshares will still be visible to the original resource owner. Creation of new reshares will not be possible. Make sure that `OCIS_ENABLE_RESHARING` is *not* set to `true` in your deployments.