diff --git a/antora.yml b/antora.yml index 7da477b4..63a9ee1a 100644 --- a/antora.yml +++ b/antora.yml @@ -48,7 +48,7 @@ asciidoc: # this is the first part of the name for envvars between major versions that will be added or removed # example for full name: 4.0.0-5.0.0-added.adoc or 4.0.0-5.0.0-removed.adoc - env_var_delta_name: '4.0.0-5.0.0' + env_var_delta_name: '5.0.0-7.0.0' # helm_tab_x will be used to assemble the url (tag) accessing the raw content for helm charts (tag) # note that tab 2 always contains the actual release and tab 3 the former diff --git a/modules/ROOT/pages/depl-examples/bare-metal.adoc b/modules/ROOT/pages/depl-examples/bare-metal.adoc index eaaada12..467d3211 100644 --- a/modules/ROOT/pages/depl-examples/bare-metal.adoc +++ b/modules/ROOT/pages/depl-examples/bare-metal.adoc @@ -73,6 +73,21 @@ Note that this URL must resolve to the server running this installation. === Install and configure the Infinite Scale Binary +[NOTE] +==== +If you have installed Infinite Scale already but want to upgrade it, do the following steps first: + +* xref:stopping-infinite-scale[Stop infinite Scale]: + +You cannot overwrite the binary of a running instance. + +* Make a copy of the existing binary first: ++ +[source,bash,subs="attributes+"] +---- +sudo cp {ocis_bin}/ocis {ocis_bin}/ocis.old +---- +==== + * Download and install the Infinite Scale binary. 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. + [source,bash,subs="attributes+"] diff --git a/modules/ROOT/pages/depl-examples/minimal-bare-metal.adoc b/modules/ROOT/pages/depl-examples/minimal-bare-metal.adoc index 7ab58575..4678c517 100644 --- a/modules/ROOT/pages/depl-examples/minimal-bare-metal.adoc +++ b/modules/ROOT/pages/depl-examples/minimal-bare-metal.adoc @@ -85,6 +85,21 @@ Congratulations, you now have access to your Infinite Scale instance. == Installation +[NOTE] +==== +If you have installed Infinite Scale already but want to upgrade it, do the following steps first: + +* xref:stopping-infinite-scale[Stop infinite Scale]: + +You cannot overwrite the binary of a running instance. + +* 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}`. + -- diff --git a/modules/ROOT/pages/deployment/general/general-info.adoc b/modules/ROOT/pages/deployment/general/general-info.adoc index 01aef11a..03548721 100644 --- a/modules/ROOT/pages/deployment/general/general-info.adoc +++ b/modules/ROOT/pages/deployment/general/general-info.adoc @@ -622,13 +622,15 @@ An admin user will be created when running the `ocis init` command with the foll Login to the webinterface with this admin user and change relevant data according your needs or create new users. As an example to reach out the webinterface use `\https://localhost:9200`. -=== Password Reset for the Admin User +=== Password Reset for IDM Users The admin password can be reset via command line if it has been forgotten and the admin can't enter the webUI anymore. Note that the admin user must already exist which happens if you have xref:deployment/general/ocis-init.adoc[initialized Infinite Scale]. -After running the respective command and entering a new password, the admin can relogin using the new password. +See the command below for details and options. + +After running the respective command and entering a new password, the admin or user can relogin using the new password. -Note that when Infinite Scale gets initialized with xref:deployment/general/ocis-init.adoc[The ocis init Command], an admin password is created and stored in the `ocis.yaml` file. The lifespan of this admin password is up to the point when it either gets changed in the webUI or via the resetpassword command. Any admin password changes are NOT written back to the `ocis.yaml` file nor manual changes to the `admin_password` are considered as a new password. +Note that when Infinite Scale gets initialized with xref:deployment/general/ocis-init.adoc[The ocis init Command], an admin password is created and stored in the `ocis.yaml` file. The lifespan of this admin password is up to the point when it either gets changed in the webUI or via the resetpassword command. Any admin password changes are *NOT* written back to the `ocis.yaml` file nor manual changes to the `admin_password` are considered as a new password. [source,yaml] ---- @@ -657,7 +659,7 @@ When the prerequisite from the note above is fulfilled, you can reset the admin ==== Binary Setup -Run the following command to reset the admin password: +Run the following command to reset the admin password, use `--user-name ` for ordinary users: [source,bash] ---- diff --git a/modules/ROOT/pages/deployment/services/env-var-changes.adoc b/modules/ROOT/pages/deployment/services/env-var-changes.adoc index c71766d2..4298abac 100644 --- a/modules/ROOT/pages/deployment/services/env-var-changes.adoc +++ b/modules/ROOT/pages/deployment/services/env-var-changes.adoc @@ -1,9 +1,9 @@ # Changed Environment Variables in Versions :toc: right -:description: This page contains tables with added and removed environment variables between Infinite Scale version 4.0.0 and 5.0.0. +:description: This page contains tables with added and removed environment variables between Infinite Scale version 5.0.x and 7.0.0. :source_path: {ocis_services_raw_url}{service_url_component}{ocis_services_final_path}adoc/env-var-deltas/ -// https://raw.githubusercontent.com/owncloud/ocis/docs-stable-5.0/services/_includes/adoc/env-var-deltas/ +// https://raw.githubusercontent.com/owncloud/ocis/docs-stable-7.0/services/_includes/adoc/env-var-deltas/ == Introduction @@ -23,4 +23,9 @@ Removed:: -- include::{source_path}{env_var_delta_name}-removed.adoc[] -- +Deprecated:: ++ +-- +include::{source_path}{env_var_delta_name}-deprecated.adoc[] +-- ==== diff --git a/modules/ROOT/pages/deployment/services/s-list/postprocessing.adoc b/modules/ROOT/pages/deployment/services/s-list/postprocessing.adoc index c7923c52..494bb95c 100644 --- a/modules/ROOT/pages/deployment/services/s-list/postprocessing.adoc +++ b/modules/ROOT/pages/deployment/services/s-list/postprocessing.adoc @@ -63,39 +63,73 @@ The backoff behavior as mentioned in the `retry` outcome can be configured using === Resume Post-Processing -If post-processing fails in one step due to an unforeseen error, current uploads will not be retried automatically. A system administrator can instead run CLI commands to retry the failed upload which is a two step process. For details on the `storage-users` command see the xref:{s-path}/storage-users.adoc#manage-unfinished-uploads[Manage Unfinished Uploads] documentation. +[NOTE] +==== +If not noted otherwise, commands with the `restart` option can also use the `resume` option. This changes behaviour slightly. -* First list ongoing upload sessions: +* `restart` + +When restarting an upload, all steps for open items will be restarted, except if otherwise defined. +* `resume` + +When resuming an upload, processing will continue unfinished items from their last completed step. +==== + +If post-processing fails in one step due to an unforeseen error, current uploads will not be resumed automatically. A system administrator can instead run CLI commands to resume the failed upload manually which is at minimum a two step process. + +NOTE: For details on the `storage-users` command which provides many options see the xref:{s-path}/storage-users.adoc#manage-unfinished-uploads[Manage Unfinished Uploads] documentation. + +Depending if you want to restart/resume all or defined failed uploads, different commands are used. + +* First, list ongoing upload sessions to identify possibly failed ones. + +Note that there never can be a clear identification of a failed upload session due to various reasons causing them. You need to apply more critera like free space on disk, a failed service like antivirus etc. to declare an upload as failed. + [source,bash] ---- ocis storage-users uploads sessions ---- -* If you want to restart *all* uploads, just rerun the command with the `--restart` flag: +{empty} + +* *All failed uploads* + +-- +If you want to restart/resume all failed uploads, just rerun the command with the relevant flag. Note that this is the preferred command to handle failed processing steps: + [source,bash] ---- -ocis storage-users uploads sessions --restart +ocis storage-users uploads sessions --resume ---- +{empty} +-- -* If you want to restart *only one* upload, use the postprocessing restart command with the ID selected: +* *Particular failed uploads* + +Use the `postprocessing` command to resume defined failed uploads. For postprocessing steps, the default is to resume . Note that at the moment, `resume` is an alias for `restart` to keep old functionality. `restart` is subject of change and will most likely be removed in a later version. + +** *Defined by ID* + +-- +If you want to resume only a specific upload, use the postprocessing resume command with the ID selected: + [source,bash] ---- -ocis postprocessing restart -u +ocis postprocessing resume -u ---- +{empty} +-- -Alternatively, instead of starting one specific upload, a system admin can also restart all uploads that are currently in a specific step. +** *Defined by step* ++ +-- +Alternatively, instead of restarting one specific upload, a system admin can also resume all uploads that are currently in a specific step. Examples: [source,bash] ---- -ocis postprocessing restart # Restarts all uploads where postprocessing is finished, but upload is not finished. -ocis postprocessing restart -s "finished" # Equivalent to the above. -ocis postprocessing restart -s "virusscan" # Restart all uploads currently in virusscan step. +ocis postprocessing resume # Resumes all uploads where postprocessing is finished, but upload is not finished. +ocis postprocessing resume -s "finished" # Equivalent to the above. +ocis postprocessing resume -s "virusscan" # Resume all uploads currently in virusscan step. ---- +-- == Storing diff --git a/modules/ROOT/pages/deployment/services/s-list/storage-users.adoc b/modules/ROOT/pages/deployment/services/s-list/storage-users.adoc index f8916378..76cb63ad 100644 --- a/modules/ROOT/pages/deployment/services/s-list/storage-users.adoc +++ b/modules/ROOT/pages/deployment/services/s-list/storage-users.adoc @@ -23,7 +23,7 @@ IMPORTANT: The graceful shutdown period is only applicable if the `storage-users When hard-stopping Infinite Scale, for example with the `kill ` command (SIGKILL), it is possible and likely that not all data from the decomposedfs (metadata) has been written to the storage which may result in an inconsistent decomposedfs. When gracefully shutting down Infinite Scale, using a command like SIGTERM, the process will no longer accept any write requests from _other_ services and will try to write the internal open requests which can take an undefined duration based on many factors. To mitigate that situation, the following things have been implemented: -* With the value of the environment variable `STORAGE_USERS_GRACEFUL_SHUTDOWN_TIMEOUT`, the `storage-users` service will delay its shutdown giving it time to finalize writing necessary data. This delay can be necessary if there is a lot of data to be saved and/or if storage access/thruput is slow. In such a case you would receive an error log entry informing you that not all data could be saved in time. To prevent such occurrences, you must increase the default value. +* With the value of the environment variable `STORAGE_USERS_GRACEFUL_SHUTDOWN_TIMEOUT`, the `storage-users` service will delay its shutdown giving it time to finalize writing necessary data. This delay can be necessary if there is a lot of data to be saved and/or if storage access/throughput is slow. In such a case you would receive an error log entry informing you that not all data could be saved in time. To prevent such occurrences, you must increase the default value. * If a shutdown error has been logged, the command-line maintenance tool xref:maintenance/commands/commands.adoc#inspect-and-manipulate-node-metadata[Inspect and Manipulate Node Metadata] can help to fix the issue. Please contact support for details. @@ -69,22 +69,30 @@ ocis storage-users uploads ---- COMMANDS: sessions Print a list of upload sessions - clean Clean up leftovers from expired uploads (deprecated, do not use it) - list Print a list of all incomplete uploads (deprecated, do not use it) ---- -- ==== Sessions command -The `sessions` command is the entry point for listing, restarting and cleaning unfinished uploads. +The `sessions` command is the entry point for listing, restarting/resuming and cleaning unfinished uploads. + +NOTE: There can never be a clear identification of a failed upload session due to various reasons causing them. You need to apply more critera like free space on disk, a failed service like antivirus etc. to declare an upload as failed. + +[NOTE] +==== +If not noted otherwise, the `restart` option can also be replaced the `resume` option. This changes behaviour slightly. + +* `restart` + +When restarting an upload, all steps for open items will be restarted, except if otherwise defined. +* `resume` + +When resuming an upload, processing will continue unfinished items from their last completed step. +==== [source,bash] ---- ocis storage-users uploads sessions ---- -Note, though possible, do not use the deprecated upload commands listed above. Their function has been embedded in the session command as command options. - [source,plaintext] ---- NAME: @@ -100,6 +108,7 @@ OPTIONS: --has-virus filter sessions by virus scan result (default: unset) --json output as json (default: false) --restart send restart event for all listed sessions (default: false) + --resume send resume event for all listed sessions (default: false) --clean remove uploads (default: false) --help, -h show help ---- @@ -165,7 +174,7 @@ ocis storage-users uploads sessions --expired=false --processing=false | |=== -The sessions command can also clear and restart uploads. The output is the same as if run without the `--clean` or `--restart` flag. Note that it is recommended to run the command first without the `--clean` (`--processing`) flag to double check which uploads get cleaned (restarted). +The sessions command can also clear and restart/resume uploads. The output is the same as if run without the `--clean` or `--restart/--resume` option. Note that it is recommended to run the command first without the `--clean` (`--processing`) option to double check which uploads would get cleaned (restarted/resumed). .Cleans all expired uploads regardless of processing and virus state. [source,bash] @@ -175,13 +184,13 @@ ocis storage-users uploads sessions \ --clean ---- -.Restarts all uploads that are processing and are not virus infected +.Resume all uploads that are currently processing and are not virus infected [source,bash] ---- ocis storage-users uploads sessions \ --processing=false \ --has-virus=false \ - --restart + --resume ---- === Manage Trash-Bin Items diff --git a/modules/ROOT/pages/maintenance/commands/changed-cli.adoc b/modules/ROOT/pages/maintenance/commands/changed-cli.adoc new file mode 100644 index 00000000..fcbfadfe --- /dev/null +++ b/modules/ROOT/pages/maintenance/commands/changed-cli.adoc @@ -0,0 +1,37 @@ += Changed or Added CLI Commands +:toc: right +:description: This page contains a list with added, changed or removed CLI commands between Infinite Scale version 5.0.x and 7.0.0. + +== Introduction + +{description} + +== Affected CLI Commands + +See the link for a detailed description of the respective CLI command if available. + +* xref:maintenance/commands/commands.adoc#manage-expired-uploads[Manage Expired Uploads] + +The `ocis storage-users uploads sessions --restart` command got an alternative `--resume` option. + +Resume can be used in the same way as restart with a slighly different behavior change. + +* xref:maintenance/commands/commands.adoc#purge-expired-space-trash-bin-items[Purge Expired Space Trash-Bin Items] + +The `ocis storage-users uploads` got restructured. + +The deprecated `list` option is now removed, the `clean` option is now part of the `sessions command`. + +* xref:maintenance/commands/commands.adoc#resume-post-processing[Resume Post-Processing] + +The `ocis postprocessing restart` command got an alternative `resume` option. + +Resume can be used in the same way as restart with a slighly different behavior change. + +* xref:maintenance/commands/commands.adoc#reset-password-for-idm-users[Reset Password for IDM Users] + +The `ocis idm resetpassword` can now specify the user name via the `--user-name` (`-u`) flag. + +* xref:maintenance/commands/commands.adoc#revisions-cleanup[Revisions Cleanup] + +The `ocis revisions purge` command allows removing revisions of files in the storage. Note that this command has also been backported to version 5 available with its latest release. + +* xref:maintenance/commands/commands.adoc#service-health[Service Health] + +A `health` command has been added to each service: `ocis health`. + +* xref:maintenance/commands/commands.adoc#trash-purge[Trash Purge]. + +The `ocis trash purge-empty-dirs` command allows removing empty folders from the trashbin. + +* The `ocis graph list-unified-roles` command simplifies the process of finding out which UID belongs to which role. Note that this command is described in the https://github.com/owncloud/ocis/tree/master/ocis#list-unified-roles[ocis repository, window=_blank] and has been added for completeness only. diff --git a/modules/ROOT/pages/maintenance/commands/commands.adoc b/modules/ROOT/pages/maintenance/commands/commands.adoc index efa90662..be42fd08 100644 --- a/modules/ROOT/pages/maintenance/commands/commands.adoc +++ b/modules/ROOT/pages/maintenance/commands/commands.adoc @@ -16,6 +16,10 @@ This could happen if services are developed which are not shipped as part of the single binary. ==== +== Changed CLI Commands + +CLI commands can get added, changed or removed between versions. See the xref:maintenance/commands/changed-cli.adoc[Changed or Added CLI Commands] document for details. + == Offline Commands Compared to online commands that need to be issued during operation of Infinite Scale, offline commands can, and somtimes must only be issued if Infinite Scale is not running. @@ -40,22 +44,37 @@ Infinite Scale provides a xref:maintenance/commands/backup-consistency.adoc[CLI NOTE: This command MUST only be issued when Infinite Scale is offline and no services are running. This command will report false positives when issued during normal operation. +=== Reset Password for IDM Users + +If you need to reset the password for the admin or a user in the xref:{s-path}/idm.adoc[idm] service from the command line, follow the xref:deployment/general/general-info.adoc#password-reset-for-idm-users[Password Reset for IDM Users]. + === Revisions Cleanup Infinite Scale provides a xref:maintenance/commands/revisions-cleanup.adoc[CLI command] which allows removing revisions of files in the storage. -=== Trash Purge +=== Service Health -Infinite Scale provides a xref:maintenance/commands/trash.adoc[CLI command] with which you can remove empty folders from the trashbin. +Infinite Scale provides a xref:maintenance/commands/service-health.adoc[CLI command] checking the health of a service. -=== Reset the Admin Password +=== Trash Purge -If you need to reset the admin password from the command line, follow the xref:deployment/general/general-info.adoc#password-reset-for-the-admin-user[Password Reset for the Admin User]. +Infinite Scale provides a xref:maintenance/commands/trash.adoc[CLI command] with which you can remove empty folders from the trashbin. == Online Only Commands Compared to offline commands that can be issued when Infinite Scale is shut down, online commands must be issued when Infinite Scale and the respective service(es) are running. +=== Inspect and Manipulate Node Metadata + +Infinite Scale provides a xref:maintenance/commands/node-metadata.adoc[CLI command] with which you can inspect and manipulate node metadata. + +WARNING: Use this command with absolute care. It is not intended to play around and should only be used on request and under supervision of ownCloud support. + +=== Inspect and Repair Node Tree Sizes + +Infinite Scale provides a xref:maintenance/commands/node-tree-size.adoc[CLI command] with which you can inspect and repair node tree sizes. This command can be necessary in very rare cases where spaces or files are shown in the Web UI with a size not matching reality. For the repair option Infinite Scale must be shut down. + +WARNING: Use this command with absolute care. It is not intended to play around and should only be used on request and under supervision of ownCloud support. === Manage Expired Uploads Compared to unfinished uploads which are handled by the system, managing expired uploads can be a necessity as those files can pile up, blocking storage resources and need to be removed by command regularly. See the xref:{s-path}/storage-users.adoc#manage-unfinished-uploads[Manage Unfinished Uploads] section at the _Storage Users_ service for details. @@ -68,30 +87,19 @@ This command is about purging old trash-bin items of `project` spaces (spaces th In rare circumstances, it can be necessary to initiate indexing manually for a given space a user has access to or all spaces. Though the search service handles exception cases automatically, it can happen that the search service was not able to complete indexing due to a dirty shut-down of the service or because of a bug. Re-indexing should *only* be run on explicit request and supervision by ownCloud support. See the xref:{s-path}/search.adoc#manually-trigger-re-indexing-spaces[Manually Trigger Re-Indexing Spaces] section at the _Search_ service for details. -=== Resume Post-Processing - -If post-processing fails in one step due to an unforeseen error, current uploads will not be retried automatically. A system administrator can instead run a xref:{s-path}/postprocessing.adoc#cli-commands[CLI Commands] to retry the failed upload. - -=== Inspect and Manipulate Node Metadata +=== Repair and Migrate jsoncs3 Indexes -Infinite Scale provides a xref:maintenance/commands/node-metadata.adoc[CLI command] with which you can inspect and manipulate node metadata. +A xref:maintenance/commands/rebuild-jsoncs3-indexes.adoc[CLI command] is provided to repair and migrate jsoncs3 indexes. In rare circumstances the data for shares from the "Shared with others" and "Shared with me" index can be corrupted though no data is lost. When using this command, you can recreate that index and migrate it to a new layout which fixes the issue. WARNING: Use this command with absolute care. It is not intended to play around and should only be used on request and under supervision of ownCloud support. -=== Inspect and Repair Node Tree Sizes +=== Resume Post-Processing -Infinite Scale provides a xref:maintenance/commands/node-tree-size.adoc[CLI command] with which you can inspect and repair node tree sizes. This command can be necessary in very rare cases where spaces or files are shown in the Web UI with a size not matching reality. For the repair option Infinite Scale must be shut down. +If post-processing fails in one step due to an unforeseen error, current uploads will not be retried automatically. A system administrator can instead run a xref:{s-path}/postprocessing.adoc#cli-commands[CLI Commands] to retry the failed upload. -WARNING: Use this command with absolute care. It is not intended to play around and should only be used on request and under supervision of ownCloud support. === Roll Back / Roll Forward Decomposedfs Migrations A xref:maintenance/commands/rolling-back-and-forward.adoc[CLI command] is provided to roll back or roll forward a decomposedfs migration. WARNING: Use this command with absolute care. It is not intended to play around and should only be used on request and under supervision of ownCloud support. - -=== Repair and Migrate jsoncs3 Indexes - -A xref:maintenance/commands/rebuild-jsoncs3-indexes.adoc[CLI command] is provided to repair and migrate jsoncs3 indexes. In rare circumstances the data for shares from the "Shared with others" and "Shared with me" index can be corrupted though no data is lost. When using this command, you can recreate that index and migrate it to a new layout which fixes the issue. - -WARNING: Use this command with absolute care. It is not intended to play around and should only be used on request and under supervision of ownCloud support. diff --git a/modules/ROOT/pages/maintenance/commands/service-health.adoc b/modules/ROOT/pages/maintenance/commands/service-health.adoc new file mode 100644 index 00000000..bad425ed --- /dev/null +++ b/modules/ROOT/pages/maintenance/commands/service-health.adoc @@ -0,0 +1,32 @@ += Service Health + +The service health CLI command allows checking the health status of a service. If there are no issues found, nothing health related will get printed. + +[source,bash] +---- +ocis health +---- + +Examples:: ++ +-- +* The `collaboration` service has been started but not configured and is therefore not in a healthy state: ++ +[source,bash] +---- +ocis collaboration health + +The WOPI secret has not been set properly in your config for collaboration. Make sure your /root/.ocis/config config contains the proper values (e.g. by using 'ocis init --diff' and applying the patch or setting a value manually in the config/corresponding environment variable). +---- + +* The `antivirus` service has not been started, the health check responds accordingly. ++ +[source,bash] +---- +ocis antivirus health + +{"level":"fatal","service":"antivirus","error":"Get \"http://127.0.0.1:9277/healthz\": dial tcp 127.0.0.1:9277: connect: connection refused","time":"2024-10-28T17:47:54+01:00","message":"Failed to request health check"} +---- +-- + + diff --git a/modules/ROOT/pages/maintenance/commands/trash.adoc b/modules/ROOT/pages/maintenance/commands/trash.adoc index 9d0bd5cd..565f43f9 100644 --- a/modules/ROOT/pages/maintenance/commands/trash.adoc +++ b/modules/ROOT/pages/maintenance/commands/trash.adoc @@ -1,6 +1,6 @@ = Trash CLI -The trash cli command allows removing empty folders from the trashbin. This should be used to speed up trash bin operations. +The trash CLI command allows removing empty folders from the trashbin. This should be used to speed up trash bin operations. [source,bash] ---- diff --git a/modules/ROOT/pages/migration/upgrading-ocis.adoc b/modules/ROOT/pages/migration/upgrading-ocis.adoc index f52a4610..300c0ada 100644 --- a/modules/ROOT/pages/migration/upgrading-ocis.adoc +++ b/modules/ROOT/pages/migration/upgrading-ocis.adoc @@ -1,7 +1,7 @@ = Upgrading Infinite Scale :toc: right :toclevels: 2 -:description: When upgrading Infinite Scale, migration steps may be required. This document guides thru the necessary steps based on the versions used. +:description: When upgrading Infinite Scale, migration steps may be required. This document guides you through the necessary steps based on the versions used. include::partial$multi-location/compose-version.adoc[] @@ -11,14 +11,30 @@ include::partial$multi-location/compose-version.adoc[] NOTE: For any Infinite Scale version to upgrade to, see {ocis-downloadpage-url}/stable/?sort=time&order=desc[download.owncloud.com,window=_blank] or {docker_ocis_prod_url}[Infinite Scale image] to get the right version. -IMPORTANT: Before starting any upgrade, make a xref:maintenance/b-r/backup.adoc[backup] first. +IMPORTANT: Before starting any upgrade, first make a xref:maintenance/b-r/backup.adoc[backup]. -IMPORTANT: If not explicitly mentioned, any upgrade is forward only and a backstep is neither supported nor recommended and will most likely break the instance. +IMPORTANT: If not explicitly mentioned, any upgrade is forward only and a step back is neither supported nor recommended and will most likely break the instance. IMPORTANT: When upgrading from an older release to the desired one, *ALL* upgrade steps from each release must be taken in order and none can be skipped. IMPORTANT: When upgrading from an older release to the desired one, mandatory configuration settings may have been added or removed. To see the changes required, you can run `ocis init --diff` after upgrading but before finally starting. For more details, see the xref:deployment/general/ocis-init.adoc[ocis init command] description. +== Version 5.0.x to 7.0.0 + +=== Notable Changes Requiring Manual Intervention + +* Resharing has finally been removed. +* The maintenance command `ocis storage-users uploads list` has been removed. Its functionality is now part of other options. + +=== Breaking Changes Requiring Manual Intervention + +* All environment variables that were marked for deprecation in Infinite Scale release 5.0.x have finally been removed. +* A new mandatory Infinite Scale config setting for the `activitylog` service named `service_account` has been added. If this config is not set, `activities` will not be recorded. + +=== Upgrade Steps + +For a detailed description of the steps to upgrade, see the xref:migration/upgrading_5.0.x_7.0.0.adoc[Upgrading from 5.0.x to 7.0.0] documentation. Note that this document also contains references to added/changed/removed CLI commands and environment variables. + == Version 4.0.0 to 5.0.0 === Notable Changes Requiring Manual Intervention diff --git a/modules/ROOT/pages/migration/upgrading_5.0.x_7.0.0.adoc b/modules/ROOT/pages/migration/upgrading_5.0.x_7.0.0.adoc new file mode 100644 index 00000000..8b10574a --- /dev/null +++ b/modules/ROOT/pages/migration/upgrading_5.0.x_7.0.0.adoc @@ -0,0 +1,243 @@ += Upgrading from 5.0.x to 7.0.0 +:toc: right +:description: This document describes the necessary steps when upgrading Infinite Scale from release 5.0.x to 7.0.0. + +include::partial$multi-location/compose-version.adoc[] + +== Introduction + +{description} + +IMPORTANT: Read the important notes in the xref:migration/upgrading-ocis.adoc#introduction[Upgrading Infinite Scale] documentation before you start. + +IMPORTANT: Check below, if you are affected by breaking changes and prepare all steps mentioned before you start the upgrade. + +== Upgrade Steps + +. 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 + +:sectnums: + +== Download and Install Infinite Scale + +Download and install Infinite Scale via: + +=== Binary + +Follow the xref:depl-examples/minimal-bare-metal.adoc#installation[Installation] section of the bare metal deployment example. + +=== Image Based Deployments + +* Issue the following command to download the new image: ++ +[source,bash,subs="attributes+"] +---- +docker pull owncloud/ocis:7.0.0 +---- + +== Shut Down the Infinite Scale Instance + +Depending how you deployed Infinite Scale, you need to shut it down differently. + +* *Binary* + +For binary deployments, do a graceful shutdown as described in xref:depl-examples/minimal-bare-metal.adoc#stopping-infinite-scale[Stopping Infinite Scale]. + +* *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]. + +* *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]. + +* *Any other image based deployment* + +For any other image based deployment, shut down Infinite Scale according the vendors deployment description. + +== Backup of 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. + +== Reconfigure the Deployment + +Reconfigure the deployment to use the new image: + +* 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 + +* All environment variables that were marked for deprecation in Infinite Scale release 5.0.x have finally been removed. +* A new mandatory Infinite Scale config setting for the `activitylog` service named `service_account` has been added. +* A new mandatory Infinite Scale config setting for the `collaboration` service named `secret` has been added. +* Deployment examples based on one of the `Ubuntu with Docker Compose` deployments have been updated/upgraded. + +=== How to Identify if You Are Affected + +* 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. + +* The xref:{s-path}/collaboration.adoc[collaboration] service has been added. Though this service needs to be started manually, it requires a secret (preferred a random UUID string) when started. For safety reasons on a fresh install, this secret is added when running the `ocis init` command and should be added on upgrades. The used upgrade procedure provides a secret if not present in the config. Note that the secret can be overwritten in the config or with an environment variable if necessary. + +** If you have used web office document servers such as Collabora, ONLYOFFICE or Microsoft using the WOPI protocol with the external https://github.com/cs3org/wopiserver[cs3org/wopi] server, we highly recommend switching to the xref:{s-path}/collaboration.adoc[collaboration] service which requires deployment reconfiguration which is a breaking change. Though the environment variables from the xref:{s-path}/app-provider.adoc[app-provider] service formerly used for web office document deployments are currently not deprecated, the are a candidate for future deprecations. + +* If you have used a rolling release and deployed web office document servers like the xref:depl-examples/ubuntu-compose/ubuntu-compose-prod.adoc[Local Production Setup] or the xref:depl-examples/ubuntu-compose/ubuntu-compose-hetzner.adoc[Deployment on Hetzner] deployment example, you should follow the reconfiguration section below because the deployment files have been updated/upgraded. + +=== 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. +* 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*: + +. Get the config diff via command +. Apply the diff created +. Start Infinite Scale as usual + +See the next section for *details* how to update the config settings. + +=== Update Config Settings + +Run the `ocis init --diff` command: + +Because this will now run the new ocis code, it will create two files in the config directory 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..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 (except an earlier `ocis.config.patch`). It may ask questions though. 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. + +NOTE: If the `patch` command is not present in your deployment, you must apply the changes provided by the patch file manually to the `ocis.yaml` file. + +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*: ++ +-- +[source,bash] +---- +ocis init --diff +---- +Change into the Infinite Scale config directory located at `$HOME/.ocis/config/` and apply the changes with: + +[source,bash] +---- +patch < ocis.config.patch +---- +-- + +{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! + +[source,bash] +---- +sudo docker run \ + --rm -it \ + --entrypoint sh \ + --mount type=bind,source=$HOME/ocis/ocis-config,target=/etc/ocis \ + owncloud/ocis:7.0.0 +---- + +Then, when the containers shell is available, type: + +[source,bash] +---- +ocis init --diff +---- +Change into the containers config directory `/etc/ocis` and apply the changes with: + +[source,bash] +---- +patch < ocis.config.patch +---- +-- + +{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. + +[source,bash] +---- +sudo docker run \ + --rm -it \ + --entrypoint sh \ + -v ocis-config:/etc/ocis \ + owncloud/ocis:7.0.0 +---- + +Then, when the containers shell is available, type: + +[source,bash] +---- +ocis init --diff +---- +Change into the containers config directory `/etc/ocis` and apply the changes with: + +[source,bash] +---- +patch < ocis.config.patch +---- +-- + +{empty} + +* *Any Other Image Based Deployment*: ++ +-- +Use one of the Docker based examples from above and derive from. +-- + +=== Reconfigure web Office Document Deployments + +With the introduction of the xref:{s-path}/collaboration.adoc[collaboration] service, the external https://github.com/cs3org/wopiserver[cs3org/wopi] server is no longer required. Deployments using the external cs3org/wopi server should upgrade. This upgrade is a breaking change, but if you have used one of the `Ubuntu with Docker Compose` deployment examples, a re-deployment is quite easy. If you have setup your own deployment not based on the examples, you can derive from the changes based on the deployment files. + +The following steps are based on the xref:depl-examples/ubuntu-compose/ubuntu-compose-prod.adoc[Local Production Setup] deployment example. The steps are identical for the xref:depl-examples/ubuntu-compose/ubuntu-compose-hetzner.adoc[Deployment on Hetzner]. + +* Backup the the base folder containing the existing deployment example by renaming it. + +You will need your configuration details with the new example. + +* Follow the xref:depl-examples/ubuntu-compose/ubuntu-compose-prod.adoc#download-and-transfer-the-example[Download and Transfer the Example] to get the new deployment and extract it as described in the following section of the guide. + +* Reconfigure the new `.env` file based on settings made in the `.env` file of the backup. + +== Start Infinite Scale + +When you have finished upgrading, you now can start Infinite Scale as ususal. + +For any deployment used, you now can delete/remove old binaries or images/containers. + +:sectnums!: + +== Changed or Added CLI Commands + +See the xref:maintenance/commands/changed-cli.adoc[Changed or Added CLI Commands] document for details. 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 59730b4d..2cc1d626 100644 --- a/modules/ROOT/partials/depl-examples/ubuntu-compose/shared-setup.adoc +++ b/modules/ROOT/partials/depl-examples/ubuntu-compose/shared-setup.adoc @@ -502,13 +502,13 @@ Use the container ID identified in the following command to read the Infinite Sc docker logs 2>&1 | less ---- -The output prints the log from the beginning. As first entry, the initial admin password set during first startup is shown. You can scroll thru the log using the keyboard, see the https://wiki.ubuntuusers.de/less/[less description] for more details. +The output prints the log from the beginning. As first entry, the initial admin password set during first startup is shown. You can scroll through the log using the keyboard, see the https://wiki.ubuntuusers.de/less/[less description] for more details. If no password can be identified, you must reset the admin password via the command line as described below. === Command Line Password Reset -To change the admin password from the command line, which you can do at any time, follow the guide described in xref:deployment/general/general-info.adoc#password-reset-for-the-admin-user[Password Reset for the Admin User]. +To change the admin password from the command line, which you can do at any time, follow the guide described in xref:deployment/general/general-info.adoc#password-reset-for-idm-users[Password Reset for IDM Users]. == Volume Migration