diff --git a/content/ocis/8.1/modules/admin/pages/deployment/services/env-var-changes.adoc b/content/ocis/8.1/modules/admin/pages/deployment/services/env-var-changes.adoc index ed8ce2a..c1fd0b2 100644 --- a/content/ocis/8.1/modules/admin/pages/deployment/services/env-var-changes.adoc +++ b/content/ocis/8.1/modules/admin/pages/deployment/services/env-var-changes.adoc @@ -1,6 +1,6 @@ # Changed Environment Variables in Versions :toc: right -:description: This page contains tables with added and removed environment variables between Infinite Scale version 7.3.0 and 8.0.0. +:description: This page contains tables with added and removed environment variables between Infinite Scale version 8.0.0 and 8.1.0. :page-aliases: ROOT:deployment/services/env-var-changes.adoc :source_path: {ocis_services_raw_url}{service_url_component}{ocis_services_env_var_deltas_path} @@ -9,9 +9,9 @@ to be set in antora.yml ocis_services_raw_url: https://raw.githubusercontent.com/owncloud/ocis/ -service_url_component: docs || docs-stable-8.0 +service_url_component: docs || docs-stable-8.1 ocis_services_env_var_deltas_path: /services/general-info/envvars/env-var-deltas/ -env_var_delta_name: 7.3.0-8.0.0 +env_var_delta_name: 8.0.0-8.1.0 //// == Introduction diff --git a/content/ocis/8.1/modules/admin/pages/deployment/services/ports-used.adoc b/content/ocis/8.1/modules/admin/pages/deployment/services/ports-used.adoc index 37e182b..5d20ff9 100644 --- a/content/ocis/8.1/modules/admin/pages/deployment/services/ports-used.adoc +++ b/content/ocis/8.1/modules/admin/pages/deployment/services/ports-used.adoc @@ -60,6 +60,7 @@ The following port ranges are used by services: | 9260-9264 | xref:{s-path}/clientlog.adoc[clientlog] | 9270-9274 | xref:{s-path}/eventhistory.adoc[eventhistory] | 9280-9284 | xref:{s-path}/ocm.adoc[ocm] +| 9285-9289 | xref:{s-path}/storage-users.adoc[storage-users (vault)] | 9300-9304 | xref:{s-path}/collaboration.adoc[collaboration] | 9350-9354 | xref:{s-path}/ocdav.adoc[ocdav] |=== diff --git a/content/ocis/8.1/modules/admin/pages/deployment/services/s-list/storage-users.adoc b/content/ocis/8.1/modules/admin/pages/deployment/services/s-list/storage-users.adoc index a566526..e54ecf6 100644 --- a/content/ocis/8.1/modules/admin/pages/deployment/services/s-list/storage-users.adoc +++ b/content/ocis/8.1/modules/admin/pages/deployment/services/s-list/storage-users.adoc @@ -331,6 +331,67 @@ ocis storage-users trash-bin restore [command options] ['spaceID' required] ['it See the xref:deployment/storage/general-considerations.adoc#resource-optimisation[General Storage Considerations and Settings] documentation for details about configuring the `STORAGE_USERS_OCIS_MAX_CONCURRENCY` environment variable. +== Vault Mode + +The `storage-users` service can be special configured to run as additional service providing vault mode. + +Vault mode provides dedicated vault storage that is stored separately and can be protected by multi-factor authentication (MFA). Vault resources are isolated from the default user storage and have their own search function, sharing options and workspaces, while public links are explicitly disallow + +=== Configuration + +Create a `storage-users-vault` service:: ++ +-- +The following environment variables must be set in order to define an instance of the `storage-users` service as a vault: + +[source,.env] +---- +STORAGE_USERS_SERVICE_NAME: storage-users-vault +STORAGE_USERS_GRPC_ADDR: storage-users-vault:9285 +STORAGE_USERS_HTTP_ADDR: storage-users-vault:9286 +STORAGE_USERS_DATA_SERVER_URL: http://storage-users-vault:9286/data +STORAGE_USERS_DEBUG_ADDR: storage-users-vault:9287 +STORAGE_USERS_OCIS_ROOT: /var/lib/ocis/storage/users-vault +STORAGE_USERS_EVENTS_CONSUMER_GROUP: vault-dcfs +---- + +[IMPORTANT] +==== +Additionally to the environment variables shown above and for the time being, caching cannot use the shared global environment variable `OCIS_CACHE_STORE_NODES`, as described in the xref:caching[Caching] section. For a vault-instance, you must define for caching either `memory` or `noop`. The affected environment variables to set the cache are: + +* `STORAGE_USERS_FILEMETADATA_CACHE_STORE` +* `STORAGE_USERS_ID_CACHE_STORE` +==== +-- + +Configure instance communication:: ++ +-- +These environment variables complete the configuration of the service instance. The example values for these environment variables are taken from the xref:depl-examples/ubuntu-compose/ubuntu-compose-prod.adoc[Local Production Setup] deployment example. To allow inter-service communication, they need to match the main configuration of the Infinite Scale instance. + +[source,.env] +---- +OCIS_GATEWAY_GRPC_ADDR: ocis:9142 +OCIS_EVENTS_ENDPOINT: ocis:9233 +STORAGE_USERS_xxx_CACHE_STORE: 'memory' +MICRO_REGISTRY_ADDRESS: ocis:9233 +---- +-- + +Complete the configuration:: ++ +-- +With the above configuration creating a `storage-users-vault` instance, you can now set the following environment variables. These envvars are only effective if the `storage-users` service is configured vault. + +The following environment variables can be used to make further configuration changes: + +* `OCIS_ENABLE_VAULT_MODE: true` + +Enable the vault mode in a OCIS. + +* `OCIS_MFA_ENABLED: true` + +Enable multi-factor authentication (MFA) for the use with vault. +-- + == Caching // renders dependent on is_cache or is_store diff --git a/content/ocis/8.1/modules/admin/pages/maintenance/commands/changed-cli.adoc b/content/ocis/8.1/modules/admin/pages/maintenance/commands/changed-cli.adoc index d74ecf1..f20fa06 100644 --- a/content/ocis/8.1/modules/admin/pages/maintenance/commands/changed-cli.adoc +++ b/content/ocis/8.1/modules/admin/pages/maintenance/commands/changed-cli.adoc @@ -1,6 +1,6 @@ = Changed or Added CLI Commands :toc: right -:description: This page contains a list with added, changed or removed CLI commands between Infinite Scale version 7.3.0 and 8.0.0. +:description: This page contains a list with added, changed or removed CLI commands between Infinite Scale version 8.0.0 and 8.1.0. :page-aliases: ROOT:maintenance/b-r/changed-cli.adoc == Introduction @@ -13,8 +13,5 @@ See the link for a detailed description of the respective CLI command if available. -* xref:maintenance/commands/commands.adoc#move-stuck-uploads[Move Stuck Uploads] + -This CLI command has been added to remedy the issue when Infinite Scale metadata may become stuck in some cases of saturated disk usage. - -* xref:maintenance/commands/commands.adoc#cleanup-orphaned-grants[Cleanup Orphaned Grants] + -This CLI command has been added to cleanup orphaned grants when a share has been deleted but the removal process is not completed successfully. +* xref:maintenance/commands/commands.adoc#verify-and-inspect-blobstore[Verify and Inspect a Blobstore] + +This CLI command has been added to verify and inspect the configured Blobstore without requiring direct access to the underlying storage system. diff --git a/content/ocis/8.1/modules/admin/pages/maintenance/commands/commands.adoc b/content/ocis/8.1/modules/admin/pages/maintenance/commands/commands.adoc index 9828e3d..1ae3141 100644 --- a/content/ocis/8.1/modules/admin/pages/maintenance/commands/commands.adoc +++ b/content/ocis/8.1/modules/admin/pages/maintenance/commands/commands.adoc @@ -124,3 +124,7 @@ WARNING: Use this command with absolute care. It is not intended to play around === Sending Grouped Emails This command is about sending emails based on events stored in a named group bucket. See the xref:{s-path}/notifications.adoc#sending-grouped-emails[Sending Grouped Emails] section in the _notification_ service for details. + +=== Verify and Inspect a Blobstore + +This command has been added to verify and inspect the configured Blobstore without requiring direct access to the underlying storage system. Use the following xref:maintenance/commands/verify-and-inspect-blobstore.adoc[CLI command] for this task. diff --git a/content/ocis/8.1/modules/admin/pages/maintenance/commands/verify-and-inspect-blobstore.adoc b/content/ocis/8.1/modules/admin/pages/maintenance/commands/verify-and-inspect-blobstore.adoc new file mode 100644 index 0000000..fae3f3c --- /dev/null +++ b/content/ocis/8.1/modules/admin/pages/maintenance/commands/verify-and-inspect-blobstore.adoc @@ -0,0 +1,40 @@ += Verify and Inspect a Blobstore +:toc: right + +Verify and inspect the configured Blobstore without requiring direct access to the underlying storage system. + +include::partial$/maintenance/ocis-storage-users-cli.adoc[] + +== Command Details + +The following command can verify and inspect the configured Blobstore. + +.Usage: + +[source,bash] +---- +ocis storage-users blobstore -h +NAME: + ocis storage-users blobstore - manage the blobstore + +USAGE: + ocis storage-users blobstore [command options] + +COMMANDS: + check check blobstore connectivity via an upload/download/delete round-trip + get get a blob from the blobstore by ID + help, h Shows a list of commands or help for one command + +OPTIONS: + --help, -h show help +---- + +.Notes: + +* `blobstore check` + +Performs a full upload/download/delete round-trip using a random payload. The payload size is configurable via `--blob-size` and accepts human-readable values such as `64`, `1KB` or `4MiB` (default: 64 bytes). + +* `blobstore get` + +Downloads a specific blob by its ID to verify it is readable. The blob can be identified either with `--blob-id` and `--space-id`, or by passing the raw blob path from a log line directly via `--path`. Both the s3ng key format (`/`) and the ocis filesystem path format (`…/spaces//blobs/`) are accepted. When using the s3ng driver without a known blob size, an automatic retry with the actual size is performed on a size mismatch. + +As both commands read the existing service configuration, they always target the same blobstore as the running service. Only the `ocis` and `s3ng` storage drivers are supported. diff --git a/content/ocis/8.1/modules/admin/pages/migration/upgrading-ocis.adoc b/content/ocis/8.1/modules/admin/pages/migration/upgrading-ocis.adoc index aca75c9..cac5ab9 100644 --- a/content/ocis/8.1/modules/admin/pages/migration/upgrading-ocis.adoc +++ b/content/ocis/8.1/modules/admin/pages/migration/upgrading-ocis.adoc @@ -20,6 +20,20 @@ IMPORTANT: When upgrading from an older release to the desired one, *ALL* upgrad 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 8.0.0 to 8.1.0 + +=== Notable Changes Requiring Manual Intervention + +There are no changes in Infinite Scale 8.1 that require manual intervention, but other notable changes have been implemented. + +=== Breaking Changes Requiring Manual Intervention + +There are no breaking changes in Infinite Scale 8.1. + +=== Upgrade Steps + +For a detailed description of the steps to upgrade, see the xref:migration/upgrading_8.0.0_8.1.0.adoc[Upgrading from 8.0.0 to 8.1.0] documentation. Note that this document also contains references to added/changed/removed CLI commands and environment variables. + == Version 7.3.0 to 8.0.0 === Notable Changes Requiring Manual Intervention @@ -34,7 +48,6 @@ There are breaking changes in Infinite Scale 8.0 that only apply when using the For a detailed description of the steps to upgrade, see the xref:migration/upgrading_7.3.0_8.0.0.adoc[Upgrading from 7.3.0 to 8.0.0] documentation. Note that this document also contains references to added/changed/removed CLI commands and environment variables. - == Version 7.2.0 to 7.3.0 === Notable Changes Requiring Manual Intervention diff --git a/content/ocis/8.1/modules/admin/pages/migration/upgrading_8.0.0_8.1.0.adoc b/content/ocis/8.1/modules/admin/pages/migration/upgrading_8.0.0_8.1.0.adoc new file mode 100644 index 0000000..5eca4c6 --- /dev/null +++ b/content/ocis/8.1/modules/admin/pages/migration/upgrading_8.0.0_8.1.0.adoc @@ -0,0 +1,107 @@ += Upgrading from 8.0.0 to 8.1.0 +:toc: right +:description: This document describes the necessary steps when upgrading Infinite Scale from release 8.0.0 to 8.1.0. + +:actual_eight_version: 8.1.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 image*! +. Shut down the Infinite Scale instance +. We strongly recommend doing a backup +. Reconfigure the deployment +. Manage Breaking Changes +. Notabale Changes +. Manage Added/Removed/Deprecated environment variables +. Start Infinite Scale + +:sectnums: + +== Download and Install Infinite Scale + +Download and install Infinite Scale: + +* Issue the following command to download the new image: ++ +[source,bash,subs="attributes+"] +---- +docker pull owncloud/ocis:{actual_eight_version} +---- + +== Shut Down the Infinite Scale Instance + +Depending how you deployed Infinite Scale, you need to shut it down differently. + +* *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 `docker compose` +** Update _every_ compose file where the `ocis image` is referenced accordingly. +** If you have used the deployment examples 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 and Upgrading* section of those pages carefully. + +== Manage Breaking Changes + +There are no breaking changes in Infinite Scale 8.1 + +== Notabale Changes + +* The deployment examples now include KeyCloak as an option. + +== Reconfigure Deployment Examples + +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]. + +* Stop the deployment example + +* 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 Example] link 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. +** Note that defined image versions have changed for: + +`Traefik`, `Collabora` and `OnlyOffice`. + +The provided versions have been tested. Update at your own risk. Note that this applies in particular when using `latest`. The image versions are subject to change if a new deployment example is provided. + +** The version of other images using the `latest` tag may also have changed. +** Pull the new image versions with `docker compose pull`. + +* Start the deployment example. + +== Start Infinite Scale + +When you have finished upgrading, you now can start Infinite Scale as usual. + +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. + +== Changed Environment Variables + +See the xref:deployment/services/env-var-changes.adoc[Changed Environment Variables in Versions] document for details. diff --git a/content/ocis/8.1/modules/admin/partials/maintenance/ocis-storage-users-cli.adoc b/content/ocis/8.1/modules/admin/partials/maintenance/ocis-storage-users-cli.adoc new file mode 100644 index 0000000..04b4f65 --- /dev/null +++ b/content/ocis/8.1/modules/admin/partials/maintenance/ocis-storage-users-cli.adoc @@ -0,0 +1,31 @@ +== Command Set Overview + +The described command is part of the `ocis storage-users` command set: + +[source,bash] +---- +ocis storage-users -h +NAME: + ocis storage-users - storage-users service commands + +USAGE: + ocis storage-users [command options] + +CATEGORY: + services + +COMMANDS: + uploads manage unfinished uploads + trash-bin manage trash-bins + spaces manage spaces + blobstore manage the blobstore + help, h Shows a list of commands or help for one command + info: + health check health status + version print the version of this binary and the running service instances + server: + server start the storage-users service without runtime (unsupervised mode) + +OPTIONS: + --help, -h show help +---- diff --git a/content/ocis/8.2/modules/admin/pages/deployment/services/ports-used.adoc b/content/ocis/8.2/modules/admin/pages/deployment/services/ports-used.adoc index 37e182b..5d20ff9 100644 --- a/content/ocis/8.2/modules/admin/pages/deployment/services/ports-used.adoc +++ b/content/ocis/8.2/modules/admin/pages/deployment/services/ports-used.adoc @@ -60,6 +60,7 @@ The following port ranges are used by services: | 9260-9264 | xref:{s-path}/clientlog.adoc[clientlog] | 9270-9274 | xref:{s-path}/eventhistory.adoc[eventhistory] | 9280-9284 | xref:{s-path}/ocm.adoc[ocm] +| 9285-9289 | xref:{s-path}/storage-users.adoc[storage-users (vault)] | 9300-9304 | xref:{s-path}/collaboration.adoc[collaboration] | 9350-9354 | xref:{s-path}/ocdav.adoc[ocdav] |=== diff --git a/content/ocis/8.2/modules/admin/pages/deployment/services/s-list/storage-users.adoc b/content/ocis/8.2/modules/admin/pages/deployment/services/s-list/storage-users.adoc index a566526..e54ecf6 100644 --- a/content/ocis/8.2/modules/admin/pages/deployment/services/s-list/storage-users.adoc +++ b/content/ocis/8.2/modules/admin/pages/deployment/services/s-list/storage-users.adoc @@ -331,6 +331,67 @@ ocis storage-users trash-bin restore [command options] ['spaceID' required] ['it See the xref:deployment/storage/general-considerations.adoc#resource-optimisation[General Storage Considerations and Settings] documentation for details about configuring the `STORAGE_USERS_OCIS_MAX_CONCURRENCY` environment variable. +== Vault Mode + +The `storage-users` service can be special configured to run as additional service providing vault mode. + +Vault mode provides dedicated vault storage that is stored separately and can be protected by multi-factor authentication (MFA). Vault resources are isolated from the default user storage and have their own search function, sharing options and workspaces, while public links are explicitly disallow + +=== Configuration + +Create a `storage-users-vault` service:: ++ +-- +The following environment variables must be set in order to define an instance of the `storage-users` service as a vault: + +[source,.env] +---- +STORAGE_USERS_SERVICE_NAME: storage-users-vault +STORAGE_USERS_GRPC_ADDR: storage-users-vault:9285 +STORAGE_USERS_HTTP_ADDR: storage-users-vault:9286 +STORAGE_USERS_DATA_SERVER_URL: http://storage-users-vault:9286/data +STORAGE_USERS_DEBUG_ADDR: storage-users-vault:9287 +STORAGE_USERS_OCIS_ROOT: /var/lib/ocis/storage/users-vault +STORAGE_USERS_EVENTS_CONSUMER_GROUP: vault-dcfs +---- + +[IMPORTANT] +==== +Additionally to the environment variables shown above and for the time being, caching cannot use the shared global environment variable `OCIS_CACHE_STORE_NODES`, as described in the xref:caching[Caching] section. For a vault-instance, you must define for caching either `memory` or `noop`. The affected environment variables to set the cache are: + +* `STORAGE_USERS_FILEMETADATA_CACHE_STORE` +* `STORAGE_USERS_ID_CACHE_STORE` +==== +-- + +Configure instance communication:: ++ +-- +These environment variables complete the configuration of the service instance. The example values for these environment variables are taken from the xref:depl-examples/ubuntu-compose/ubuntu-compose-prod.adoc[Local Production Setup] deployment example. To allow inter-service communication, they need to match the main configuration of the Infinite Scale instance. + +[source,.env] +---- +OCIS_GATEWAY_GRPC_ADDR: ocis:9142 +OCIS_EVENTS_ENDPOINT: ocis:9233 +STORAGE_USERS_xxx_CACHE_STORE: 'memory' +MICRO_REGISTRY_ADDRESS: ocis:9233 +---- +-- + +Complete the configuration:: ++ +-- +With the above configuration creating a `storage-users-vault` instance, you can now set the following environment variables. These envvars are only effective if the `storage-users` service is configured vault. + +The following environment variables can be used to make further configuration changes: + +* `OCIS_ENABLE_VAULT_MODE: true` + +Enable the vault mode in a OCIS. + +* `OCIS_MFA_ENABLED: true` + +Enable multi-factor authentication (MFA) for the use with vault. +-- + == Caching // renders dependent on is_cache or is_store diff --git a/content/ocis/8.2/modules/admin/pages/maintenance/commands/commands.adoc b/content/ocis/8.2/modules/admin/pages/maintenance/commands/commands.adoc index 9828e3d..1ae3141 100644 --- a/content/ocis/8.2/modules/admin/pages/maintenance/commands/commands.adoc +++ b/content/ocis/8.2/modules/admin/pages/maintenance/commands/commands.adoc @@ -124,3 +124,7 @@ WARNING: Use this command with absolute care. It is not intended to play around === Sending Grouped Emails This command is about sending emails based on events stored in a named group bucket. See the xref:{s-path}/notifications.adoc#sending-grouped-emails[Sending Grouped Emails] section in the _notification_ service for details. + +=== Verify and Inspect a Blobstore + +This command has been added to verify and inspect the configured Blobstore without requiring direct access to the underlying storage system. Use the following xref:maintenance/commands/verify-and-inspect-blobstore.adoc[CLI command] for this task. diff --git a/content/ocis/8.2/modules/admin/pages/maintenance/commands/verify-and-inspect-blobstore.adoc b/content/ocis/8.2/modules/admin/pages/maintenance/commands/verify-and-inspect-blobstore.adoc new file mode 100644 index 0000000..fae3f3c --- /dev/null +++ b/content/ocis/8.2/modules/admin/pages/maintenance/commands/verify-and-inspect-blobstore.adoc @@ -0,0 +1,40 @@ += Verify and Inspect a Blobstore +:toc: right + +Verify and inspect the configured Blobstore without requiring direct access to the underlying storage system. + +include::partial$/maintenance/ocis-storage-users-cli.adoc[] + +== Command Details + +The following command can verify and inspect the configured Blobstore. + +.Usage: + +[source,bash] +---- +ocis storage-users blobstore -h +NAME: + ocis storage-users blobstore - manage the blobstore + +USAGE: + ocis storage-users blobstore [command options] + +COMMANDS: + check check blobstore connectivity via an upload/download/delete round-trip + get get a blob from the blobstore by ID + help, h Shows a list of commands or help for one command + +OPTIONS: + --help, -h show help +---- + +.Notes: + +* `blobstore check` + +Performs a full upload/download/delete round-trip using a random payload. The payload size is configurable via `--blob-size` and accepts human-readable values such as `64`, `1KB` or `4MiB` (default: 64 bytes). + +* `blobstore get` + +Downloads a specific blob by its ID to verify it is readable. The blob can be identified either with `--blob-id` and `--space-id`, or by passing the raw blob path from a log line directly via `--path`. Both the s3ng key format (`/`) and the ocis filesystem path format (`…/spaces//blobs/`) are accepted. When using the s3ng driver without a known blob size, an automatic retry with the actual size is performed on a size mismatch. + +As both commands read the existing service configuration, they always target the same blobstore as the running service. Only the `ocis` and `s3ng` storage drivers are supported. diff --git a/content/ocis/8.2/modules/admin/pages/migration/upgrading-ocis.adoc b/content/ocis/8.2/modules/admin/pages/migration/upgrading-ocis.adoc index aca75c9..cac5ab9 100644 --- a/content/ocis/8.2/modules/admin/pages/migration/upgrading-ocis.adoc +++ b/content/ocis/8.2/modules/admin/pages/migration/upgrading-ocis.adoc @@ -20,6 +20,20 @@ IMPORTANT: When upgrading from an older release to the desired one, *ALL* upgrad 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 8.0.0 to 8.1.0 + +=== Notable Changes Requiring Manual Intervention + +There are no changes in Infinite Scale 8.1 that require manual intervention, but other notable changes have been implemented. + +=== Breaking Changes Requiring Manual Intervention + +There are no breaking changes in Infinite Scale 8.1. + +=== Upgrade Steps + +For a detailed description of the steps to upgrade, see the xref:migration/upgrading_8.0.0_8.1.0.adoc[Upgrading from 8.0.0 to 8.1.0] documentation. Note that this document also contains references to added/changed/removed CLI commands and environment variables. + == Version 7.3.0 to 8.0.0 === Notable Changes Requiring Manual Intervention @@ -34,7 +48,6 @@ There are breaking changes in Infinite Scale 8.0 that only apply when using the For a detailed description of the steps to upgrade, see the xref:migration/upgrading_7.3.0_8.0.0.adoc[Upgrading from 7.3.0 to 8.0.0] documentation. Note that this document also contains references to added/changed/removed CLI commands and environment variables. - == Version 7.2.0 to 7.3.0 === Notable Changes Requiring Manual Intervention diff --git a/content/ocis/8.2/modules/admin/pages/migration/upgrading_8.0.0_8.1.0.adoc b/content/ocis/8.2/modules/admin/pages/migration/upgrading_8.0.0_8.1.0.adoc new file mode 100644 index 0000000..5eca4c6 --- /dev/null +++ b/content/ocis/8.2/modules/admin/pages/migration/upgrading_8.0.0_8.1.0.adoc @@ -0,0 +1,107 @@ += Upgrading from 8.0.0 to 8.1.0 +:toc: right +:description: This document describes the necessary steps when upgrading Infinite Scale from release 8.0.0 to 8.1.0. + +:actual_eight_version: 8.1.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 image*! +. Shut down the Infinite Scale instance +. We strongly recommend doing a backup +. Reconfigure the deployment +. Manage Breaking Changes +. Notabale Changes +. Manage Added/Removed/Deprecated environment variables +. Start Infinite Scale + +:sectnums: + +== Download and Install Infinite Scale + +Download and install Infinite Scale: + +* Issue the following command to download the new image: ++ +[source,bash,subs="attributes+"] +---- +docker pull owncloud/ocis:{actual_eight_version} +---- + +== Shut Down the Infinite Scale Instance + +Depending how you deployed Infinite Scale, you need to shut it down differently. + +* *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 `docker compose` +** Update _every_ compose file where the `ocis image` is referenced accordingly. +** If you have used the deployment examples 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 and Upgrading* section of those pages carefully. + +== Manage Breaking Changes + +There are no breaking changes in Infinite Scale 8.1 + +== Notabale Changes + +* The deployment examples now include KeyCloak as an option. + +== Reconfigure Deployment Examples + +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]. + +* Stop the deployment example + +* 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 Example] link 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. +** Note that defined image versions have changed for: + +`Traefik`, `Collabora` and `OnlyOffice`. + +The provided versions have been tested. Update at your own risk. Note that this applies in particular when using `latest`. The image versions are subject to change if a new deployment example is provided. + +** The version of other images using the `latest` tag may also have changed. +** Pull the new image versions with `docker compose pull`. + +* Start the deployment example. + +== Start Infinite Scale + +When you have finished upgrading, you now can start Infinite Scale as usual. + +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. + +== Changed Environment Variables + +See the xref:deployment/services/env-var-changes.adoc[Changed Environment Variables in Versions] document for details. diff --git a/content/ocis/8.2/modules/admin/partials/maintenance/ocis-storage-users-cli.adoc b/content/ocis/8.2/modules/admin/partials/maintenance/ocis-storage-users-cli.adoc new file mode 100644 index 0000000..04b4f65 --- /dev/null +++ b/content/ocis/8.2/modules/admin/partials/maintenance/ocis-storage-users-cli.adoc @@ -0,0 +1,31 @@ +== Command Set Overview + +The described command is part of the `ocis storage-users` command set: + +[source,bash] +---- +ocis storage-users -h +NAME: + ocis storage-users - storage-users service commands + +USAGE: + ocis storage-users [command options] + +CATEGORY: + services + +COMMANDS: + uploads manage unfinished uploads + trash-bin manage trash-bins + spaces manage spaces + blobstore manage the blobstore + help, h Shows a list of commands or help for one command + info: + health check health status + version print the version of this binary and the running service instances + server: + server start the storage-users service without runtime (unsupervised mode) + +OPTIONS: + --help, -h show help +---- diff --git a/content/ocis/8.3/modules/admin/pages/deployment/services/ports-used.adoc b/content/ocis/8.3/modules/admin/pages/deployment/services/ports-used.adoc index 37e182b..5d20ff9 100644 --- a/content/ocis/8.3/modules/admin/pages/deployment/services/ports-used.adoc +++ b/content/ocis/8.3/modules/admin/pages/deployment/services/ports-used.adoc @@ -60,6 +60,7 @@ The following port ranges are used by services: | 9260-9264 | xref:{s-path}/clientlog.adoc[clientlog] | 9270-9274 | xref:{s-path}/eventhistory.adoc[eventhistory] | 9280-9284 | xref:{s-path}/ocm.adoc[ocm] +| 9285-9289 | xref:{s-path}/storage-users.adoc[storage-users (vault)] | 9300-9304 | xref:{s-path}/collaboration.adoc[collaboration] | 9350-9354 | xref:{s-path}/ocdav.adoc[ocdav] |=== diff --git a/content/ocis/8.3/modules/admin/pages/deployment/services/s-list/storage-users.adoc b/content/ocis/8.3/modules/admin/pages/deployment/services/s-list/storage-users.adoc index a566526..e54ecf6 100644 --- a/content/ocis/8.3/modules/admin/pages/deployment/services/s-list/storage-users.adoc +++ b/content/ocis/8.3/modules/admin/pages/deployment/services/s-list/storage-users.adoc @@ -331,6 +331,67 @@ ocis storage-users trash-bin restore [command options] ['spaceID' required] ['it See the xref:deployment/storage/general-considerations.adoc#resource-optimisation[General Storage Considerations and Settings] documentation for details about configuring the `STORAGE_USERS_OCIS_MAX_CONCURRENCY` environment variable. +== Vault Mode + +The `storage-users` service can be special configured to run as additional service providing vault mode. + +Vault mode provides dedicated vault storage that is stored separately and can be protected by multi-factor authentication (MFA). Vault resources are isolated from the default user storage and have their own search function, sharing options and workspaces, while public links are explicitly disallow + +=== Configuration + +Create a `storage-users-vault` service:: ++ +-- +The following environment variables must be set in order to define an instance of the `storage-users` service as a vault: + +[source,.env] +---- +STORAGE_USERS_SERVICE_NAME: storage-users-vault +STORAGE_USERS_GRPC_ADDR: storage-users-vault:9285 +STORAGE_USERS_HTTP_ADDR: storage-users-vault:9286 +STORAGE_USERS_DATA_SERVER_URL: http://storage-users-vault:9286/data +STORAGE_USERS_DEBUG_ADDR: storage-users-vault:9287 +STORAGE_USERS_OCIS_ROOT: /var/lib/ocis/storage/users-vault +STORAGE_USERS_EVENTS_CONSUMER_GROUP: vault-dcfs +---- + +[IMPORTANT] +==== +Additionally to the environment variables shown above and for the time being, caching cannot use the shared global environment variable `OCIS_CACHE_STORE_NODES`, as described in the xref:caching[Caching] section. For a vault-instance, you must define for caching either `memory` or `noop`. The affected environment variables to set the cache are: + +* `STORAGE_USERS_FILEMETADATA_CACHE_STORE` +* `STORAGE_USERS_ID_CACHE_STORE` +==== +-- + +Configure instance communication:: ++ +-- +These environment variables complete the configuration of the service instance. The example values for these environment variables are taken from the xref:depl-examples/ubuntu-compose/ubuntu-compose-prod.adoc[Local Production Setup] deployment example. To allow inter-service communication, they need to match the main configuration of the Infinite Scale instance. + +[source,.env] +---- +OCIS_GATEWAY_GRPC_ADDR: ocis:9142 +OCIS_EVENTS_ENDPOINT: ocis:9233 +STORAGE_USERS_xxx_CACHE_STORE: 'memory' +MICRO_REGISTRY_ADDRESS: ocis:9233 +---- +-- + +Complete the configuration:: ++ +-- +With the above configuration creating a `storage-users-vault` instance, you can now set the following environment variables. These envvars are only effective if the `storage-users` service is configured vault. + +The following environment variables can be used to make further configuration changes: + +* `OCIS_ENABLE_VAULT_MODE: true` + +Enable the vault mode in a OCIS. + +* `OCIS_MFA_ENABLED: true` + +Enable multi-factor authentication (MFA) for the use with vault. +-- + == Caching // renders dependent on is_cache or is_store diff --git a/content/ocis/8.3/modules/admin/pages/maintenance/commands/commands.adoc b/content/ocis/8.3/modules/admin/pages/maintenance/commands/commands.adoc index 9828e3d..1ae3141 100644 --- a/content/ocis/8.3/modules/admin/pages/maintenance/commands/commands.adoc +++ b/content/ocis/8.3/modules/admin/pages/maintenance/commands/commands.adoc @@ -124,3 +124,7 @@ WARNING: Use this command with absolute care. It is not intended to play around === Sending Grouped Emails This command is about sending emails based on events stored in a named group bucket. See the xref:{s-path}/notifications.adoc#sending-grouped-emails[Sending Grouped Emails] section in the _notification_ service for details. + +=== Verify and Inspect a Blobstore + +This command has been added to verify and inspect the configured Blobstore without requiring direct access to the underlying storage system. Use the following xref:maintenance/commands/verify-and-inspect-blobstore.adoc[CLI command] for this task. diff --git a/content/ocis/8.3/modules/admin/pages/maintenance/commands/verify-and-inspect-blobstore.adoc b/content/ocis/8.3/modules/admin/pages/maintenance/commands/verify-and-inspect-blobstore.adoc new file mode 100644 index 0000000..fae3f3c --- /dev/null +++ b/content/ocis/8.3/modules/admin/pages/maintenance/commands/verify-and-inspect-blobstore.adoc @@ -0,0 +1,40 @@ += Verify and Inspect a Blobstore +:toc: right + +Verify and inspect the configured Blobstore without requiring direct access to the underlying storage system. + +include::partial$/maintenance/ocis-storage-users-cli.adoc[] + +== Command Details + +The following command can verify and inspect the configured Blobstore. + +.Usage: + +[source,bash] +---- +ocis storage-users blobstore -h +NAME: + ocis storage-users blobstore - manage the blobstore + +USAGE: + ocis storage-users blobstore [command options] + +COMMANDS: + check check blobstore connectivity via an upload/download/delete round-trip + get get a blob from the blobstore by ID + help, h Shows a list of commands or help for one command + +OPTIONS: + --help, -h show help +---- + +.Notes: + +* `blobstore check` + +Performs a full upload/download/delete round-trip using a random payload. The payload size is configurable via `--blob-size` and accepts human-readable values such as `64`, `1KB` or `4MiB` (default: 64 bytes). + +* `blobstore get` + +Downloads a specific blob by its ID to verify it is readable. The blob can be identified either with `--blob-id` and `--space-id`, or by passing the raw blob path from a log line directly via `--path`. Both the s3ng key format (`/`) and the ocis filesystem path format (`…/spaces//blobs/`) are accepted. When using the s3ng driver without a known blob size, an automatic retry with the actual size is performed on a size mismatch. + +As both commands read the existing service configuration, they always target the same blobstore as the running service. Only the `ocis` and `s3ng` storage drivers are supported. diff --git a/content/ocis/8.3/modules/admin/pages/migration/upgrading-ocis.adoc b/content/ocis/8.3/modules/admin/pages/migration/upgrading-ocis.adoc index aca75c9..cac5ab9 100644 --- a/content/ocis/8.3/modules/admin/pages/migration/upgrading-ocis.adoc +++ b/content/ocis/8.3/modules/admin/pages/migration/upgrading-ocis.adoc @@ -20,6 +20,20 @@ IMPORTANT: When upgrading from an older release to the desired one, *ALL* upgrad 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 8.0.0 to 8.1.0 + +=== Notable Changes Requiring Manual Intervention + +There are no changes in Infinite Scale 8.1 that require manual intervention, but other notable changes have been implemented. + +=== Breaking Changes Requiring Manual Intervention + +There are no breaking changes in Infinite Scale 8.1. + +=== Upgrade Steps + +For a detailed description of the steps to upgrade, see the xref:migration/upgrading_8.0.0_8.1.0.adoc[Upgrading from 8.0.0 to 8.1.0] documentation. Note that this document also contains references to added/changed/removed CLI commands and environment variables. + == Version 7.3.0 to 8.0.0 === Notable Changes Requiring Manual Intervention @@ -34,7 +48,6 @@ There are breaking changes in Infinite Scale 8.0 that only apply when using the For a detailed description of the steps to upgrade, see the xref:migration/upgrading_7.3.0_8.0.0.adoc[Upgrading from 7.3.0 to 8.0.0] documentation. Note that this document also contains references to added/changed/removed CLI commands and environment variables. - == Version 7.2.0 to 7.3.0 === Notable Changes Requiring Manual Intervention diff --git a/content/ocis/8.3/modules/admin/pages/migration/upgrading_8.0.0_8.1.0.adoc b/content/ocis/8.3/modules/admin/pages/migration/upgrading_8.0.0_8.1.0.adoc new file mode 100644 index 0000000..5eca4c6 --- /dev/null +++ b/content/ocis/8.3/modules/admin/pages/migration/upgrading_8.0.0_8.1.0.adoc @@ -0,0 +1,107 @@ += Upgrading from 8.0.0 to 8.1.0 +:toc: right +:description: This document describes the necessary steps when upgrading Infinite Scale from release 8.0.0 to 8.1.0. + +:actual_eight_version: 8.1.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 image*! +. Shut down the Infinite Scale instance +. We strongly recommend doing a backup +. Reconfigure the deployment +. Manage Breaking Changes +. Notabale Changes +. Manage Added/Removed/Deprecated environment variables +. Start Infinite Scale + +:sectnums: + +== Download and Install Infinite Scale + +Download and install Infinite Scale: + +* Issue the following command to download the new image: ++ +[source,bash,subs="attributes+"] +---- +docker pull owncloud/ocis:{actual_eight_version} +---- + +== Shut Down the Infinite Scale Instance + +Depending how you deployed Infinite Scale, you need to shut it down differently. + +* *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 `docker compose` +** Update _every_ compose file where the `ocis image` is referenced accordingly. +** If you have used the deployment examples 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 and Upgrading* section of those pages carefully. + +== Manage Breaking Changes + +There are no breaking changes in Infinite Scale 8.1 + +== Notabale Changes + +* The deployment examples now include KeyCloak as an option. + +== Reconfigure Deployment Examples + +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]. + +* Stop the deployment example + +* 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 Example] link 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. +** Note that defined image versions have changed for: + +`Traefik`, `Collabora` and `OnlyOffice`. + +The provided versions have been tested. Update at your own risk. Note that this applies in particular when using `latest`. The image versions are subject to change if a new deployment example is provided. + +** The version of other images using the `latest` tag may also have changed. +** Pull the new image versions with `docker compose pull`. + +* Start the deployment example. + +== Start Infinite Scale + +When you have finished upgrading, you now can start Infinite Scale as usual. + +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. + +== Changed Environment Variables + +See the xref:deployment/services/env-var-changes.adoc[Changed Environment Variables in Versions] document for details. diff --git a/content/ocis/8.3/modules/admin/partials/maintenance/ocis-storage-users-cli.adoc b/content/ocis/8.3/modules/admin/partials/maintenance/ocis-storage-users-cli.adoc new file mode 100644 index 0000000..04b4f65 --- /dev/null +++ b/content/ocis/8.3/modules/admin/partials/maintenance/ocis-storage-users-cli.adoc @@ -0,0 +1,31 @@ +== Command Set Overview + +The described command is part of the `ocis storage-users` command set: + +[source,bash] +---- +ocis storage-users -h +NAME: + ocis storage-users - storage-users service commands + +USAGE: + ocis storage-users [command options] + +CATEGORY: + services + +COMMANDS: + uploads manage unfinished uploads + trash-bin manage trash-bins + spaces manage spaces + blobstore manage the blobstore + help, h Shows a list of commands or help for one command + info: + health check health status + version print the version of this binary and the running service instances + server: + server start the storage-users service without runtime (unsupervised mode) + +OPTIONS: + --help, -h show help +----