Skip to content

add recommendations for large migrations #1111

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Svanvith wants to merge 1 commit into
base: main
Choose a base branch
from
+43 −0
Open

add recommendations for large migrations #1111

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 43 additions & 0 deletions docs/admin/maintenance/migrate.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`:
Expand All @@ -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!
Expand Down