numbered sections (finished)

modules/ROOT/pages/depl-examples/minimal-bare-metal.adoc

@@ -85,6 +85,17 @@ Congratulations, you now have access to your Infinite Scale instance.
 
 == Installation
 
+[NOTE]
+====
+If you have installed Infinite Scale already but want to upgrade it, make a copy of the existing binary first!
+
+[source,bash,subs="attributes+"]
+----
+sudo cp {ocis_bin}/ocis {ocis_bin}/ocis.old
+----
+
+====
+
 * To get the stable binary from ownCloud, visit {ocis-downloadpage-url}/{download-type}/?sort=time&order=desc[download.owncloud.com,window=_blank], select the version and the platform of choice and copy the link of the file. Check the sort order on the modification date to get the most recent releases on top. Depending on your system and preferences, you may want to save the binary in `{ocis_bin}`.
 +
 --

modules/ROOT/pages/migration/upgrading_5.0.x_7.0.0.adoc

@@ -17,6 +17,8 @@ IMPORTANT: Check below, if you are affected by breaking changes and prepare all
 . Download and install Infinite Scale +
 *Do not start it after downloading the binary or image*!
 . Shut down the Infinite Scale instance
+. We strongly recommend doing a backup
+. Reconfigure the deployment
 . Manage Breaking Changes
 . Start Infinite Scale
 
@@ -26,38 +28,54 @@ IMPORTANT: Check below, if you are affected by breaking changes and prepare all
 
 Download and install Infinite Scale via:
 
-* *Binary* +
+=== Binary
+
 Follow the xref:depl-examples/minimal-bare-metal.adoc#installation[Installation] section of the bare metal deployment example.
 
-* *Image Based Deployments*
+=== Image Based Deployments
+
+* Issue the following command to download the new image:
 +
 [source,bash,subs="attributes+"]
 ----
 docker pull owncloud/ocis:7.0.0
 ----
 
-** When using `docker run`
-*** Update the image version used in the docker run command.
+== Shut Down the Infinite Scale Instance
+
+Depending how you deployed Infinite Scale, you need to shut it down differently.
 
-** When using `docker compose`
-*** Update _every_ compose file where the `ocis image` is referenced accordingly.
-*** If you have used the deployment examples based on _rolling releases version 6.x_ either for xref:depl-examples/ubuntu-compose/ubuntu-compose-prod.adoc[Local Production Setup] or xref:depl-examples/ubuntu-compose/ubuntu-compose-hetzner.adoc[Deployment on Hetzner], read the *Updating* section of those pages carefully. 
+* *Binary* +
+For binary deployments, do a graceful shutdown as described in xref:depl-examples/minimal-bare-metal.adoc#stopping-infinite-scale[Stopping Infinite Scale].
 
-** When using `Kubernetes - Helm`
-*** Update `{{ .Values.image.tag }}` and/or `{{ .Chart.AppVersion }}` accordingly.
+* *docker run* +
+For depoyments using `docker run` do a graceful shutdown as described in xref:depl-examples/container-setup.adoc#stop-a-running-container[Stop a Running Container].
 
-== Shut Down the Infinite Scale Instance
+* *docker compose* +
+For deployments using `docker compose` do a graceful shutdown as described in xref:depl-examples/ubuntu-compose/ubuntu-compose-prod.adoc#stop-the-deployment[Stop the Deployment].
 
-Depending how you deployed Infinite Scale, you need to shut it down differently.
+* *Any other image based deployment* +
+For any other image based deployment, shut down Infinite Scale according the vendors deployment description.
+
+== Backup of Infinite Scale
 
-* For binary deployments, do a graceful shutdown as described in xref:depl-examples/minimal-bare-metal.adoc#stopping-infinite-scale[Stopping Infinite Scale].
+See the xref:maintenance/b-r/backup_considerations.adoc[Backup Considerations] and the xref:maintenance/b-r/backup.adoc[Backup] documentation for more details.
 
-* For depoyments using `docker run` do a graceful shutdown as described in xref:depl-examples/container-setup.adoc#stop-a-running-container[Stop a Running Container].
+== Reconfigure the Deployment
 
-* For deployments using `docker compose` do a graceful shutdown as described in xref:depl-examples/ubuntu-compose/ubuntu-compose-prod.adoc#stop-the-deployment[Stop the Deployment].
+Reconfigure the deployment to use the new image:
 
-* For any other image based deployment, shut down Infinite Scale according the vendors deployment description.
+* For binary, nothing extra needs to be done
 
