From 65a122aa04c1de39c415900bc643985ecf506540 Mon Sep 17 00:00:00 2001 From: Martin Mattel Date: Tue, 29 Oct 2024 15:10:58 +0100 Subject: [PATCH 1/4] Update compose deployment examples --- .../ubuntu-compose/shared-setup.adoc | 82 +++++++++++++++++-- 1 file changed, 77 insertions(+), 5 deletions(-) diff --git a/modules/ROOT/partials/depl-examples/ubuntu-compose/shared-setup.adoc b/modules/ROOT/partials/depl-examples/ubuntu-compose/shared-setup.adoc index f5b3f651..23724489 100644 --- a/modules/ROOT/partials/depl-examples/ubuntu-compose/shared-setup.adoc +++ b/modules/ROOT/partials/depl-examples/ubuntu-compose/shared-setup.adoc @@ -573,16 +573,88 @@ docker volume ls docker volume rm {ocis_wopi}_ocis-config {ocis_wopi}_ocis-data ---- -== Updating +== Updating and Upgrading + +=== Updating + +: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 consecutive updates to be taken. + +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 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. + +* 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 advice 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 the configuration 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, updates ALL images and starts 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 rolling to production:: ++ +-- +* Stop the deployment with: ++ +[source,bash] +---- +sudo docker compose stop +---- + +* 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 the configuration! + +* Re-pull the deployment. This will update all images that versions might have changed. ++ +[source,bash] +---- +sudo docker compose pull +---- + +* Start the deployment. ++ +[source,bash] +---- +sudo docker compose up -d --remove-orphans +---- +-- == Certificate Renewal From 9cfd992f98a7998bbfc0c2c73d54b461600e0743 Mon Sep 17 00:00:00 2001 From: Martin Mattel Date: Tue, 29 Oct 2024 17:40:35 +0100 Subject: [PATCH 2/4] updates --- .../ubuntu-compose/shared-setup.adoc | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/modules/ROOT/partials/depl-examples/ubuntu-compose/shared-setup.adoc b/modules/ROOT/partials/depl-examples/ubuntu-compose/shared-setup.adoc index 23724489..2cd2931d 100644 --- a/modules/ROOT/partials/depl-examples/ubuntu-compose/shared-setup.adoc +++ b/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 fining any first startup issues that need to be solved first. + == Certificate Generation Process The recommended process to generate live certificates is the following: @@ -577,12 +579,13 @@ docker volume rm {ocis_wopi}_ocis-config {ocis_wopi}_ocis-data === Updating -:version-type: production +// for testing +//:version-type: production ifeval::["{version-type}" == "rolling"] For rolling releases, the following steps are essential to avoid breaking the setup. This is because rolling releases depend on consecutive updates to be taken. -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 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. +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: + @@ -601,7 +604,7 @@ sudo docker compose up -d --remove-orphans * Finally, you can remove any old images if no longer used. -Note that we advice 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 the configuration and bring the deployment up! +Note that we advice 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::[] @@ -612,7 +615,7 @@ Follow these steps to update between production releases: For patch releases only!:: + -- -These commands will stop the deployment, updates ALL images and starts 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. +These commands will stop the deployment, updates all images and starts 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] ---- @@ -637,9 +640,11 @@ For all major and minor releases including from rolling to production:: 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 the configuration! +* 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 that versions might have changed. + From 3cf7804ab46506564a3b1fc33dc20cd60fe4465c Mon Sep 17 00:00:00 2001 From: Martin Mattel Date: Tue, 29 Oct 2024 17:43:20 +0100 Subject: [PATCH 3/4] fix typo --- .../partials/depl-examples/ubuntu-compose/shared-setup.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/partials/depl-examples/ubuntu-compose/shared-setup.adoc b/modules/ROOT/partials/depl-examples/ubuntu-compose/shared-setup.adoc index 2cd2931d..ade32b25 100644 --- a/modules/ROOT/partials/depl-examples/ubuntu-compose/shared-setup.adoc +++ b/modules/ROOT/partials/depl-examples/ubuntu-compose/shared-setup.adoc @@ -304,7 +304,7 @@ 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 fining any first startup issues that need to be solved first. +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 From 5b735fe1f5bbeb32a1950e9e1d28713b822acb27 Mon Sep 17 00:00:00 2001 From: Martin Date: Wed, 30 Oct 2024 07:48:01 +0100 Subject: [PATCH 4/4] Apply suggestions from code review Co-authored-by: Phil Davis --- .../depl-examples/ubuntu-compose/shared-setup.adoc | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/modules/ROOT/partials/depl-examples/ubuntu-compose/shared-setup.adoc b/modules/ROOT/partials/depl-examples/ubuntu-compose/shared-setup.adoc index ade32b25..59730b4d 100644 --- a/modules/ROOT/partials/depl-examples/ubuntu-compose/shared-setup.adoc +++ b/modules/ROOT/partials/depl-examples/ubuntu-compose/shared-setup.adoc @@ -583,7 +583,7 @@ docker volume rm {ocis_wopi}_ocis-config {ocis_wopi}_ocis-data //:version-type: production ifeval::["{version-type}" == "rolling"] -For rolling releases, the following steps are essential to avoid breaking the setup. This is because rolling releases depend on consecutive updates to be taken. +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. @@ -604,7 +604,7 @@ sudo docker compose up -d --remove-orphans * Finally, you can remove any old images if no longer used. -Note that we advice 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. +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::[] @@ -615,7 +615,7 @@ Follow these steps to update between production releases: For patch releases only!:: + -- -These commands will stop the deployment, updates all images and starts 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. +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] ---- @@ -630,7 +630,7 @@ endif::[] === Upgrading -For all major and minor releases including from rolling to production:: +For all major and minor releases including from former rolling to production:: + -- * Stop the deployment with: @@ -646,7 +646,7 @@ sudo docker compose stop * 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 that versions might have changed. +* Re-pull the deployment. This will update all images with any versions that might have changed. + [source,bash] ----