ocis upgrade steps

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

@@ -9,9 +9,64 @@
 
 NOTE: For any Infinite Scale version to upgrade to, see {ocis-downloadpage-url}?sort=time&order=desc[download.owncloud.com,window=_blank] or {docker-ocis-url}[Infinite Scale image] to get the right version.
 
+IMPORTANT: Before starting any upgrade, make a xref:maintenance/b-r/backup.adoc[backup] first.
+
 IMPORTANT: If not explicitly mentioned, any upgrade is forward only and a backstep is neither supported nor recommended and will most likely break the instance.
 
-IMPORTANT: Before starting any upgrade, make a xref:maintenance/b-r/backup.adoc[backup] first.
+IMPORTANT: When upgrading from the current running release to the desired one, *ALL* upgrade steps from each release must be taken in order and none must be skipped. 
+
+== Version 3.0.0 to 3.1.0
+
+=== Notable Changes Requiring Manual Intervention
+
+* The space index of the decomposedFS will be automatically migrated from symlinks to messagepack. This migration needs preperation to run successfully.
+* The xref:deployment/container/orchestration/orchestration.adoc#using-helm-charts-with-infinite-scale[Helm Chart] has been upgraded.
+
+=== Upgrade Steps
+
+. Shut down the Infinite Scale instance.
+. Update Infinite Scale via:
++
+--
+* Docker
++
+[source,bash]
+----
+docker pull owncloud/ocis:3.1.0
+----
+
+* or get the binary from the link above.
+--
+
+. Migrate the Space Index to Messagepack: +
+It is important to disable clients and users logging in while the space index migration to `messagepack` is in progress. To do so, start Infinite Scale with only two necessary services. The example uses the binary as base:
++
+--
+[source,bash]
+----
+OCIS_RUN_SERVICES="storage-users,nats" \
+ocis server
+----
+
+Because the proxy service is not running, no clients or users can login. During the restart of Infinite Scale, the symlinks of spaces in the DecomposedFS will be migrated to `messagepack` _automatically_ via the `storage-users` service. The start of the migration can be identified in the log with a message like:
+
+[source,plaintext]
+----
+{"level":"info","root":"/var/lib/ocis/storage/users","time":"2023-06-16T12:21:49.441395153Z","caller":"github.com/cs3org/reva/[email protected]/pkg/storage/utils/decomposedfs/migrator/0003_switch_to_messagepack_metadata.go:45","message":"Migrating to messagepack metadata backend..."}
+----
+
+When migration has finished - which can take a while depending on the quantity of files - you can see a log message like below:
+
+[source,plaintext]
+----
+{"level":"info","time":"2023-06-16T12:30:05.267986656Z","caller":"github.com/cs3org/reva/[email protected]/pkg/storage/utils/decomposedfs/migrator/0003_switch_to_messagepack_metadata.go:106","message":"done."}`
+----
+
+Finally start the Infinite Scale instance as usual.
+--
+
+. Check your Instance +
+When the instance has started successfully, check the logs for any unusual entries.
 
 == Version 2.0.0 to 3.0.0