+* When using `docker run`
+** Update the image version used in the docker run command.
+
+* When using `docker compose`
+** Update _every_ compose file where the `ocis image` is referenced accordingly.
+** If you have used the deployment examples based on _rolling releases version 6.x_ either for xref:depl-examples/ubuntu-compose/ubuntu-compose-prod.adoc[Local Production Setup] or xref:depl-examples/ubuntu-compose/ubuntu-compose-hetzner.adoc[Deployment on Hetzner], read the *Updating* section of those pages carefully. 
+
+* When using `Kubernetes - Helm`
+** Update `{{ .Values.image.tag }}` and/or `{{ .Chart.AppVersion }}` accordingly.
 
 == Manage Breaking Changes
 
@@ -66,50 +84,47 @@ Depending how you deployed Infinite Scale, you need to shut it down differently.
 
 === How to Identify if You Are Affected
 
-* If you are using deprecated environment variables in your config.
+* If you are using removed or deprecated environment variables in your config.
 ** See the xref:deployment/services/env-var-changes.adoc[Added and Removed Environment Variables] documentation.
 
-* Because the xref:{s-path}/activitylog.adoc[activitylog] service has been added and is started automatically, everyone who upgrades is affected.
+* Because the xref:{s-path}/activitylog.adoc[activitylog] service has been added and is started automatically, _everyone_ who upgrades is affected.
 
 === 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.
+==== 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.
+* Environment variables that habe been removed from Infinite Scale can safely be removed from the config if set manually.
+
+==== Add new Infnite Scale config settings
+
+To do so, the following steps need to be taken, here is the *overview*:
 
-* Add new Infnite Scale config settings. +
-To do so, the following steps need to be taken, here is the overview:
-+
---
-. Get the new binary/image, but do not start Infinite Scale
 . Get the config diff via command
 . Apply the diff created
---
-+
-See the detailed steps below.
+. Start Infinite Scale as usual
 
-* You can now start Infinite Scale as usual
+See the next section for *details* how to update the config settings.
 
-{empty}
+=== Update Config Settings
 
-Update Config Settings::
-* If not already done, get the new Infinite Scale version as described in xref:download-and-install-infinite-scale[Download and Install Infinite Scale].
+Run the `ocis init --diff` command:
 
-* Run the `ocis init --diff` command: +
 Because this will now run the new ocis code, it will create two files to help manage the needed changes. Note that the patch file is only created if changes are found:
-+
---
+
 . `ocis.config.patch` which contains all the changes that can be applied and
 . `ocis.yaml.<time-stamp>.backup` containing a backup of the original config.
---
-+
+
+Note that after applying the patch file, the created files by the `--diff` option must be deleted manually.
+
 The diff option will NOT overwrite anything though questions will be asked. Consider using the correct answer for `certificate checking` as this will influence the respective diff output.
-+
+
 If a patch file is created, do a review before applying it.
-+
+
 Depending on the deployment selected, you need to prepare for this command differently, assuming the location of the config directory is the default:
 
-** *Binary Deployment*:
+* *Binary Deployment*:
 +
 --
 [source,bash]
@@ -122,10 +137,11 @@ Change into the Infinite Scale config directory located at `$HOME/.ocis/config/`
 ----
 patch < ocis.config.patch
 ----
-{empty}
 --
 
-** *Docker Deployment*:
+{empty}
+
+* *Docker Deployment*:
 +
 --
 This will open a shell in a temporary container using the new Infinite Scale image. Note that you *MUST* provide the mount/volume definition where the configuration settings are stored to make the `ocis init` command work. The bind mount from below is just an example and fails if the local directory does not exist!
@@ -151,10 +167,11 @@ Change into the containers config directory `/etc/ocis` and apply the changes wi
 ----
 patch < ocis.config.patch
 ----
-{empty}
 --
 
-** *Docker Compose Deployment*:
+{empty}
+
+* *Docker Compose Deployment*:
 +
 --
 This will open a shell in a temporary container using the new Infinite Scale image. Note that you *MUST* provide the volume definition (either the volume name or the local path) where the configuration settings are stored defined in the compose file to make the `ocis init` command work. The named volume `ocis-config` from below is just an example and derives from our docker compose deployment examples.
@@ -180,17 +197,20 @@ Change into the containers config directory `/etc/ocis` and apply the changes wi
 ----
 patch < ocis.config.patch
 ----
-{empty}
 --
 
-** *Any Other Image Based Deployment*:
+{empty}
+
+* *Any Other Image Based Deployment*:
 +
 --
 Use one of the Docker based examples from above and derive from. 
 --
 
 == Start Infinite Scale
 
+When you have finished upgrading, you can now start infinite Scale as ususal.
+
 :sectnums!:
 
 == Changed or Added CLI Commands