Skip to content

Commit

Permalink
numbered sections (finished)
Browse files Browse the repository at this point in the history
  • Loading branch information
mmattel committed Nov 8, 2024
1 parent fdb8898 commit 060f321
Show file tree
Hide file tree
Showing 2 changed files with 77 additions and 46 deletions.
11 changes: 11 additions & 0 deletions modules/ROOT/pages/depl-examples/minimal-bare-metal.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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}`.
+
--
Expand Down
112 changes: 66 additions & 46 deletions modules/ROOT/pages/migration/upgrading_5.0.x_7.0.0.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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

Expand All @@ -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]
Expand All @@ -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!
Expand All @@ -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.
Expand All @@ -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
Expand Down

0 comments on commit 060f321

Please sign in to comment.