Migration and Update Guide for 5 to 7

[mmattel]

References:
#1028 (Migration and Update Guide for 5 to 7)
#1034 (CLI: health check for services (to be added in maintenance commands)
#1038 (Update the compose examples to be ready to upgrade for the next release)
owncloud/ocis#10439 (Restart Postprocessing Properly) (CLI change)
owncloud/ocis#10499 ([docs-only] Create envvar delta files after v5 to master (v7.0.0))
owncloud/ocis#10566 ([docs-only] Improve error messages for health command output)

Updates the migration, update and envvar changes documentation.

Currently visible on staging

• Added/Removed envvar .adoc table files in ocis/docs/services/general-info/envvar-deltas
• Added/Changed/Removed CLI commands
• Config changes when running ocis init --diff
• Breaking changes
  activitylog: service_account: + value in ocis.yaml (via ocis init --diff)
  collaboration: wopi.secret + value in ocis.yaml (via ocis init --diff)

IMPORTANT
These changes also require a final docs branching where we reference to versioned ocis content that MUST be provided to make this final. Some things get automatically referenced with branching pointing to the correct ressources included.

[ScharfViktor]

step https://doc.staging.owncloud.com/ocis/next/migration/upgrading_5.0.x_7.0.0.html#update-config-settings for docker doesn't work because patch command is currently missing in the ocis docker image

[mmattel]

for docker doesn't work because patch command is currently missing

A commit has been added with a note what to do if the patch command is missing

[jnweiger]

Making a copy in this way does not help. the original binary file is still locked for swapping by the kernel.

I'd prefer to move away the running binary - then we can add a new version with the original name.
E.g. the following commands can be done without stopping ocis:

  wget -P /usr/local/bin https://download.owncloud.com/ocis/ocis/testing/7.0.0-rc.1/ocis-7.0.0-rc.1-linux-amd64
  chmod a+x /usr/local/bin/ocis-7.0.0-rc.1-linux-amd64
  mv /usr/local/bin/ocis /usr/local/bin/ocis-5.0.8      # it can happily continue to run under this name.
  ln -s ocis-7.0.0-rc.1-linux-amd64 /usr/local/bin/ocis

  ocis version --skip-services
    Version: 7.0.0-rc.1
    Compiled: 2024-11-07 00:00:00 +0000 UTC

The symlink is used here to document the versions, active and inactive.
(A simpler sequence - with a longer absence - would just use wget -O after mv.)

[mmattel]

This procedure is a good idea, if that works - needs testing, I like it.
With that, we can easily switch versions and keep track of original naming.

[jnweiger]

Works fine -- for me 🤷‍♂️ at least.
I simply avoid the ETXTBSY overwrite by moving the old binary away. That works, because a busy text file is about the inode of the file, not the name of the file (kernel only cares about inodes here).

Symlinks sometimes cause confusion; but here it looks smooth, and I could not think of anything that would break.

(All this is still not an atomic upgrade. The technically best approach is to use a hardlink and a rename system call.)