A self-hostable bookmark-everything app (links, notes and images) with AI-based automatic tagging and full text search
docs: add a guide for upgrading meilisearch (#3208)
lightsc184eec6c9bc
diff --git a/docs/docs/02-installation/01-docker.md b/docs/docs/02-installation/01-docker.mdindex e1c18dd4..2e5d029b 100644--- a/docs/docs/02-installation/01-docker.md+++ b/docs/docs/02-installation/01-docker.md@@ -89,4 +89,7 @@ Updating Karakeep will depend on what you used for the `KARAKEEP_VERSION` env vaIf your custom Compose file still uses the old Alpine Chrome image, follow the[Chrome image migration guide](../06-administration/09-chrome-image-migration.md).-Note that if you want to upgrade/migrate `Meilisearch` versions, refer to the [troubleshooting](../06-administration/05-troubleshooting.md) page.+Updating Karakeep doesn't change the Meilisearch image in your compose file. If+you move Meilisearch to a newer version, for example by copying a newer compose+file, it needs a one-time database upgrade first. Follow the+[Meilisearch upgrade guide](../06-administration/10-meilisearch-upgrade.md).diff --git a/docs/docs/02-installation/04-kubernetes.md b/docs/docs/02-installation/04-kubernetes.mdindex 9daac131..a4a33566 100644--- a/docs/docs/02-installation/04-kubernetes.md+++ b/docs/docs/02-installation/04-kubernetes.md@@ -98,3 +98,5 @@ Go to the [quick sharing page](../04-using-karakeep/quick-sharing.md) to installEdit the `KARAKEEP_VERSION` variable in the `kustomization.yaml` file and run `make clean deploy`.If you have chosen `release` as the image tag you can also destroy the web pod, since the deployment has an ImagePullPolicy set to always the pod always pulls the image from the registry, this way we can ensure that the newest release image is pulled.++If an update changes the Meilisearch image in `meilisearch-deployment.yaml`, Meilisearch needs a one-time database upgrade before it starts again. Follow the [Meilisearch upgrade guide](../06-administration/10-meilisearch-upgrade.md).diff --git a/docs/docs/06-administration/05-troubleshooting.md b/docs/docs/06-administration/05-troubleshooting.mdindex 2b03f328..3498a66d 100644--- a/docs/docs/06-administration/05-troubleshooting.md+++ b/docs/docs/06-administration/05-troubleshooting.md@@ -34,13 +34,6 @@ Check the logs of the container and this will usually tell you what's wrong. Com## Upgrading Meilisearch - Migrating the Meilisearch db version-[Meilisearch](https://www.meilisearch.com/) is the database used by karakeep for searching in your bookmarks. The version used by karakeep is `1.41.0` and it is advised not to upgrade it without good reasons. If you do, you might see errors like `Your database version (x.x.x) is incompatible with your current engine version (x.x.x). To migrate data between Meilisearch versions, please follow our guide on https://www.meilisearch.com/docs/learn/update_and_migration/updating.`.+[Meilisearch](https://www.meilisearch.com/) is the database used by karakeep for searching in your bookmarks. Karakeep is tested with the Meilisearch version pinned in the bundled docker compose file, so prefer that version unless you have a reason to change it. After changing the Meilisearch version, you might see errors like `Your database version (x.x.x) is incompatible with your current engine version (x.x.x)`.-Luckily we can easily workaround this:-1. Stop the Meilisearch container.-2. Inside the Meilisearch volume bound to `/meili_data`, erase/rename the folder called `data.ms`.-3. Launch Meilisearch again.-4. Login to karakeep as administrator and go to (as of v0.24.1) `Admin Settings > Background Jobs` then click on `Reindex All Bookmarks`.-5. When the reindexing has finished, Meilisearch should be working as usual.--If you run into issues, the official documentation can be found [there](https://www.meilisearch.com/docs/learn/update_and_migration/updating).+See [Upgrading Meilisearch](10-meilisearch-upgrade.md) for how to migrate the database in place, or how to rebuild it from Karakeep instead.diff --git a/docs/docs/06-administration/10-meilisearch-upgrade.md b/docs/docs/06-administration/10-meilisearch-upgrade.mdnew file mode 100644index 00000000..7bbac916--- /dev/null+++ b/docs/docs/06-administration/10-meilisearch-upgrade.md@@ -0,0 +1,89 @@+# Upgrading Meilisearch++Meilisearch won't open a database that was written by an older Meilisearch+version. If you start a newer Meilisearch image on an existing volume, the+container exits with an error like this one:++```+Your database version (1.41.0) is incompatible with your current engine version (1.55.0).+```++Search in Karakeep stops working until the database is upgraded or rebuilt. You+can either migrate the existing database in place, or start from an empty one+and let Karakeep rebuild the index.++If you run a separate Meilisearch instance for embeddings (`MEILI_VECTOR_ADDR`),+upgrade it the same way.++## Upgrading the database in place++Meilisearch can migrate an existing database while it starts. To allow it, set+`MEILI_UPGRADE_DB=true` (or pass `--upgrade-db`) when you start the new version.+Meilisearch versions older than v1.51 call this option+`MEILI_EXPERIMENTAL_DUMPLESS_UPGRADE=true` instead.++The migration is one-way: once it has run, older Meilisearch versions can't open+the data anymore. Back up the Meilisearch volume first if you might want to go+back.++### Docker Compose++1. Change the image tag of the `meilisearch` service to the new version, and add+ the variable to its environment:++ ```diff+ services:+ meilisearch:+ image: getmeili/meilisearch:<new version>+ restart: unless-stopped+ env_file:+ - .env+ environment:+ MEILI_NO_ANALYTICS: "true"+ + MEILI_UPGRADE_DB: "true"+ ```++2. Run `docker compose up -d meilisearch` and check+ `docker compose logs meilisearch`: Meilisearch should now start listening+ instead of exiting with the error above.+3. Remove `MEILI_UPGRADE_DB` again and run `docker compose up -d meilisearch`.++Leaving the variable set does no harm while the database is up to date, but the+next image change would then migrate the data without asking.++### Kubernetes++Deploy the new image as usual. The Meilisearch pod fails to start with the+error above until you enable the migration:++```bash+kubectl set env deployment/meilisearch MEILI_UPGRADE_DB=true+```++Once the new pod is running, remove the variable again:++```bash+kubectl set env deployment/meilisearch MEILI_UPGRADE_DB-+```++If Flux or Argo CD manages the deployment, set and remove the variable in+your manifests instead — the next reconcile reverts `kubectl set env`.++## Rebuilding the index instead++Karakeep can rebuild the search index from its own database, so you can also+throw away the Meilisearch data:++1. Stop Meilisearch and delete (or rename) the `data.ms` folder in the volume+ mounted at `/meili_data`.+2. Start the new Meilisearch version.+3. Log in to Karakeep as an administrator, go to+ `Admin Settings > Background Jobs` and click `Reindex All Bookmarks`.+4. If embeddings are enabled+ ([`EMBEDDING_ENABLE_AUTO_INDEXING`](../03-configuration/01-environment-variables.md)),+ also click `Regenerate Embeddings for All Bookmarks`. The embeddings were+ stored in the same Meilisearch data, so they are gone as well.++Regenerating embeddings sends every bookmark to your embedding provider again,+which can take a while and cost money on a large collection. The in-place+upgrade keeps the existing embeddings.