diff --git a/.vuepress/config.js b/.vuepress/config.js index 22c0e01512..5071e22939 100644 --- a/.vuepress/config.js +++ b/.vuepress/config.js @@ -148,29 +148,68 @@ module.exports = { collapsable: false, children: [ { - title: 'Run in Production', - path: '/create/how_to/running_production', - }, - { - title: 'Integrate into Your Documentation', - path: '/create/how_to/search_bar_for_docs', - }, - { - title: 'Deploy on DigitalOcean', - path: '/create/how_to/digitalocean_droplet', + title: 'Basics', + collapsable: false, + sidebarDepth: 0, + children: [ + { + title: 'Update MeiliSearch', + path: '/create/how_to/updating', + }, + { + title: 'Run in Production', + path: '/create/how_to/running_production', + }, + { + title: 'Use with Postman', + path: '/create/how_to/postman_collection', + }, + ], }, { - title: 'Deploy on AWS', - path: '/create/how_to/aws', + title: 'Deploy', + collapsable: false, + sidebarDepth: 0, + children: [ + { + title: 'Deploy on DigitalOcean', + path: '/create/how_to/digitalocean_droplet', + }, + { + title: 'Deploy on AWS', + path: '/create/how_to/aws', + }, + { + title: 'Deploy on Qovery', + path: '/create/how_to/qovery', + }, + ], }, - '/create/how_to/http2_ssl', { - title: 'Use with Postman', - path: '/create/how_to/postman_collection', + title: 'Integrate', + collapsable: false, + sidebarDepth: 0, + children: [ + { + title: 'Add a Search Bar to Your Docs', + path: '/create/how_to/search_bar_for_docs', + }, + { + title: 'Add to a React app', + path: '/create/how_to/meilisearch_react', + }, + ], }, { - title: 'Add to a React app', - path: '/create/how_to/meilisearch_react', + title: 'Miscellaneous', + collapsable: false, + sidebarDepth: 0, + children: [ + { + title: 'Use HTTP/2 and SSL', + path: '/create/how_to/http2_ssl', + }, + ], }, ], }, diff --git a/create/how_to/README.md b/create/how_to/README.md index 1113c9894c..74d576773c 100644 --- a/create/how_to/README.md +++ b/create/how_to/README.md @@ -1,17 +1,28 @@ # How To -These how-to guides take the reader through the steps required to solve a real-world problem. Like recipes in a cookbook, they represent repeatable solutions to particular problems. +Each guide in this section takes the reader through the steps required to solve a real-world problem. Like recipes in a cookbook, they are **repeatable solutions** you can return to many times. -This is not the section for tutorial content. If you'd like to follow a step-by-step tutorial that introduces you to the basics of MeiliSearch, check out our [getting started guide](/learn/getting_started/quick_start.md). +This is not the best section for MeiliSearch beginners. If you'd like to follow a step-by-step guide that introduces you to the basics of MeiliSearch, check out our [quick start guide](/learn/getting_started/quick_start.md). ## Table of Contents -How to: +**Basics**: +- [Update MeiliSearch](/create/how_to/updating.md) - [Run MeiliSearch in Production](/create/how_to/running_production.md) -- [Integrate a Relevant Search Bar to Your Documentation](/create/how_to/search_bar_for_docs.md) +- [Use Postman with MeiliSearch](/create/how_to/postman_collection.md) + +**Deploy**: + - [Deploy MeiliSearch on DigitalOcean](/create/how_to/digitalocean_droplet.md) - [Deploy MeiliSearch on AWS](/create/how_to/aws.md) -- [Use HTTP/2 and SSL with MeiliSearch](/create/how_to/http2_ssl.md) -- [Use Postman with MeiliSearch](/create/how_to/postman_collection.md) +- [Deploy MeiliSearch on Qovery](/create/how_to/qovery.md) + +**Front-end Integration**: + +- [Integrate a Relevant Search Bar to Your Documentation](/create/how_to/search_bar_for_docs.md) - [Implement Instant Search in Your React App in 5 Minutes](/create/how_to/meilisearch_react.md) + +**Miscellaneous**: + +- [Use HTTP/2 and SSL with MeiliSearch](/create/how_to/http2_ssl.md) diff --git a/create/how_to/qovery.md b/create/how_to/qovery.md index 2d42a1d9cc..b369f43e35 100644 --- a/create/how_to/qovery.md +++ b/create/how_to/qovery.md @@ -1,4 +1,8 @@ -# How to deploy a MeiliSearch instance on Qovery +# Deploy a MeiliSearch Instance on Qovery + +_The following is a guest post by Romaric Philogène, CEO and Co-Founder of Qovery._ + +## Introduction In this tutorial I explain how to deploy a pre-configured Meilisearch instance in one click. @@ -6,10 +10,10 @@ In this tutorial I explain how to deploy a pre-configured Meilisearch instance i Deploying Meilisearch with Qovery provides: -* A pre-configured Meilisearch instance. -* A free SSD storage. -* A free SSL. -* Optional: custom domain. +- A pre-configured Meilisearch instance. +- A free SSD storage. +- A free SSL. +- Optional: custom domain. ## Step-by-step Meilisearch deployment @@ -19,16 +23,16 @@ Visit [the Qovery dashboard](https://start.qovery.com) to create an account if y ### 2. Create a project -* Click on the "create a project" button and give a name to your project. Eg. `Meilisearch` -* Click on "next". +- Click on the "create a project" button and give a name to your project, e.g. `MeiliSearch`. +- Click on "next". ### 3. Deploy Meilisearch ![meilisearch template](https://github.com/Qovery/public-resources/raw/master/screenshots/meilisearch-template.png) -* Click on the "use a template" button. -* Select "Meilisearch". -* Select your Github or Gitlab repository where Qovery will save your configuration files (Qovery uses Git as the source of truth). -* Click on "deploy". +- Click on the "use a template" button. +- Select "Meilisearch". +- Select your Github or Gitlab repository where Qovery will save your configuration files (Qovery uses Git as the source of truth). +- Click on "deploy". Congrats 🔥 - Your Meilisearch instance is deployed and ready to be used 🎉 diff --git a/create/how_to/updating.md b/create/how_to/updating.md new file mode 100644 index 0000000000..ba54f4d2c9 --- /dev/null +++ b/create/how_to/updating.md @@ -0,0 +1,327 @@ +# Update to the Latest MeiliSearch Version + +Currently, MeiliSearch databases can only be opened by the MeiliSearch version you used to create them. The following guide will walk you through all the steps to **migrate an existing database** from an older version of MeiliSearch to the most recent one. + +If you already have a MeiliSearch database with some data you don’t want to lose, you are in the right place! + +## Verify your database version + +Before we begin, you need to **verify the version of MeiliSearch that's compatible with your database**, i.e. the version that indexed the data. You can do so by launching a MeiliSearch instance: + +```bash +./meilisearch +``` + +If MeiliSearch launches successfully, use the [get version endpoint](/reference/api/version.md), note your `pkgVersion`, and [proceed to the next step](#proceed-according-to-your-database-version). + +```bash +curl -X GET 'http://127.0.0.1:7700/version' +``` + +The response should look something like this: + +```json +{ + "commitSha":"stringOfLettersAndNumbers", + "buildDate":"YYYY-MM-DDTimestamp", + "pkgVersion":"x.y.z" +} +``` + +If you get the error `Cannot open database, expected MeiliSearch engine version: 0.X.X, current engine version 0.Y.Y`, your database is not compatible with the currently installed MeiliSearch version. + +In this case, you need to **download the compatible version now** (i.e. `0.X.X` in the above error message) so that you can access and export your database. + +:::: tabs + +::: tab cURL +If you downloaded MeiliSearch using `curl`, find and download the compatible version [here](https://github.com/meilisearch/MeiliSearch/releases) before continuing. +::: + +::: tab Homebrew + +Replace `0.X.X` with the version you would like to install. + +```bash +brew install meilisearch@0.X.X +``` + +::: + +::: tab Source + +Replace `0.X.X` with the version you would like to install. + +```bash +# clone MeiliSearch and checkout the branch of the expected version +git clone https://github.com/meilisearch/MeiliSearch +cd MeiliSearch +git checkout v0.X.X + +# update the rust toolchain to the latest version +rustup update + +# compile the project +cargo build --release + +# execute the server binary +./target/release/meilisearch +``` + +::: + +::: tab APT + +Replace `0.X.X` with the version you would like to install. + +```bash +apt-get install meilisearch=0.X.X +``` + +::: + +::: tab Docker + +Replace `0.X.X` with the version you would like to install. + +```bash +docker run -it --rm \ + -p 7700:7700 \ + -v "$(pwd)/data.ms:/data.ms" \ + getmeili/meilisearch:v0.X.X +``` + +::: + +:::: + +### Proceed according to your database version + +Now that you know which MeiliSearch version your database is compatible with, proceed accordingly: + +- **If your database version is v0.15.0 or above**, continue to the [next section](#updating-from-v0-15-0-or-above). +- **If your version is v0.14.0 or below**, [go here](#updating-from-v0-14-0-or-below). + +## Updating from v0.15.0 or above + +Because MeiliSearch v0.15.0 and above include the [dumps feature](/reference/features/dumps.md), updating is relatively simple. + +In this guide, we will: + +1. [Set all fields as displayed attributes](#step-1-set-all-fields-as-displayed-attributes) +2. [Create a dump using the MeiliSearch version that's compatible with your database](#step-2-create-the-dump) +3. [Import the dump using the most recent MeiliSearch version](#step-3-import-the-dump) + +### Step 1: Set all fields as displayed attributes + +When creating dumps, MeiliSearch calls the same method as the [get documents endpoint](/reference/api/documents.md#get-documents). This means that all fields must be [displayed](/reference/features/field_properties.md#displayed-fields) in order to be saved in the dump. + +Start by using the [get displayed attributes endpoint](/reference/api/displayed_attributes.md#get-displayed-attributes) to verify that **all attributes are displayed**. + +```bash +# whenever you see :index_uid, replace it with your index's unique id +curl -X GET \ + 'http://127.0.0.1:7700/indexes/:index_uid/settings/displayed-attributes' +``` + +If the response is `{'displayedAttributes': '["*"]'}`, you can move on to the [next step](#step-2-create-the-dump). + +If it's something else, then you need to use the [reset displayed attributes endpoint](/reference/api/displayed_attributes.md#reset-displayed-attributes). Before doing this, make sure you save your list of displayed attributes somewhere so you can restore it afterwards. + +```bash +curl -X DELETE \ + 'http://127.0.0.1:7700/indexes/:index_uid/settings/displayed-attributes' +``` + +This command should return an updateId: + +```json +{ + "updateId": 1 +} +``` + +Now that all fields are displayed, proceed to the next step. + +### Step 2: Create the dump + +Before creating your dump, make sure that your [dump directory](/reference/features/configuration.md#dumps-destination) is somewhere accessible. By default, dumps are created in a folder called `dumps` at the root of your MeiliSearch directory. + +If you're unsure where your MeiliSearch directory is located, try this: + +:::: tabs + +::: tab macOS / Linux + +```bash +which meilisearch +``` + +It should return something like this: + +```bash +/absolute/path/to/your/meilisearch/directory +``` + +::: + +::: tab Windows CMD + +```bash +where meilisearch +``` + +It should return something like this: + +```bash +/absolute/path/to/your/meilisearch/directory +``` + +::: + +::: tab Windows PowerShell + +```bash +(Get-Command meilisearch).Path +``` + +It should return something like this: + +```bash +/absolute/path/to/your/meilisearch/directory +``` + +::: + +:::: + +To create a dump, use the [create dump endpoint](/reference/api/dump.md#create-a-dump). + +```bash +curl -X POST 'http://127.0.0.1:7700/dumps' +``` + +The server should return a response that looks like this: + +```json +{ + "uid": "20210212-151153878", + "status": "in_progress" +} +``` + +This process can take some time. Since dump creation is an [asynchronous process](/learn/advanced/asynchronous_updates.md), you can use the returned `uid` to [track its status](/reference/api/dump.md#get-dump-status). + +```bash +# replace :dump_uid with the uid returned by the previous command +curl -X GET 'http://127.0.0.1:7700/dumps/:dump_uid/status' +``` + +Once the response to the previous command looks like this (`"status": "done"`), move on. + +```json +{ + "uid": "20210212-151153878", + "status": "done" +} +``` + +### Step 3: Import the dump + +Now that you’ve got your dump, [install the latest version of MeiliSearch](/learn/getting_started/installation.md#download-and-launch) and [import the dump](/reference/features/dumps.md#importing-a-dump) at launch using the [CLI option](/reference/features/configuration.md#import-dump). + +```bash +# install MeiliSearch +curl -L https://install.meilisearch.com | sh + +# launch MeiliSearch and import the specified dump file +./meilisearch --import-dump /dumps/your_dump_file.dump +``` + +> Importing a dump is the same process as indexing documents. This can take time and cause a spike in memory usage; to save memory, use a [smaller batch size](/reference/features/configuration.md#dump-batch-size). + +Finally, don’t forget to set `displayedAttributes` back to its previous value if necessary. You can do this using the [update displayed attributes endpoint](/reference/api/displayed_attributes.md#update-displayed-attributes). + +Congratulations! You have successfully migrated your MeiliSearch database to the latest version! 🎉 + +## Updating from v0.14.0 or below + +Since these versions predate the [dumps feature](/reference/features/dumps.md), the best solution is to export your documents and your [index settings](/reference/features/settings.md) as `.JSON` files. + +If you don’t need to preserve index settings, skip directly to [step two](#step-2-set-all-fields-as-displayed-attributes). + +### Step 1: Save your settings + +First, use the [get settings endpoint](/reference/api/settings.md#get-settings) to retrieve the [settings](/reference/features/settings.md) of any indexes you want to preserve, and save them to a file using the method you prefer. + +```bash +# the -o option saves the output as a local file +curl -X GET \ + 'http://127.0.0.1:7700/indexes/:index_uid/settings' -o mysettings.json +``` + +Repeat this process for all indexes you wish to migrate. + +**It is important to save your settings before exporting documents**, since the next step may require you to modify the settings. + +### Step 2: Set all fields as displayed attributes + +To prevent data loss, all fields must be set as [displayed](/reference/features/field_properties.md#displayed-fields). + +By default, all fields are added to the displayed attributes list. Still, it's a good idea to verify this before creating a dump. You can do so by using the [get displayed attributes endpoint](/reference/api/displayed_attributes.md#get-displayed-attributes): + +```bash +curl -X GET \ + 'http://127.0.0.1:7700/indexes/:index_uid/settings/displayed-attributes' +``` + +If the response is `'["*"]'`, you can move on to the [next step](#step-2-create-the-dump). + +If it's something else, then you need to use the [reset displayed-attributes endpoint](/reference/api/displayed_attributes.md#reset-displayed-attributes). Before doing this, make sure you save your list of displayed attributes somewhere so you can restore it afterwards. + +```bash +curl -X DELETE \ + 'http://127.0.0.1:7700/indexes/:index_uid/settings/displayed-attributes' +``` + +This command should return an updateId: + +```json +{ + "updateId": 1 +} +``` + +Now that all fields are displayed, proceed to the next step. + +### Step 3: Save your documents + +Use the [get documents endpoint](/reference/api/documents.md#get-documents) to retrieve your documents and save them using the method you prefer. Make sure to set the `limit` on documents returned so that, if you have some number of documents `n`, `limit ≥ n`. Otherwise, you risk data loss. + +```bash +# the -o option saves the output as a local file +# whenever you see :index_uid, replace it with your index's unique id +curl -X GET \ + 'http://127.0.0.1:7700/indexes/:index_uid/documents?limit=n' \ + -o mydocuments.json +``` + +### Step 4: Upload your data to the latest version of MeiliSearch + +Finally, [install the latest version of MeiliSearch](/learn/getting_started/installation.md) and upload your data as usual. + +If you chose to save your settings, make sure to follow this order: + +```bash +# update your settings +curl -X POST -H "Content-Type: application/json" -d @mysettings.json \ + 'http://127.0.0.1:7700/indexes/:index_uid/settings' + +# then, add your documents +curl -X POST -H "Content-Type: application/json" -d @mydocuments.json \ + 'http://127.0.0.1:7700/indexes/:index_uid/documents' +``` + +Since updating the settings requires re-indexing all documents, this order saves time and memory. + +Congratulations! You have successfully migrated your MeiliSearch database to the latest version! 🎉 diff --git a/learn/getting_started/README.md b/learn/getting_started/README.md index 56ffd259a7..c8a1adb499 100644 --- a/learn/getting_started/README.md +++ b/learn/getting_started/README.md @@ -7,7 +7,7 @@ It is **not** to provide exhaustive or universal instructions on how to use Meil ## Table of Contents: - [Installation](/learn/getting_started/installation.md) -- [Getting Started](/learn/getting_started/quick_start.md) +- [Quick Start Guide](/learn/getting_started/quick_start.md) - [Download and launch MeiliSearch](/learn/getting_started/quick_start.md#download-and-launch) - [Add documents](/learn/getting_started/quick_start.md#add-documents) - [Search!](/learn/getting_started/quick_start.md#search) diff --git a/learn/getting_started/installation.md b/learn/getting_started/installation.md index 8e246c171a..1c82751847 100644 --- a/learn/getting_started/installation.md +++ b/learn/getting_started/installation.md @@ -1,11 +1,11 @@ # Installation -## Download and launch +## Download and Launch :::: tabs ::: tab cURL -Download the **latest stable release** of MeiliSearch with **curl**. +Download the **latest stable release** of MeiliSearch with **cURL**. Launch MeiliSearch to start the server. @@ -94,23 +94,27 @@ cargo build --release ::: +::: tab Windows +To install MeiliSearch on Windows, use Docker or compile from the source. + +A common compilation error (`"link.exe not found"`) can be solved by installing [Visual Studio Build Tools](https://visualstudio.microsoft.com/downloads/) (scroll down and click on **Tools for Visual Studio 2019**). + +MeiliSearch will allocate 100GB on launch. If disk space is an issue on your machine, adjust the [main database](/reference/features/configuration.md#max-mdb-size) and [update database](/reference/features/configuration.md#max-udb-size) maximums accordingly. +::: + :::: -After launching MeiliSearch, you should see the following response: +::: tip Compile for Best Performance +For best performance, compile MeiliSearch on the machine you intend to run it on. This way, the binary is optimized for your specific architecture. +::: -``` -888b d888 d8b 888 d8b .d8888b. 888 -8888b d8888 Y8P 888 Y8P d88P Y88b 888 -88888b.d88888 888 Y88b. 888 -888Y88888P888 .d88b. 888 888 888 "Y888b. .d88b. 8888b. 888d888 .d8888b 88888b. -888 Y888P 888 d8P Y8b 888 888 888 "Y88b. d8P Y8b "88b 888P" d88P" 888 "88b -888 Y8P 888 88888888 888 888 888 "888 88888888 .d888888 888 888 888 888 -888 " 888 Y8b. 888 888 888 Y88b d88P Y8b. 888 888 888 Y88b. 888 888 -888 888 "Y8888 888 888 888 "Y8888P" "Y8888 "Y888888 888 "Y8888P 888 888 - -Database path: "./data.ms" -Server listening on: "127.0.0.1:7700" -``` +## Cloud Deploy + +To deploy MeiliSearch on a cloud service, follow one of our dedicated guides: + +- [AWS](/create/how_to/aws.md) +- [DigitalOcean](/create/how_to/digitalocean_droplet.md) +- [Qovery](/create/how_to/qovery.md) ## Configuration Options @@ -126,18 +130,10 @@ Here is a list of [all the options and how to use them](/reference/features/conf ## Updating MeiliSearch -Getting the latest version of MeiliSearch is a straightforward process: simply fetch and install the latest binary with your preferred method (see [installation](/learn/getting_started/installation.md#download-and-launch) above). - -However, please note that prior to our official release (`v1.0`), all minor updates (`v0.X`) are considered breaking. Therefore, **MeiliSearch databases are not compatible across versions** for as long as we are in beta. - -If you want to transfer your database from an outdated MeiliSearch instance to the most recent version, we recommend following [the below guide](/learn/getting_started/installation.md#migrating-a-database-to-a-later-version). - -If you get the error `Cannot open database, expected MeiliSearch engine version: X.X.X, current engine version Y.Y.Y`, simply delete your database folder (defaults to `data.ms`), and re-index all your documents. - -### Migrating a Database to a Later Version +Getting the latest version of MeiliSearch is a straightforward process: simply fetch and install the latest binary with your preferred method (see [Installation](/learn/getting_started/installation.md#download-and-launch) above). -Using [dumps](/reference/features/dumps.md), you can export your MeiliSearch data—all indexes, documents, and settings contained in your database—into a transferrable state. Then, you can re-import this data after updating MeiliSearch to the latest version. +However, please note that **prior to our official release (`v1.0`), databases are not compatible across versions**. Any database created by MeiliSearch `v0.X` can only be read by that version. -Since the content is exported in a way that guarantees mobility, it needs to be re-indexed. If your database is large, this process can take a long time. Nonetheless, this process guarantees **to migrate all settings and documents between two different versions of MeiliSearch**. +### Migrating Your Database to a Later Version -If you want a complete guide on how to update MeiliSearch on DigitalOcean, please [look at this GitHub issue](https://github.com/meilisearch/MeiliSearch/discussions/1187#discussioncomment-278125). +If you get the error `Cannot open database, expected MeiliSearch engine version: X.X.X, current engine version Y.Y.Y`, your database is not compatible with the version you're using. To migrate your database to the most recent version of MeiliSearch, follow our [dedicated guide](/create/how_to/updating.md). diff --git a/learn/getting_started/quick_start.md b/learn/getting_started/quick_start.md index 47d588cd3d..9067762214 100644 --- a/learn/getting_started/quick_start.md +++ b/learn/getting_started/quick_start.md @@ -1,8 +1,8 @@ -# Getting Started +# Quick Start This quick tour will help you get started with MeiliSearch in only a few steps. -## Download and launch +## Download and Launch First of all, let's download and run MeiliSearch. diff --git a/reference/features/configuration.md b/reference/features/configuration.md index f43fedda1c..e9e1ee9cf0 100644 --- a/reference/features/configuration.md +++ b/reference/features/configuration.md @@ -230,7 +230,7 @@ Depending on the OS, it is either the size that will be allocated on launch or t - On **UNIX** it is the maximum size. - On **Windows** it is a fixed size that will be allocated on launch. - Because this allocates 100Gb on MeiliSearch launch, a Windows user can use this option to decrease the size of the database. + Because this allocates 100GiB on MeiliSearch launch, a Windows user can use this option to decrease the size of the database. [To know more about storage in MeiliSearch look at this guide](/reference/under_the_hood/storage.md) @@ -254,7 +254,7 @@ Depending on the OS, it is either the size that will be allocated on launch or t - On **UNIX** it is the maximum size. - On **Windows** it is a fixed size that will be allocated on launch. - Because this allocates 100Gb on MeiliSearch launch, a Windows user can use this option to decrease the size of the database. + Because this allocates 100GiB on MeiliSearch launch, a Windows user can use this option to decrease the size of the database. [To know more about storage in MeiliSearch look at this guide](/reference/under_the_hood/storage.md) diff --git a/reference/features/field_properties.md b/reference/features/field_properties.md index 1ab27dba81..576aba61f7 100644 --- a/reference/features/field_properties.md +++ b/reference/features/field_properties.md @@ -16,7 +16,7 @@ When you perform a search, all searchable fields are searched for matching query Non-searchable fields are most useful for internal information that's not relevant to the search experience, such as URLs, sales numbers, or ratings used exclusively for sorting results. ::: tip -Even if you make a field non-searchable, it will remain stored in the database and can be made searchable again at a later time. +Even if you make a field non-searchable, it will remain [stored in the database](#data-storing) and can be made searchable again at a later time. ::: ### The Searchable Attributes List