From 7d0635e2bc932f498b55a4b9268641ecd74983af Mon Sep 17 00:00:00 2001 From: Anja Barz Date: Thu, 13 Aug 2026 15:29:14 +0200 Subject: [PATCH] add recommendations for large migrations --- docs/admin/maintenance/migrate.md | 43 +++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) diff --git a/docs/admin/maintenance/migrate.md b/docs/admin/maintenance/migrate.md index 728955c3..bfdc6f19 100644 --- a/docs/admin/maintenance/migrate.md +++ b/docs/admin/maintenance/migrate.md @@ -198,6 +198,33 @@ description = nc-bob ``` +## Prepare OpenCloud for a Large Migration + +:::note Optional optimization +The steps in this section are intended for a large initial bulk import. Skip them for small +migrations where the additional system load is not a concern. +::: + +A bulk import generates substantially more file events than normal operation. Temporarily exclude +the `activitylog` and `search` services to prevent activity processing and search indexing from +competing with the migration for system resources. + +Add both services to `OC_EXCLUDE_RUN_SERVICES` in the OpenCloud `.env` file: + +```dotenv +OC_EXCLUDE_RUN_SERVICES=activitylog,search +``` + +If the variable already contains other services, preserve them and append `activitylog` and `search` +to the comma-separated list. Restart the OpenCloud container after changing the configuration. + +While the services are excluded: + +- OpenCloud does not record activity history for files created or updated by the migration. This can + prevent duplicate or misleading entries when data is migrated in multiple passes. +- Search results for migrated data remain incomplete until the search service is re-enabled and the + index is rebuilt. + ## Copy Data to OpenCloud Use `rclone copy` to transfer data from `oCIS` and `Nextcloud` to `OpenCloud`: @@ -209,6 +236,22 @@ rclone copy nc-bob:/ opencloud-alan:/ --no-check-certificate -P # Copy Nextclou ``` +## Restore Normal Operation After a Large Migration + +If you applied the optimizations for a large migration: + +1. Remove `activitylog` and `search` from `OC_EXCLUDE_RUN_SERVICES`, preserving any services that + were excluded before the migration. +2. Restart OpenCloud and wait until the search service is ready. +3. Build the search index for all Spaces: + + ```shell + docker compose exec opencloud opencloud search index --all-spaces + ``` + + Indexing can take a long time on large installations. Search results remain incomplete until it + has finished. + ## Migration Results and Limitations Congratulations! You have successfully migrated personal space data to OpenCloud!