Merge pull request #1038 from owncloud/update_compose_examples

Update the compose examples to be ready to upgrade for the next release

modules/ROOT/partials/depl-examples/ubuntu-compose/shared-setup.adoc

@@ -304,6 +304,8 @@ Define these settings according to your eMail configuration. With the settings d
 
 NOTE: When not defining your own domain names, internal evaluation only domain names with self-signed certificates are used automatically.
 
+NOTE: There can be additional options to be configured like web apps. These should be configured after successfully starting the deployment without issues. This eases finding any first startup issues that need to be solved first.
+ 
 == Certificate Generation Process
 
 The recommended process to generate live certificates is the following:
@@ -573,16 +575,91 @@ docker volume ls
 docker volume rm {ocis_wopi}_ocis-config {ocis_wopi}_ocis-data
 ----
 
-== Updating
+== Updating and Upgrading
+
+=== Updating
+
+// for testing
+//:version-type: production
 
 ifeval::["{version-type}" == "rolling"]
-Note that this deploymment can, for the time being, only be updated within Infinite Scale rolling releases.
+For rolling releases, the following steps are essential to avoid breaking the setup. This is because rolling releases depend on all updates being done consecutively.
+
+If new Infinite Scale releases are available, you *must not* skip any version in between the current running and the latest available rolling release for internal update reasons. All versions need to be downloaded and started one time. For more details see the https://owncloud.dev/ocis/release_roadmap/#updating-and-overlap[Updating and Overlap] description in the developer documentation.
+
+* Each upgrade consists of a set of commands:
++
+[source,bash]
+----
+sudo docker compose stop \
+sudo docker compose pull \
+sudo docker compose up -d --remove-orphans
+----
+
+* If there is no release gap, run the command block once.
+
+* For *any* https://owncloud.dev/ocis/release_roadmap/#dates[release gap], you must run the command block from above once and set the respective release in the `OCIS_DOCKER_TAG` _before_ pulling. Use no value for the last release, it defaults to `latest`.
+
+* Check if there are any Infinite Scale config changes. To do so, run a `ocis init --diff` plus apply any patches. The detailed how-to is described in the xref:migration/upgrading-ocis.adoc[Upgrading Infinite Scale] guide for 7.0.0. When done, bring the deployment up.
+
+* Finally, you can remove any old images if no longer used.
+
+Note that we advise to manually check if the deployment source has changed. If this is the case, stop the deployment, backup your existing deployment source/configuration and update the xref:download-and-transfer-the-example[deployment sources], then re-apply your configuration settings and bring the deployment up.
+
 endif::[]
 
-If new Infinite Scale releases are available, you *must not* skip any version in between the current running and the latest available release for internal upgrade reasons. All versions need to be downloaded and started one time. For more details see the https://owncloud.dev/ocis/release_roadmap/#updating-and-overlap[Updating and Overlap] description in the developer documentation.
+ifeval::["{version-type}" != "rolling"]
+
+Follow these steps to update between production releases:
+
+For patch releases only!::
++
+--
+These commands will stop the deployment, update all images and start the deployment again. This works because the relevant `xxx_TAG` variables in the `.env` file are set to `latest` by default while others have hardcoded versions set.
+
+[source,bash]
+----
+sudo docker compose stop \
+sudo docker compose pull \
+sudo docker compose up -d --remove-orphans
+----
+{empty}
+--
 
-* If there is no release gap, you can update by just stopping and starting the compose environment.
-* For *any* https://owncloud.dev/ocis/release_roadmap/#dates[release gap], you must stop the compose environment with `docker compose down`, set the `OCIS_DOCKER_TAG` variable in the `.env` file accordingly, pull the new image with `docker compose pull` and start the compose environment with `docker compose up -d` again. For the last release, you can remove any setting of `OCIS_DOCKER_TAG` as `latest` is used by default.
+endif::[]
+
+=== Upgrading
+
+For all major and minor releases including from former rolling to production::
++
+--
+* Stop the deployment with:
++
+[source,bash]
+----
+sudo docker compose stop
+----
+
+* If upgrading from rolling to production, change the `OCIS_DOCKER_IMAGE` environment variable from `owncloud/ocis-rolling` to `owncloud/ocis` in the `.env` file.
+
+* Follow the respective xref:migration/upgrading-ocis.adoc[Upgrading Infinite Scale] guide.
+
+* Backup your existing deployment source/configuration and update the xref:download-and-transfer-the-example[deployment sources] - if they have been changed, re-apply your configuration settings.
+
+* Re-pull the deployment. This will update all images with any versions that might have changed.
++
+[source,bash]
+----
+sudo docker compose pull
+----
+
+* Start the deployment.
++
+[source,bash]
+----
+sudo docker compose up -d --remove-orphans
+----
+--
 
 == Certificate Renewal