Updating RustSearch

Before updating

1. Read the release notes for version-specific requirements and any separate index migration.
2. Upload the new KPZ through Koha’s plugin manager. Do not uninstall the existing plugin.
3. Open Configuration → Update RustSearch and copy its bundled SSH command. Replace INSTANCE with the actual instance name.
4. Run --check-only to inspect prerequisites and existing engine compatibility.

Server updates run over SSH as the normal administrator with sudo access. The web process does not execute them.

Update the engine and plugin

Use --update to build and test the bundled engine, back up the deployment, install matching components and verify native search. Uploading a KPZ alone does not replace the engine executable.

Compatible same-schema updates retain existing indexes. The service account, index paths, tenant port and enabled optional features are preserved. Expect a brief search interruption during the switch. Upgrades requiring an index migration follow a separate procedure in their release notes.

Keep the printed backup paths and installation log. Validate staff and OPAC searches, indexing status and enabled features after updating.

Refresh the plugin and integration only

Use --existing-engine only when the release instructions do not require a new engine executable. This refresh retains the engine binary and indexes; engine changes are not applied.

This is not a transactional engine replacement. Completed steps may remain installed if a later step fails. Incompatible engines require a separate migration and are refused.

If an update stops

Keep its log and backup paths. Read the underlying error and verify the recorded rollback status before retrying. Installation-file backups do not undo catalog edits. Follow the matching recovery instructions and preserve the library’s selected SearchEngine through a compatible update.

Production deployments require schema 7 or newer. Validate the library’s catalog and configuration in staging before production use.