Oyez, oyez! A new version of Meilisearch is out and brings you a bunch of cool new features including a long-requested one: typo tolerance customization!

We have been receiving feedback from users on wanting to disable or fine-tune typo tolerance for some time. Meilisearch v0.21 introduced phrase search, which returns documents containing the exact query terms if they are enclosed within double-quotes like: `“african-american poet”`.

It was a big step towards meeting our users’ needs, but it was not enough. After carefully studying the matter, the time has come: **the customization of typo tolerance** is a reality 🎉

But hang on, what does custom typo tolerance really mean? And even more important, what does typo tolerance mean?

The good old default behavior
-----------------------------

Meilisearch is typo tolerant, meaning it understands your search even if there are typos. But with great power comes great responsibility, which means setting boundaries to keep results relevant. This translates into the following three rules:

1.  No typo is allowed if the query word is less than 5 characters long
2.  Only 1 typo is allowed if the query word is between 5 and 8 characters long
3.  2 typos are allowed if the query word is more than 8 characters long

So if you are looking for `lost` but accidentally type `last`, you wouldn't get the desired result because it’s 4 characters long.

But, typing `greeec`instead of `greece` would retrieve the expected documents because it’s 6 characters long, so one typo is allowed.

These rules are applied by default and are part of the out-of-the-box configuration of Meilisearch, providing a powerful and relevant search. Yet, as they say, rules are meant to be broken...

Customization: a new horizon of possibilities
---------------------------------------------

We know every project is different, and some users need to configure typo tolerance to suit their projects’ particularities. We hear you!

Let’s take a look at the new typo tolerance settings:

```json
"typoTolerance": {
    "enabled": true, 
    "minWordSizeForTypos": {
        "oneTypo": 5,
        "twoTypos": 10
    },
    "disableOnWords": [],
    "disableOnAttributes": []
}

```

Looking at the `typoTolerance` object above, you can now:

*   Disable typo tolerance entirely by setting `"enabled": false` 😱
*   Disable typo tolerance partially on a set of specific terms using `"disableOnWords"`
*   Disable typo tolerance on desired document attributes `"disableOnAttributes"`

You can also fine-tune the typo tolerance settings by modifying the minimum size of a word to accept one or two typos.

In sum, you have complete control of the feature.

<Callout>
  For more in-depth information on typo tolerance customization, you can read the [dedicated section](https://docs.meilisearch.com/learn/configuration/typo_tolerance.html) of the documentation.
</Callout>

Try it out and see
------------------

They say a picture is worth a thousand words (I can't stop with the catchphrases, sorry); that’s why I’ve created a demo to show how different typo tolerance configurations can impact the returned search results. **You can test it [here](https://typo-tolerance.meilisearch.com/).**

We will be using [Hakan Özler](https://github.com/ozlerhakan)'s [dataset of books](https://github.com/ozlerhakan/mongodb-json-files/blob/master/datasets/books.json). I made some changes to the original dataset for demo purposes, you can find the [transformed dataset](https://github.com/meilisearch/demos/blob/main/src/typo-tolerance/setup/books.json) on GitHub. You can search a book by its title, [ISBN](https://en.wikipedia.org/wiki/ISBN) (the ID of the book), author, or by the words in its description.

I have created two identical indexes with different typo tolerance settings. One index uses the out-of-the-box typo tolerance settings, whereas the other uses the following:

```JavaScript
const customTypoTolerance = {
    disableOnAttributes: ['isbn'],
    minWordSizeForTypos: {
        oneTypo: 2,
        twoTypos: 4
    }
}
```

Typo tolerance is disabled on `isbn`, and typos are allowed on shorter words: one typo for words that are 2 and 3 characters long, two typos for any longer word.

![Meilisearch returns different search results depending on the typo tolerance configuration for the same query](https://unable-actionable-car.media.strapiapp.com/typo_tolerance_1_gif_c23f105edf.gif)

It's usually better to provide the end-user with some results than with none. That’s why I set the threshold to the [minimum recommended](https://docs.meilisearch.com/learn/configuration/typo_tolerance.html#minwordsizefortypos). Try typing `flx` and see what happens!

Sometimes, however, it is preferable to return only exact matches. For example when searching documents by their unique identifier. The ISBN is precisely that: the ID of a book. Therefore, I disabled the typo tolerance on the `isbn` attribute.

Let’s try to find a book called “Well-Grounded Rubyist” by its ISBN; type `1933988657` into the search bar.

![When searching for an ISBN, Meilisearch returns only one document when typo tolerance has been disabled on the isbn field](https://unable-actionable-car.media.strapiapp.com/typo_tolerance_2_gif_0119353162.gif)

As you can see, we get the desired book with both settings. However, we get more than one result when typo tolerance is enabled. Searching for an invalid ISBN like `1933988676` still returns results when typo tolerance is enabled; this can be confusing and misleading.

Conclusion
----------

I didn’t disable the typo tolerance on any word because I did not deem it necessary given this dataset, did you? If you want to make some modifications and try to get more relevant results, be my guest: you can find [the code on GitHub](https://github.com/meilisearch/demos/tree/main/src/typo-tolerance).

But, if you like real challenges, I've got one for you. [Literal](https://literal.club/), an online platform for book readers, uses Meilisearch to search through bookshelves. They have been kind enough to share the recipe they've been using to deliver relevant search results:

```json
{
   "displayedAttributes":[
      "id",
      "title",
      "workId",
      "authors",
      "categories",
      "popularity"
   ],
   "searchableAttributes":[
      "authors",
      "title",
      "categories"
   ],
   "filterableAttributes":[
      "isbn10",
      "isbn13",
      "language"
   ],
   "distinctAttribute":"workId",
   "rankingRules":[
      "words",
      "typo",
      "popularity:desc",
      "proximity",
      "attribute",
      "sort",
      "exactness"
   ]
}

```

Can you come up with a better configuration? Can you think of the perfect typo tolerance settings to enhance the relevancy?

As you may have noticed, we take user feedback very seriously. Please don’t hesitate to check our [public roadmap](https://roadmap.meilisearch.com/) and upvote for any feature you'd like to see in future versions or submit a new feature idea. You can also check our [product repo](https://github.com/meilisearch/product/discussions) and make a suggestion or join an existing discussion on improving the product.

If you like Meilisearch and want to support us, a star on [GitHub](https://github.com/meilisearch/meilisearch) means a lot 🥰

Take control of Meilisearch's typo tolerance

This tutorial will show you how to integrate Meilisearch with Strapi v4 to create a search-based web app. We are going to use Strapi’s quick start guide to create a restaurant collection, and then use Meilisearch to search through our collection data.

Introducing our tools
---------------------

### What is Strapi?

[Strapi](https://strapi.io/) is a headless CMS. It provides a quick way to create a back-end where we can add and store data. The data is then available through a REST or GraphQL API without having to code anything or configure our database.

### What is Meilisearch?

[Meilisearch](https://meilisearch.org.cn/docs/learn/what_is_meilisearch/overview#what-is-meilisearch) is a fast, open-source search engine that's easy to use and deploy. The aim of Meilisearch is to create an out-of-the-box relevant search experience in very few steps, with no configuration needed.

Pre-requisites for integrating Meilisearch and Strapi
-----------------------------------------------------

To be able to follow this tutorial on Strapi and Meilisearch integration, you'll need the following:

*   An open [terminal or command prompt](https://www.ionos.com/help/email/troubleshooting-mail-basicmail-business/access-the-command-prompt-or-terminal)
*   [Node.js](https://node.org.cn/en/download/) {">= 14 <= 18"}
*   NPM and NPX (v6 only) (installed with Node.js): package managers that help you access and use JS libraries

Create a directory for our app
------------------------------

Let’s create a directory called `my-app` where we will add our back and front-end parts of the application.

```bash
mkdir my-app
cd my-app

```

Create a back-end using Strapi
------------------------------

Our first step is to generate a back-end API using Strapi. Go to your open terminal window and run the following command:

```bash
npx create-strapi-app@latest back --quickstart

```

This command creates a Strapi app in a new directory called `back` and opens the admin dashboard. Create an account or log in so that you have access to it.

![Strapi signup form](https://unable-actionable-car.media.strapiapp.com/Capture_d_e_cran_2022_04_08_a_11_27_18_1_3e4dd92cf4.png)

Once you have created your account, you should be redirected to Strapi's admin dashboard. This is where we will configure our back-end API.

Our next step is to create a new collection type. A collection is like a blueprint of your content—in this case, it'll be a collection of restaurants. We will create another collection called "Category" to organize our restaurants later.

![Strapi dashboard with side menu 'Content-Type Builder' option circled](https://unable-actionable-car.media.strapiapp.com/Capture_d_e_cran_2022_04_08_a_11_34_17_2_1_2b9259cf7e.png)

To follow along, complete the first 4 steps of "Part B: Build your content" from [Strapi's quick start guide](https://docs.strapi.io/developer-docs/latest/getting-started/quick-start.html). These will include:

*   creating collection types
*   creating new entries
*   setting roles & permissions
*   publishing the content

After finishing step 4 of Strapi's quick start guide, two new collections named `Restaurant` and `Category` should have appeared under `Content Manager` > `Collection Types`. If we click on `Restaurant`, we can see that there is only one. Let's add more by clicking the `+ Create new entry` button in the upper-right corner of the dashboard!

![Strapi dashboard: Content manager side menu, arrow indicating the location of the Restaurant Collection Type ](https://unable-actionable-car.media.strapiapp.com/Capture_d_e_cran_2022_04_08_a_18_27_41_copie_1_1_70c8af5070.png)

We’ll add three restaurants, one by one. For each restaurant, you need to press `Save` and then `Publish`.

*   Name: `The Butter Biscotte.` Description: `All about butter, nothing about health.`  
    Let’s add the `French food` category on the bottom right corner of the page 👇

![Strapi dashboard: create an entry form, arrow indicating the location of the categorie's location in the right side menu](https://unable-actionable-car.media.strapiapp.com/Capture_d_e_cran_2022_04_08_a_18_33_44_2_9695c0fc90.png)

Name: `The Slimy Snail` Description: `Gastronomy is made of garlic and butter.` Category: `French food`

Name: `The Smell of Blue` Description: `Blue Cheese is not expired, it is how you eat it. With a bit of butter and a lot of happiness.` Category: `French food`

Once the three restaurants have been added, you should end up with the following page:

![Strapi dashboard: list of the existing restaurant entries in the Restaurant Collection Type page](https://unable-actionable-car.media.strapiapp.com/Capture_d_e_cran_2022_04_08_a_18_42_35_1_0d0b1abef2.png)

Our Strapi back-end is now up and running! Strapi automatically creates a REST API for our `Restaurants` collection. Check out Strapi's documentation for all available [API endpoints](https://strapi.io/documentation/developer-docs/latest/developer-resources/content-api/content-api.html#api-endpoints).

Now, it's time to bring Meilisearch into the mix.

Install and launch Meilisearch
------------------------------

To integrate Meilisearch into our Strapi-based web app, you first need to install Meilisearch. There are multiple ways to [download and run a Meilisearch instance](https://meilisearch.org.cn/docs/learn/getting_started/installation#download-and-launch), we will be using [Docker](https://docker.net.cn/) here.

If you want to avoid a local installation, **[try Meilisearch Cloud](https://meilisearch.org.cn/pricing)**, a hosted and fully‑managed version of Meilisearch with a **free** 14-day trial, **no credit card required**.

**Open a second terminal window** and move to the `my-app` directory. This window will be used to run Meilisearch. Execute the command below to download and [install Meilisearch with Docker](https://meilisearch.org.cn/docs/learn/cookbooks/docker). If Docker doesn't work for you, consider trying one of the [many other methods](https://meilisearch.org.cn/docs/learn/getting_started/installation#download-and-launch).

```bash
# Fetch the latest version of Meilisearch image from DockerHub
docker pull getmeili/meilisearch:latest

# Launch Meilisearch
docker run -it --rm \
    -p 7700:7700 \
    -e MEILI_ENV='development' \
    -v $(pwd)/meili_data:/meili_data \
    getmeili/meilisearch:latest

```

You should see a big chunk of text (including some ASCII art) confirming that Meilisearch is up and running.

![Meilisearch startup message, arrow pointing the location of the address](https://unable-actionable-car.media.strapiapp.com/Screenshot_2023_02_23_at_15_02_41_e904f789b5.png)

Find the line titled `Server listening on`. This lets us know where Meilisearch is being served. Once you've found it, open this address in your browser.

![Meilisearch search preview, aka, mini-dashboard](https://unable-actionable-car.media.strapiapp.com/Screenshot_2023_02_23_at_15_08_38_b0c8b8b2a8.png)

This is the Meilisearch [search preview](https://meilisearch.org.cn/docs/learn/what_is_meilisearch/search_preview). It will remain empty until we add some data to our Meilisearch instance.

It’s time to connect Strapi and Meilisearch and start searching through our data.

Connect Strapi and Meilisearch
------------------------------

In order to add the Meilisearch plugin to Strapi, we need to quit our Strapi app. Go to the terminal window running Strapi (_make sure it's not the one running Meilisearch!_) and push `Ctrl+C` to kill the process.

Once you've done that, install the plugin in the `back` directory.

```json
cd back
npm install strapi-plugin-meilisearch

```

After the installation, we have to rebuild our Strapi app before starting it again in development mode, since it makes configuration easier.

```json
npm run build
npm run develop

```

At this point, our Strapi app should be running once again on the default address: [http://localhost:1337/admin/](http://localhost:1337/admin/). Visiting it in your browser, you should see an admin sign-in page; enter the same credentials as before.

Once connected, you should see the new `meilisearch` plugin on the left side of the screen.

![Strapi dashboard with plugins side menu: arrow pointing at the 'meilisearch' option](https://unable-actionable-car.media.strapiapp.com/Capture_d_e_cran_2022_04_08_a_19_01_53_1_a30c95c406.png)

To add your Meilisearch credentials, click on the `Settings` tab on the meilisearch plugin page so that Strapi knows where to send our data.

For example, using the credentials from the **Launch and start Meilisearch** section above, add the address serving Meilisearch in the `Meilisearch Host` field, then click the `Save` button.

![Strapi dashboard with Meilisearch plugin selected: arrow pointing to the location of the settings tab](https://unable-actionable-car.media.strapiapp.com/Screenshot_2023_02_23_at_15_30_11_c882741ba9.png)

Note that we leave `Meilisearch API Key` blank because we launched Meilisearch without a [master key](https://meilisearch.org.cn/docs/learn/configuration/instance_options#master-key).

Now it's time to add your Strapi collection to Meilisearch. In the `Collections` tab on the `meilisearch` plugin page, you should see the `restaurant` and `category` content-types.

By clicking on the checkbox next to `restaurant`, the content-type is automatically indexed in Meilisearch.

![GIF showing the mouse clicking on 'restaurant' in the Meilisearch collections tab](https://unable-actionable-car.media.strapiapp.com/strapi_gif_ce383289e9.gif)

As you can see in the GIF above, the word “Hooked” appears when you click on the restaurant's checkbox in the `Collections` tab. This means that each time you add, update or delete an entry in your restaurant content-types, Meilisearch is automatically updated!

Once the indexing finishes, your restaurants are in Meilisearch. We can now go back to our Meilisearch host address: [http://localhost:7700](http://localhost:7700). After refreshing, you should observe that the page is no longer empty. Try typing “butter” in the search bar and see what happens 😉

![GIF showing the word 'butter' being typed in the search bar and search results appearing instantly](https://unable-actionable-car.media.strapiapp.com/butter_1_72fa85eb2f.gif)

As you can see, your Strapi entries are sent to Meilisearch as is. You can modify the data before sending it to Meilisearch, for instance by removing a field. Check out all the customization options on the [strapi-plugin-meilisearch](https://github.com/meilisearch/strapi-plugin-meilisearch/#-customization) page.

Next steps after integrating Strapi and Meilisearch
---------------------------------------------------

Now that you have successfully added your Strapi collections in Meilisearch, you can start using the [search capabilities](https://meilisearch.org.cn/docs/learn/what_is_meilisearch/overview#features) to their full extent.

Learn how to [set up instant-meilisearch](/blog/instant-meilisearch/ to integrate a search-as-you-type experience into your front end in no time at all!

If you have any questions about integrating Meilisearch with Strapi, please join us on [Discord](https://discord.gg/meilisearch). If you like Meilisearch, [a star on GitHub](https://github.com/meilisearch/meilisearch) means a lot.

How to integrate a relevant search into Strapi v4 using Meilisearch

### \***\*What is multitenancy?\*\***

In software development, multitenancy means that multiple users - also called tenants - share the same computing resources but have different access to system-wide data. In Meilisearch, you might have one index containing data belonging to many distinct tenants. In such cases, your tenants must only be able to search through their own documents.

You can achieve this using tenant tokens.

### **Tenant Token**

Tenant tokens are small packages of encrypted data presenting proof a user can access a certain index. They contain security credentials and instructions on which documents within that index the user is allowed to see.

The primary use case for tenant tokens is to enforce restrictions based on user permissions.

A user can generate a tenant token using [Meilisearch SDKs](https://docs.meilisearch.com/learn/security/tenant_tokens.html#generating-tenant-tokens-with-an-sdk) or [custom code](https://docs.meilisearch.com/learn/security/tenant_tokens.html#generating-tenant-tokens-without-a-meilisearch-sdk).

**Tenant tokens** do not require you to configure any specific instance options or index settings. They are also meant to be short-lived—Meilisearch does not store nor keep track of generated tokens.

When using an SDK to generate a tenant token, you need four parameters:

- **Search rules**: Search rules are a set of instructions defining search parameters that will be enforced in every query made with a specific tenant token.
- **API key**: A token has access to the same indexes as the API key used to generate it.
- **API key uid**: The uid of the API key used to generate the token allows checking that the API key used is valid.
- **Expiration date**(optional): The expiration date of the tenant token

You can read more about the tenant token payload in the [documentation](https://docs.meilisearch.com/learn/security/tenant_tokens.html#tenant-token-payload-reference).

### \***\*Requirements\*\***

1.  [Node.js](https://node.org.cn/en/download/)
2.  [npm](https://npmjs.net.cn/)
3.  [Meilisearch JavaScript SDK](https://github.com/meilisearch/meilisearch-js)

### \***\*Creating a tenant token\*\***

A **tenant token** can be created using the `generateTenantToken` function available in the Meilisearch Javascript SDK.

Here’s a simple example for creating a **tenant token** using the Meilisearch SDK

```jsx
client = new Meilisearch({
  host: "<http://localhost:7700>",
  apiKey: "masterKey",
});
// We have created a Meilisearch instance in JavaScript and we will use this to create the tenant token.

const apiKey =
  "rkDxFUHd02193e120218f72cc51a9db62729fdb4003e271f960d1631b54f3426fa8b2595";
const apiKeyUid = "85c3c2f9-bdd6-41f1-abd8-11fcf80e0f76";
const expiresAt = new Date("2025-01-01");
// Now we have declared the API Key, its uid, as well as the expiration date for the token.

searchRules = {
  "*": {
    filter: "user_id = 1",
  },
};
// Here we have defined the search rules that will apply restrictions on the search results.

tenantToken = client.generateTenantToken(apiKeyUid, searchRules, {
  expiresAt: expiresAt,
  apiKey: apiKey,
});
// Now the generateTenantToken function will create a tenant token and Meilisearch can validate this token with the apiKey.
```

When Meilisearch gets a search query with a tenant token, it decodes it and applies the search rules to the search request.

### **Application Usage**

Let's say we have a medical record system in a Meilisearch instance with the `patient_medical_record` index. This index contains a list of patients along with their details. We can use tenant tokens to restrict access to this data.

Sample dataset:

```json
[
  {
    "patient": "John",
    "description": "John is in room number 2 and is suffering from Covid",
    "roomNumber": 1,
    "isDoctorAppointed": true
  },
  {
    "patient": "Zia",
    "description": "Zia is in room number 3 and is suffering from Dengue",
    "roomNumber": 2,
    "isDoctorAppointed": true
  },
  {
    "patient": "Kevin",
    "description": "Kevin is in room number 4 and is suffering from Typhoid",
    "roomNumber": 3,
    "isDoctorAppointed": false
  }
]
```

In the above dataset, we have three patients: John, Zia, and Kevin. The aim is to restrict Zia from accessing Kevin and John's data. To achieve this, we need to create a **tenant token** for her with a set of search rules.

For this case, the search rules can be specified as:

```jsx
"searchRules": {
      "patient_medical_record": {
          "filter": "patient = Zia"
      }
  }
```

Zia's tenant token will be applied at the time of the search request, which returns:

```json
[
  {
    "patient": "Zia",
    "description": "Zia is in room number 3 and is suffering from Dengue",
    "roomNumber": 2,
    "isDoctorAppointed": true
  }
]
```

This is a simple use case, but we can modify the rule to meet more complex requirements.

### \***\*Integrating the multitenancy feature in your application\*\***

We will use the above example to create an [application](https://tenant-token.meilisearch.com/) for displaying patients in a Meilisearch index. We will then use multitenancy to restrict access to this data.

1.  **Download the application**

    Clone the boilerplate code for the demo application from the Meilisearch tutorials repository on Github.

    Use the following command:

```bash
git clone https://github.com/meilisearch/tutorials

```

    The boilerplate code exists in the `src/tenant-token-tutorial` directory.

```bash
cd src/tenant-token-tutorial

```

    This code contains a frontend application built in `React.js` and a backend server in `Express.js/Node.js`.

2.  **Start Meilisearch**

    There are multiple ways to [download and run a Meilisearch instance](https://docs.meilisearch.com/learn/getting_started/quick_start.html#download-and-launch). The easiest way to run a Meilisearch instance is using [Meilisearch Cloud](https://cloud.meilisearch.com/), there's a free 14-day trial, no credit card required. Meilisearch is open-source, in this demo, we'll run it locally using Docker:

```bash
   docker pull getmeili/meilisearch:v1.0


   docker run -it --rm \
       -p 7700:7700 \
       -e MEILI_MASTER_KEY='masterKey'\
       -v $(pwd)/meili_data:/meili_data \
       getmeili/meilisearch:v1.0 \
       meilisearch --env="development"
```

    _Don't forget to define a [master key](https://docs.meilisearch.com/learn/security/master_api_keys.html#protecting-a-meilisearch-instance) as shown above when launching Meilisearch. It will create the API keys needed to generate the tenant tokens._

    The Meilisearch instance will run on the IP address: `http://localhost:7700`.

3.  **Adding data to Meilisearch**

    There is a `data.json` file in the `seed` folder of the base directory with a list of 10 patients suffering from multiple conditions with 100 entries, each with a room number and some patient details. We'll enter the information into Meilisearch.

    Change the terminal directory to the `seed` folder and add the given data to the Meilisearch instance, using the following command:

```bash
npm install     #  This command will install node dependencies

npm start         # This command will add all the data from data.json to Meilisearch

```

4.  **Start frontend server**

    Navigate to the `frontend` folder, and install all the application dependencies, and Meilisearch Javascript SDK

```bash
npm install                # To install all the react application dependency

npm install meilisearch    # To install the Meilisearch SDK

```

    It can take a while to install all the dependencies of the project.

    Let's get the frontend React server up and running with the command:

```jsx
npm start

```

    The app will run on the IP address: `http://localhost:3000`.

![drawing](https://unable-actionable-car.media.strapiapp.com/tenant2_4cce8f78f6.png)

1.  **Adding the functionality to create tenant tokens**

    Navigate to the `backend` folder and install all dependencies using the following command:

```jsx
npm install

```

    In the `backend` folder, open the `index.js` file. It contains the APIs' route and logic.

    An endpoint is already defined for generating the **Tenant token**:

```jsx
app.get("/create-tenant-token", async (req, res) => {
  const { value: patientName } = req.query;

  /* Add functionality to create Tenant token */
});
```

    Now, we'll add the functionality below the comment in the function.

    We need an API Key, search rules, and an expiration date to generate a tenant token.

    The API Key can be obtained from the `getKeys` method in the Javascript SDK. The `getKeys` method returns a list of API Keys from which we can select one to use in the **tenant token** generation process. To do so, add the following code to the API method stated above:

```jsx
const { results } = await client.getKeys();
const apiKey = results.filter(
  (res) => res.name === "Default Search API Key"
)[0].key;
const apiKeyUid = results.filter(
  (res) => res.name === "Default Search API Key"
)[0].uid;
```

    We can also use the `createKey` function to generate a new API Key.

    You can read more on API keys in the [Meilisearch documentation](https://docs.meilisearch.com/reference/api/keys.html).

    By specifying search rules, we can now generate a payload. Use the following code to define a payload:

```jsx
const payload = {
  patient_medical_record: {
    filter: `patient = ${patientName}`,
  },
};
```

    If we need the token to expire after a year, we can set an expiration date when creating the token, as shown below.

```jsx
const expiresAt = new Date(
  new Date().setFullYear(new Date().getFullYear() + 1)
);
```

    To generate the token, we can now use the `generateTenantToken` function from the Meilisearch Javascript SDK, and return the generated token using `res.json(`) function.

```jsx
const tenantToken = client.generateTenantToken(apiKeyUid, payload, {
  apiKey,
  expiresAt,
});

return res.json({ token: tenantToken });
```

    This is how the endpoint should be implemented:

```jsx
app.get("/create-tenant-token", async (req, res) => {
  const { value: patientName } = req.query;

  /* Add functionality to create Tenant token */
  const { results } = await client.getKeys();
  const apiKey = results.filter(
    (res) => res.name === "Default Search API Key"
  )[0].key;
  const apiKeyUid = results.filter(
    (res) => res.name === "Default Search API Key"
  )[0].uid;

  const payload = {
    patient_medical_record: {
      filter: `patient = ${patientName}`,
    },
  };

  const expiresAt = new Date(
    new Date().setFullYear(new Date().getFullYear() + 1)
  );

  const tenantToken = client.generateTenantToken(apiKeyUid, payload, {
    apiKey,
    expiresAt,
  });

  return res.json({ token: tenantToken });
});
```

    The frontend requested endpoint will look like this:

```bash
http://localhost:5001/create-tenant-token?value=John

```

    A payload containing the search rules is created using the value `John` from the API.

    Let's use the `npm start` command to start the express API server. The server will run at `http://localhost:5001.`

2.  **Connect your APIs with the Frontend code**

    Enter the patient's name in the text box. On submitting the input form, an API call is sent to the backend, which should return a tenant token. We can pass this token to the Meilisearch instance when we need data on a certain patient.

    The frontend code must now be configured to request a tenant token from the server. We'll use the [axios library](https://npmjs.net.cn/package/axios) to get the token from the `/create-tenant-token` API that we've developed, and we'll pass the patient name in the API's params.

    Open the file `index.js` in the `/src/utils` folder and look for the `getTenantToken` function. This function makes a request to the server and receives a tenant token back.

    Add the following code to the getTenantToken method:

```jsx
export const getTenantToken = async (patientName) => {
  const response = await axios({
    url: `${apiHost}/create-tenant-token`,
    method: "GET",
    params: {
      value: patientName,
    },
  });

  return response.data.token;
};
```

3.  **Test out the implemented functionality**

    Let's test the implementation; start by clicking the **`Create a Tenant token`** button.

    ![drawing](https://unable-actionable-car.media.strapiapp.com/tenant1_b0077452fb.png)

    Type the name `Kevin` in the given text box, and click **`Create a Tenant token` button**. This generates the tenant token.

    ![meili-create-token](https://unable-actionable-car.media.strapiapp.com/meili_create_token_76fc8c30f6.gif)

    Meilisearch will get data based on the tenant token provided by the patient, acting as an authenticator in the process.

### Conclusion

We have restricted access to medical records based on the names of the patients. Using Meilisearch's multitenancy capabilities, we were able to execute all of this with ease. This is a pretty basic use case scenario that comes to mind. The functionality can be as complex as you want it to be. For example, we can implement multitenancy in an e-banking application where the central authority is the bank and the customers are tenants having access to distinct bank accounts.

If you have any questions, please join us [on Discord](https://discord.gg/meilisearch). For more information on Meilisearch, check out our [Github repository](https://github.com/meilisearch/meilisearch/) and our official [documentation](https://docs.meilisearch.com/).


How to use Meilisearch in your multi-tenant application

[Nikita](https://nikita.js.org/current/guide/tutorial/) is a Node.js toolkit for automating deployment workflows. Even though we think it is great, we noticed Nikita's documentation website doesn’t really give users a way to quickly search and find the information they’re looking for. Nikita's content is open source and the documentation website is built with Gatsby, though, so we decided to take the opportunity to show you how to add a nice search interface to a Gatsby-based project.

In this tutorial we will install Meilisearch together with a few other dependencies. Then, we will clone Nikita’s Gatsby repository and index Nikita’s docs with Meilisearch. Finally, we’ll add a search UI to our local version of Nikita’s docs.

You can check the finalized code, including all content ready to be run in a server, [at this github repo](https://github.com/meilisearch/demos/tree/main/src/gatsby-plugin-guide).

Setup
=====

Before we begin, let’s take a quick look at everything you need to follow this tutorial.

Introducing our Tools
=====================

Gatsby
------

[Gatsby](https://www.gatsbyjs.com/) is a React-based open-source framework used for Static Site Generation (SSG). It combines the functionality of React, GraphQL and Webpack and provides great performance, scalability, and security right out of the box.

Requirements
============

To be able to follow this tutorial, you'll need the following:

*   An open [terminal or command prompt](https://www.ionos.com/help/email/troubleshooting-mail-basicmail-business/access-the-command-prompt-or-terminal)
*   [Node.js](https://node.org.cn/en/download/) {">= 14.15.X and <= 16.X"}: this makes it possible to run JS outside a browser
    *   You can check your active version with the command `node --version`
    *   If your version of Node is outside this range, we recommend that you [install nvm](https://github.com/nvm-sh/nvm/blob/master/README.md#about) and use it to access Node 14
*   Yarn >= 1.22 : Yarn is a package manager that doubles down as project manager
*   [Docker](https://docker.net.cn/): Docker will help us create a working development environment with relatively little effort

Steps
=====

1.  Start Meilisearch
2.  Setup the Gatsby project
3.  Add the Meilisearch plugin
4.  Add the content of the Gatsby app to Meilisearch
5.  Build the frontend

Start Meilisearch
=================

There are multiple ways to [download and run a Meilisearch instance](https://meilisearch.org.cn/docs/learn/getting_started/installation#download-and-launch). For this guide, we'll be using Docker. Want to avoid a local installation? Try our [Meilisearch cloud](https://cloud.meilisearch.com/) with a free 14-day trial!

After installing Docker in your machine, fetch and run the latest Meilisearch container image. To do that, open your terminal and use the following commands:

```bash
docker pull getmeili/meilisearch:latest 

docker run -it --rm -p 7700:7700 getmeili/meilisearch:latest ./meilisearch --master-key=masterKey

```

Meilisearch will start running on [http://localhost:7700](http://localhost:7700/). If everything went well, you should see something like this in your terminal window:

![Screenshot-2023-04-13-at-14.48.31](https://unable-actionable-car.media.strapiapp.com/Screenshot_2023_04_13_at_14_48_31_d715bb8f41.png)

Setup the Gatsby project
========================

With Meilisearch ready, it’s time to download Nikita’s documentation.

In another terminal window, navigate to your working directory, then clone the Nikita project that we will be using for this guide:

```bash
git clone https://github.com/adaltas/node-nikita.git

```

You can find the content of the Gatsby app in the markdown files inside the `docs/content` folder. This is the data Gatsby uses to generate Nikita’s documentation.

| _Directory structure for the node-nikita project_ |

Add the Meilisearch plugin and launch Gatsby
============================================

Alright: both Meilisearch and Gatsby are installed. We will start by installing all the project dependencies. Run the following command in your terminal:

```bash
cd node-nikita/docs/website
yarn

```

Once that is done, we will install the official Meilisearch plugin for Gatsby with Yarn:

```bash
yarn add gatsby-plugin-meilisearch

```

Great! We’re ready to launch Gatsby. To do that, just run the following command on your console:

```bash
yarn develop

```

This is how the UI of the Nikita docs website looks like:  
![nikita1](https://user-images.githubusercontent.com/19529592/161043477-afd719ab-fe45-4f1a-ae0b-5f27e4983df6.jpg)

Add the content of the Gatsby app to Meilisearch
================================================

Now that we have installed the plugin and have both the Gatsby app and the Meilisearch instance running, things start to get interesting! Let's configure `gatsby-meilisearch-plugin` to make the content searchable.

The main code for the docs website lies in the directory `docs/website`.

**Configure the plugin**
------------------------

The first thing we need to do is add your Meilisearch [credentials](https://meilisearch.org.cn/docs/learn/getting_started/quick_start#securing-meilisearch) to the Meilisearch Gatsby plugin. Open `docs/website/gatsby-config.js` and add this bit of code at the bottom of the `plugins` array:

```jsx
{
    resolve: 'gatsby-plugin-meilisearch',
    options: {
      host: 'http://localhost:7700', // your host URL goes here
      apiKey: 'masterKey',   // your API key goes here       
      indexes: [],
    },
  },

```

So far, our configuration tells the plugin where to find our Meilisearch instance and gives it the credentials to read the content inside Gatsby. Now we need to define what data we want to add to Meilisearch and how. This happens in the [indexes field](https://github.com/meilisearch/gatsby-plugin-meilisearch#-indexes). This field can be considered the heart of the Gatsby Meilisearch plugin.

The `indexes` field is an array composed of multiple index objects. Each index object must contain the following fields: `indexUid`, `query`, and `transformer`. Let's examine these fields.

### `indexUid`

This field contains the name of a Meilisearch index. For this guide, we will use `nikita-api-docs`:

```jsx
indexUid: 'nikita-api-docs'

```

### `query`

This field contains the GraphQL query the plugin will use to fetch content from Nikita’s documentation. Gatsby comes with inbuilt support for GraphQL—it even includes a bundled GraphQL tool, accessible on ([http://localhost:8000/\_\_\_graphql](http://localhost:8000/___graphql)). You can read more about GraphQL on the project’s official [documentation.](https://graphql.net.cn/learn/)

Our query looks like this.

```jsx
query: `query MyQuery {
    allMdx {
      edges {
        node {
          frontmatter {
            title
            navtitle
            description
          }
          slug
          rawBody
          id
        }
      }
    }
  }`,

```

In this query, we first say we are only interested in the markdown files by wrapping our query with the `allMdx` statement. We can do that thanks to two very useful tools: `gatsby-plugin-mdx` and `gatsby-source-filesystem`.

Then, we specify which document fields we want to include in our index: `title`, `navtitle`, `description`, `slug`, `id`, and, finally, `rawBody`—that is, the document’s raw markdown content.

### `transformer`

This is the last configuration field. It gets the data we fetched from Gatsby with our `query` and converts it into a format that Meilisearch will understand.

In our case, the data will look a bit like this:

```jsx
data = {
    allMdx: {
        edges: [
          {
            node: {
              frontmatter: {
                title: "Introduction",
                navtitle: "intro",
              },
              body: "Introduction to the Nikita.js",
              slug: "/introduction",
              id: "1",
            },
          },
          {
            node: {
              frontmatter: {
                title: "Architecture",
                navtitle: "architecture",
              },
              body: "Architechture of Nikita.js",
              slug: "/architecture",
              id: "2",
            },
          },
        ],
    },
};

```

This data looks great, but is not in a format that Meilisearch can easily understand. We can change that by adding a parser function to `transformer`:

```jsx
transformer: (data) => {
    data.allMdx.edges.map(({ node }) => {
      // Node property has been destructured here
      return {
        id: node.id,
        lvl0: node.frontmatter.title,
        lvl1: node.frontmatter.navtitle,
        content: node.body,
        anchor: node.slug,
      };
    });
}


```

With that, `gatsby-plugin-meilisearch` will get the raw data we extract with our query and turn the whole object into an array.

```jsx
 // It will return a list of transformed structured object
  
[
    {
      id: "1",
      lvl0: "Introduction",
      lvl1: "introduction",
      content: "Introduction to the Nikita.js",
      anchor: "/introduction"
    },
    {
      id: "2",
      lvl0: "Architecture",
      lvl1: "architecture",
      content: "Architechture of Nikita.js",
      anchor: "/architecture"
    }
]

```

### Putting it all together and finalizing plugin configuration

If you’ve been following along, the `gatsby-plugin-meilisearch`configuration at the end of your `docs/website/gatsby-config.js` should look something like this now:

```jsx
{
  resolve: 'gatsby-plugin-meilisearch',
  options: {
    host: 'http://localhost:7700',
    apiKey: 'masterKey',
    batchSize: 1,
    indexes: [
      {
        indexUid: 'nikita-api-docs',
        settings: {
          searchableAttributes: ['lvl0', 'lvl1', 'lvl2', 'content'],
        },
        transformer: (data) =>
          data.allMdx.edges
            .filter(
              ({ node }) =>
                node.slug.search('guide') !== -1 ||
                node.slug.search('project') !== -1 ||
                node.slug.search('api') !== -1
            )
            .map(({ node }) => {
              // Have to update for versioning
              const currentVersion =
                node.slug.substring(0, 8).search('project') === -1
                  ? '/current'
                  : ''

              return {
                id: node.id,
                lvl0:
                  node.frontmatter.navtitle || node.frontmatter.title || '',
                lvl1:
                  node.frontmatter.title || node.frontmatter.navtitle || '',
                lvl2: node.frontmatter.description || '',
                content: node.rawBody,
                url: `${currentVersion}/${node.slug}`,
              }
            }),
        query: `query MyQuery {
            allMdx {
              edges {
                node {
                  frontmatter {
                    title
                    navtitle
                    description
                  }
                  slug
                  rawBody
                  id
                }
              }
            }
          }`,
      },
    ],
  },
},
```

We began `gatsby-plugin-meilisearch` configuration by adding basic data and credentials to `docs/website/gatsby-config.js.`

We continued configuration by specifying the content we want to search should be added to the `nikita-api-docs` index, used a GraphQL query to select content for indexation, and finally used a `transformer` function to format the data for indexation.

**Build the project**
---------------------

The `gatsby-plugin-meilisearch` will fetch and send data for indexation to Meilisearch during the build process. To get that started, run the following command:

```bash
yarn build

```

You should see a message in the terminal once your content is being indexed:

```bash
success gatsby-plugin-meilisearch - 0.920s - Documents are send to Meilisearch, track the indexing progress using the tasks uids.

```

You can verify this by going to [http://localhost:7700](http://localhost:7700), entering your API key, and checking that Nikita’s documentation has been added to Meilisearch.

Build the frontend
==================

Now that the data is indexed, let’s build the user interface and create a great search experience for our end-users.

For this example, we will use [docs-searchbar.js](https://github.com/meilisearch/docs-searchbar.js). It is a front-end SDK for Meilisearch that provides an easy way of integrating a search bar into our documentation site.

Add the search bar component
----------------------------

Let’s start by installing docs-searchbar.js in the frontend directory of the project.

```markdown
# With Yarn
yarn add docs-searchbar.js

```

With that done, we can import the docs-searchbar module into `website/src/components/shared/AppBar.js` by adding this to the top of the file:

```jsx
import 'docs-searchbar.js/dist/cdn/docs-searchbar.css'

```

Next, we need to add a `useEffect` hook to add the docsSearchBar function to `AppBar.js`. Add this below the other `useEffect` hook:

```jsx
useEffect(() => {
    if(window !== undefined){
      const docsSearchBar = require('docs-searchbar.js').default

      docsSearchBar({
        hostUrl: 'http://localhost:7700',
        apiKey: 'masterKey',
        indexUid: 'nikita-api-docs',
        inputSelector: '#search-bar-input',
        meilisearchOptions: {
          limit: 5,
        },
        enhancedSearchInput: true,
      })
    }
  }, [])

```

The `docsSearchBar` function comes in with a number of different parameters:

*   `hostUrl` and `apiKey` allows the search bar to access your Meilisearch instance.
*   `indexUid` tells the search bar which index it should search through.
*   `inputSelector`is a selector matching the HTML element where our users will type their queries. In our case, that’s `#search-bar-input`. Don’t worry, we’ll add this element to Gatsby in a moment.
*   Finally, `enhancedSearchInput` tells `docs-searchbar` to apply a theme to the search box, improving its appearance and making it a bit more user-friendly.

All that’s left is adding our search element in `website/src/components/shared/AppBar.js`. Remember to use the same `id` we configured as the `inputSelector`. Add the element after `</Link>` tag:

```jsx
<input type="search" id="search-bar-input" />

```

And that’s it! We’re done!

**Test the implementation**
---------------------------

Ready to see all this hard work in action? On your terminal, re-run the following command:

```markdown
yarn develop

```

And then use your browser to access [`http://localhost:8000`](http://localhost:8000/). You should see your local copy of NikitaJS’s docs with a brand new search bar:

![nikitalfinall](https://user-images.githubusercontent.com/19529592/161043686-a34453b0-e155-4f03-8ba2-2a9225190757.jpg)

Conclusion
==========

We hope this article was a pleasant introduction to the new [Meilisearch plugin for Gatsby](https://github.com/meilisearch/gatsby-plugin-meilisearch)!

If you have any questions, please join us [on Discord](https://discord.gg/meilisearch). For more information on Meilisearch, check out our [Github repository](https://github.com/meilisearch/meilisearch/) and our official [documentation](https://docs.meilisearch.com/).

Add a search bar to your Gatsby project using Meilisearch

If you haven't heard it yet, [Meilisearch v0.22](/blog/whats-new-in-v0-22/)s out, and it comes with a highly requested new feature: sorting at search time.

Search-time sorting is when results are sorted according to parameters decided at query time. By default, Meilisearch orders results according to their [relevancy](https://meilisearch.org.cn/docs/learn/core_concepts/relevancy), but you can configure it to let users decide at search time what results they want to see first.

Let me show you how powerful this feature is. If I wanted to search for a MacBook and sort the results by ascending price, I would send the following query:

```json
curl \
  -X POST 'http://localhost:7700/indexes/computers/search' \
  --data '{
    "q": "MacBook",
    "sort": [
        "price:asc"
    ]
}'

```

I could do the opposite and search by descending price. I would just need to replace `asc` by `desc` in my request.

The old way
-----------

Before Meilisearch v0.22, you could only sort search results using the [custom ranking rules](https://meilisearch.org.cn/docs/learn/core_concepts/relevancy#custom-rules).

Thanks to the custom ranking rules, we could have our search results sorted by the numeric attribute of our choice. However, the sorting was not at search time, the sorting order was decided in our index settings.

To change the sort order of the search results in the user interface, we had to duplicate the index and set different custom ranking rules for each index.

That's what I did for our [MoMA demo](https://moma.meilisearch.com/) a few months ago. For those who missed it, the MoMA demo is a Meilisearch demo created with the artworks dataset of the [Museum of Modern Art](https://www.moma.org/) available in their [GitHub repository](https://github.com/MuseumofModernArt/collection). You can learn more about the demo in [this blog post](/blog/demo-moma/) wanted the users to be able to sort the artworks by date, so I had to create three indexes:

\-  `artWorks` with the default built-in ranking rules  

\- `artWorksAsc` with a custom ranking rule for ascending sort

\- `artWorksDesc` with a custom ranking rule for descending sort

```javascript
// Get or create indexes
const artWorksIndex = await client.getOrCreateIndex('artWorks', { primaryKey: 'ObjectID' })
const artWorksAscIndex = await client.getOrCreateIndex('artWorksAsc', { primaryKey: 'ObjectID' })
const artWorksDescIndex = await client.getOrCreateIndex('artWorksDesc', { primaryKey: 'ObjectID' })

const defaultRankingRules = [
  'typo',
  'words',
  'proximity',
  'attribute',
  'exactness'
] 

const rankingRulesAsc = [
  'typo',
  'words',
  'proximity',
  'attribute',
  'exactness',
  'asc(DateToSortBy)' // ascending sort
]
const rankingRulesDesc = [
  'typo',
  'words',
  'proximity',
  'attribute',
  'exactness',
  'desc(DateToSortBy)' // descending sort
]

```

The duplication, or triplication, gave the impression of sorting at search time as Meilisearch is blazingly fast.

At that time, sorting was on our [roadmap](https://roadmap.meilisearch.com/), in the Under Consideration tab, and it was one of the most voted features (86 votes).

> We have a [public roadmap](https://roadmap.meilisearch.com/) where you can submit feature or integration ideas and vote for the existing ones.

With the new v0.22 sort feature
-------------------------------

Today, it's a reality. And I've updated the demo to integrate this feature. Let's go through what has changed.

### Behind the scenes

First of all, I have added the following line to the settings:

```javascript
sortableAttributes: ['DateToSortBy']

```

This addition is necessary because we need to inform Meilisearch of the attributes we want to use for sorting.

We only need one index (not three) and the default ranking rules. This has considerably reduced the back-end code. You can change the position of the `sort` rule to tune the relevancy of the search results according to your needs. By default, the `sort` rule in 5th position of the ranking rules to promote results relevant to the user's search.

You can learn more about the ranking rules and how they affect relevancy [here](https://meilisearch.org.cn/docs/learn/core_concepts/relevancy).

And if you are curious about why the `sort` rule is in 5th position by default, you can check [this GitHub issue](https://github.com/meilisearch/MeiliSearch/issues/1680#issuecomment-915789791) where our Product Manager explains this choice.

With these modifications, the big block of code above has been reduced to the following line:

```javascript
// Get or create the index
const index = await client.getOrCreateIndex('artWorks', { primaryKey: 'ObjectID' })

```

Easy, right? But, what about the front end?

### In the spotlight

For this demo I used [Vue InstantSearch](https://github.com/algolia/vue-instantsearch/), combined with [Instant Meilisearch](https://github.com/meilisearch/meilisearch-js-plugins/tree/main/packages/instant-meilisearch). This connects the Meilisearch instance with the open-source [InstantSearch](https://github.com/algolia/instantsearch.js) front-end tools allowing us to customize the search environment effortlessly.

The previous code looked like this:

```javascript
<ais-sort-by
:items="[
  { value: 'artWorks', label: 'Featured' },
  { value: 'artWorksAsc', label: 'Date asc.' },
  { value: 'artWorksDesc', label: 'Date desc.' }                    
]"
:class-names="{
    'ais-SortBy': 'MyCustomSortBy'
}"
/>

```

I just needed to transform it into this:

```javascript
<ais-sort-by
:items="[
  { value: 'artWorks', label: 'Featured' },
  { value: 'artWorks:DateToSortBy:asc', label: 'Date asc.' },
  { value: 'artWorks:DateToSortBy:desc', label: 'Date desc.' }                    
]"
:class-names="{
  'ais-SortBy': 'MyCustomSortBy'
}"
/>

```

As you can see, instead of using 3 different indexes (`artWorks`, `artWorksAsc`, and `artworksDesc`), we only need to append the attribute's name to the `artWorks` index followed by the desired sort order, `asc` or `desc`.

```javascript
'artWorks:DateToSortBy:asc'
'artWorks:DateToSortBy:desc'

```

And this is it. Smooth and simple. You can test it [here](https://moma.meilisearch.com/).

![](https://unable-actionable-car.media.strapiapp.com/sortby_a3723cbe47.gif)

Web interface with the query "Magritte" sorting by ascending and then descending date gif

The end-user may not notice the difference, but resource-wise it's much more efficient.

Another great advantage of v0.22 is the new indexer. It's way faster than before, so if you're still using an older version of Meilisearch, I strongly encourage you to [upgrade it](https://meilisearch.org.cn/docs/learn/update_and_migration/updating).

The demo source code is available on [GitHub](https://github.com/meilisearch/demos/tree/main/src/MoMA). I invite you to play with it, you can add other attributes to sort by, as long as they are strings or numeric values. For a more in-depth explanation of sorting, take a look at the [dedicated section](https://meilisearch.org.cn/docs/learn/getting_started/filtering_and_sorting#sorting) of the documentation.

* * *

_Picture by [Héctor J. Rivas](https://unsplash.com/@hjrc33) on [Unsplash](https://unsplash.com/)_

The art of sorting

<Callout>
  This guide is for Strapi v3. If you are using Strapi v4, check [this post](/blog/strapi-v4-plugin-meilisearch/)
</Callout>

As the web evolves, more and more tools are available to take care of complex jobs for us. Why create a CRUD API from scratch when you can generate one in a few clicks? Why struggle with difficult search operations and queries, when simple and efficient solutions exist?

Maybe we're intimidated by new technologies, or concerned about investing time in tools that don't pan out. Or, more likely, _we may not even be aware that a simple solution exists._

![](https://unable-actionable-car.media.strapiapp.com/truemen_d2b99b9b0a.gif)

Meilisearch in action

This tutorial will show you, in the fewest steps possible, how to use Strapi and Meilisearch to create a search-based web-app. First, let's get acquainted with our tools!

Introducing our Tools
---------------------

### Strapi

[Strapi](https://strapi.io/) is a headless CMS. It provides a quick way to create a back-end where we can add and store data. The data is then available through a REST API without having to code anything or configure our database.

### Meilisearch

[Meilisearch](https://meilisearch.org.cn/docs/learn/what_is_meilisearch/overview) is a fast, open-source search engine that's easy to use and deploy. The aim of Meilisearch is to create a relevant search experience out of the box in very few steps and with no configuration needed.

Requirements
------------

To be able to follow this tutorial, you'll need the following:

*   An open [terminal or command prompt](https://www.ionos.com/help/email/troubleshooting-mail-basicmail-business/access-the-command-prompt-or-terminal)
*   [Node.js](https://node.org.cn/en/download/) {">= 10.16 and <= 14"}: this makes it possible to run JS outside a browser
    *   You can check the active version with the command `node --version`
    *   If your version of Node is outside this range, we recommend that you [install nvm](https://github.com/nvm-sh/nvm/blob/master/README.md#about) and use it to access Node 14
*   NPM and NPX >= 6.x (installed with Node.js): package managers that help you access and use JS libraries

Steps:
------

1.  [Create a working directory](#create-a-directory-for-our-app)
2.  [Create Strapi Back End](#create-a-back-end-using-strapi)
3.  [Start Meilisearch](#launch-and-start-meilisearch)
4.  [Connect Strapi and Meilisearch](#connect-strapi-and-meilisearch)
5.  [Conclusion](#conclusion)

Create a directory for our app
------------------------------

We don't want our app to be all over the place! Let's create a directory where we will add every part of our application.

```bash
mkdir my-app
cd my-app
```

If you are not using a [UNIX-based operating system](https://www.eukhost.com/blog/webhosting/linux-flavors/) please follow this guide to [create a directory](https://www.computerhope.com/issues/ch000742.htm).

Create a back end using Strapi
------------------------------

In this section we are going to create and run a back-end using Strapi.

Our first step is to generate a Strapi Application. Go to your open terminal window and run the following command:

```bash
npx create-strapi-app@3.5.4 back --quickstart

```
<Callout>
  Using [npx](https://npmjs.net.cn/package/npx) we run a specific version of the package without installing it globally. Note that this guide may not work with a different version.
</Callout>

This command creates a Strapi app in a new directory called `back` and opens the admin dashboard. Create an account or log in so that you have access.

![](https://unable-actionable-car.media.strapiapp.com/Screenshot_2021_04_20_at_14_28_54_1_453a624ffa.png)

If you lose this page at any time, just go to `http://localhost:1337/admin` in your browser

Once you have created your account, you should be redirected to Strapi's admin dashboard. This is where we will configure our back-end API.

Our next step is to create a new collection type—in this case, it'll be a collection of restaurants. Complete [step 3 of Strapi's quick start guide](https://strapi.io/documentation/developer-docs/latest/getting-started/quick-start.html#_3-create-a-restaurant-content-type) to continue.

![](https://unable-actionable-car.media.strapiapp.com/Screenshot_2021_04_20_at_15_31_41_2effed8eb3.png)

Admin dashboard landing page

After finishing [step 3 of Strapi's quick start guide](https://strapi.io/documentation/developer-docs/latest/getting-started/quick-start.html#_3-create-a-restaurant-content-type), a new collection named `Restaurants` should have appeared under `Collection Types`. If we click on it, we can see that there are still no restaurants. Let's add some!

![](https://unable-actionable-car.media.strapiapp.com/Screenshot_2021_04_20_at_15_07_36_63c48765e5.png)

`Restaurants` collection landing page

Click on `+ Add New Restaurants` in the upper-right corner of the dashboard. Now let's add three restaurants, one by one:

*   Name: `The Butter Biscotte`. Description:  `All about butter, nothing about health.`
*   Name: `The Slimy Snail` Description: `Gastronomy is made of garlic and butter.`
*   Name: `The Smell of Blue` Description: `Blue Cheese is not expired, it is how you eat it. With a bit of butter and a lot of happiness.`

![](https://unable-actionable-car.media.strapiapp.com/Screenshot_2021_04_20_at_15_15_38_2c431c5150.png)

Create an entry in the Restaurant Collection.

For each restaurant, you need to press `save` and then `publish`. Once the three restaurants have been added, you should end up with the following page:

![](https://unable-actionable-car.media.strapiapp.com/Screenshot_2021_04_20_at_15_22_55_e0137d6c9d.png)

Main page of `Restaurants` showcasing the restaurants we have added

Our Strapi back end is now up and running! Strapi automatically creates a REST API for our `Restaurants` collection. Check out Strapi's documentation for all available [API endpoints](https://strapi.io/documentation/developer-docs/latest/developer-resources/content-api/content-api.html#api-endpoints).

Next, it's time to bring Meilisearch into the mix.

Launch and Start Meilisearch
----------------------------

**tl;dr:** [download, install and start Meilisearch](https://docs.meilisearch.com/learn/getting_started/installation.html#download-and-launch).

Want to avoid a local installation? Use our [Meilisearch cloud](https://cloud.meilisearch.com/) free 14-day trial or our [one-click install on DigitalOcean](https://marketplace.digitalocean.com/apps/meilisearch) and [continue to the next section](#connect-strapi-and-meilisearch).

If you made it this far, you should already have an open terminal window running Strapi. If not or if you closed it by accident, please [follow this guide](https://www.ionos.com/help/email/troubleshooting-mail-basicmail-business/access-the-command-prompt-or-terminal), navigate to the directory `.../my-app/back` that we created, and run the command `npm run develop` to restart Strapi.

Let's take a moment to **open a second terminal window** and move to the `my-app` directory. This window will be used to run Meilisearch.

Inside `my-app`, create a new directory called `meilisearch-binary` .

```bash
mkdir meilisearch-binary
cd meilisearch-binary
```

Create and move to directory where we will run Meilisearch

Execute the following command to download Meilisearch in the current directory. If cURL doesn't work for you, consider trying one of the [many other methods to download and install](https://docs.meilisearch.com/learn/getting_started/installation.html#download-and-launch) Meilisearch.

```bash
# Install Meilisearch
curl -L https://install.meilisearch.com | sh
```

Download and install Meilisearch

We now have the `meilisearch` binary in our directory. Let's run it!

```bash
# Launch Meilisearch
./meilisearch
```

Launch Meilisearch

You should see a big chunk of text (including some ASCII art) confirming that Meilisearch is up and running.

![](https://unable-actionable-car.media.strapiapp.com/MS_adress_75a76c4b2b.png)

Running Meilisearch

Find the line titled `Server listening on`. This lets us know where Meilisearch is being served. Once you've found it, open this adress in your browser.

You should arrive on a web page without much to look at.

![](https://unable-actionable-car.media.strapiapp.com/Screenshot_2021_04_21_at_13_21_44_d9162084ee.png)

The Meilisearch web interface w/ empty index

This is the Meilisearch [web interface](https://meilisearch.org.cn/docs/learn/what_is_meilisearch/search_preview). It will remain empty until we add some data to our Meilisearch instance.

Data, you say? It just so happens we already have some in our Strapi app! Time to connect the two and start searching through our data with Meilisearch.

Connect Strapi and Meilisearch
------------------------------

In order to add the Meilisearch plugin to Strapi, we need to quit our Strapi app. Go to the terminal window running Strapi (_make sure it's not the one running Meilisearch!_) and push `control + c` to kill the process.

Once you've done that, move inside the `back` directory and install the plugin.

```json
cd back
npm install strapi-plugin-meilisearch
```

After the installation, we have to rebuild our Strapi app before starting it again in development mode, since it makes configuration easier.

```bash
npm run build
npm run develop
```

At this point, our Strapi app should be running once again on the default address: [`http://localhost:1337/admin/`](http://localhost:1337/admin/) . Visiting it in your browser, you should see an admin sign-in page; enter the same credentials as before.

Once connected, you should see a new `Plugin` on the left side of the screen: Meilisearch! Let's click on it.

![](https://unable-actionable-car.media.strapiapp.com/Screenshot_2021_04_21_at_14_32_44_c00e3d34f8.png)

Arriving on the Meilisearch plugin page, we can see that the information is split into two sections:

*   Meilisearch credentials
*   Strapi collections

![](https://unable-actionable-car.media.strapiapp.com/Screenshot_2021_04_21_at_14_44_12_6b821d2d2e.png)

Meilisearch plugin page of Strapi admin dashboard

First, we need to add the credentials of our Meilisearch instance so that Strapi knows where to send our data.

You may remember from the previous step that Meilisearch runs on `http://localhost:7700` by default. Add this in the `Meilisearch Host` field, then click `Add` to connect your Meilisearch instance to Strapi.  

![](https://unable-actionable-car.media.strapiapp.com/credentials_6fe7804ffa.gif)

Add credentials to Meilisearch.

> Note that we leave `Meilisearch Api Key` blank because we started Meilisearch without a [master key](https://meilisearch.org.cn/docs/learn/configuration/instance_options#master-key).

Great! Now it's time to add your Strapi collection to Meilisearch.

Try clicking on the check box next to `restaurant` and watch as Meilisearch instantly begins processing your data. Because we only have three documents, the indexing time is practically non-existent.

![](https://unable-actionable-car.media.strapiapp.com/Large_GIF_956x212_5f52b4fd0f.gif)

Add restaurants to Meilisearch

We can now go back to our Meilisearch host address: `http://localhost:7700`. After refreshing, you should observe that the page is not as empty as before.

![](https://unable-actionable-car.media.strapiapp.com/Screenshot_2021_04_22_at_10_07_08_6dbd424e4d.png)

Demo page of Meilisearch

We did it! Try inputting "butter" and check out the results.

#### Front-end Interface

Using [instant-meilisearch](https://github.com/meilisearch/meilisearch-js-plugins/tree/main/packages/instant-meilisearch), you can implement a front-end search interface in [React](https://github.com/meilisearch/meilisearch-react), [Vue](https://github.com/meilisearch/meilisearch-vue), or [Angular](https://github.com/meilisearch/meilisearch-angular) in no time at all.  
  
Here's an interactive [code sandbox](https://codesandbox.io/s/react-movies-demo-e1dqh) (in React) where you can get a feel for the different components. You can't break anything, so feel free to play around!

### Conclusion

I hope this article was a pleasant introduction to the new [Meilisearch plugin for Strapi](https://github.com/meilisearch/strapi-plugin-meilisearch). However, this is just the beginning!

If you have any questions, please join us [on Discord](https://discord.gg/meilisearch). If you like Meilisearch, [a star on GitHub means a lot](https://github.com/meilisearch/meilisearch). For more information, see our:

*   [Documentation](https://meilisearch.org.cn/docs/)
*   [GitHub](https://github.com/meilisearch/meilisearch)
*   [Strapi Plugin](https://github.com/meilisearch/strapi-plugin-meilisearch)
*   [Discord](https://discord.gg/meilisearch)

How to add relevant search to your Strapi app using Meilisearch

_[Originally published](https://docs.airbyte.io/tutorials/slack-history) on Airbyte site_

**Overview**
------------

The [Slack free tier](https://slack.com/pricing/paid-vs-free) saves only the last 10K messages. For social Slack instances, it may be impractical to upgrade to a paid plan to retain these messages. Similarly, for an open-source project like [Airbyte](https://airbyte.io) where we interact with our community through a public Slack instance, the cost of paying for a seat for every Slack member is prohibitive.

However, searching through old messages can be really helpful. Losing that history feels like some advanced form of memory loss. What was that joke about Java 8 Streams? This contributor question sounds familiar—haven't we seen it before? But you just can't remember!

This tutorial will show you how you can, for _free_, use Airbyte to save these messages (even after Slack removes access to them). It will also provide you a convenient way to search through them.

Specifically, we will export messages from your Slack instance into an open-source search engine called [Meilisearch](https://github.com/meilisearch/meilisearch). We will be focusing on getting this setup running from your local workstation. We will mention at the end how you can set up a more productionized version of this pipeline.

We want to make this process easy, so while we will link to some external documentation for further exploration, we will provide all the instructions you need here to get this up and running.

**Set up Meilisearch**
----------------------

First, let's get Meilisearch running on our workstation. Meilisearch has extensive docs for [getting started](https://docs.meilisearch.com/reference/features/installation.html#download-and-launch). For this tutorial, however, we will give you all the instructions you need to set up Meilisearch using Docker.

```Shell
docker run -it --rm \
  -p 7700:7700 \
  -v $(pwd)/data.ms:/data.ms \
  getmeili/meilisearch
```

That's it!

> Meilisearch stores data in `$(pwd)/data.ms`, so if you prefer to store it somewhere else, just adjust this path.

**How to replicate your Slack messages to Meilisearch**
-------------------------------------------------------

### Set up Airbyte

Make sure you have Docker and Docker Compose installed. If you haven’t set Docker up, follow the [instructions here](https://docs.docker.net.cn/desktop/) to set it up on your machine. Then, run the following commands:

```Shell
git clone https://github.com/airbytehq/airbyte.git
cd airbyte
docker-compose up
```

If you run into any problems, feel free to check out our more extensive [getting started](https://docs.airbyte.io/getting-started) for more help.

Once you see an Airbyte banner, the UI is ready to go at `http://localhost:8000/`. Once you have set your user preferences,  you will be brought to a page that asks you to set up a source. In the next step, we'll go over how to do that.

### Set up Airbyte’s Slack source connector

In the Airbyte UI, select Slack from the dropdown. We provide step-by-step instructions for setting up the Slack source in Airbyte [here](https://docs.airbyte.io/integrations/sources/slack#setup-guide). These will walk you through how to complete the form on this page.

![](https://lh3.googleusercontent.com/ZCxW4_nPPsLB4_fiszkcCIWFIDS8nSifxcwLweC2tH__sUdhEF-34YXQmQXJCSZGg4upzpv1NbICIKNKS0ayap4X41Unxhf7qLmfmDCzEbkl8M2R9ggUnMi-czMU-v_QSAD2mL07)

By the end of these instructions, you should have created a Slack source in the Airbyte UI. For now, just add your Slack app to a single public channel (you can add it to more channels later). Only messages from that channel will be replicated.

The Airbyte app will now prompt you to set up a destination. Next, we will walk through how to set up Meilisearch.

### Set up Airbyte’s Meilisearch destination connector

Head back to the Airbyte UI. It should still be prompting you to set up a destination. Select "Meilisearch" from the dropdown. For the host field, set: `http://localhost:7700`. The api\_key can be left blank.

### Set up the replication

On the next page, you will be asked to select which streams of data you'd like to replicate. We recommend unchecking "files" and "remote files" since you won't really be able to search them easily in this search engine.

![](https://lh6.googleusercontent.com/O-bUkd7k_8Eo-K9PNZA1kCd-bbg0DekSwyNfaXdDHIb3Pcyd9gi8nJXljU0NJL3ELaY6sDq8HoUuaMklFi5fQBpTplfTDklOuYdoQF_lpe_vFAZ9wSOLtPp76iWM7VFnwuC9rkbh)

For frequency, we recommend every 24 hours.

**Search Meilisearch**
----------------------

After the connection has been saved, Airbyte should start replicating the data immediately. When it completes you should see the following:

![](https://lh5.googleusercontent.com/ZErxFD14kuzXkBx2Fv6OtjPM80AogKllbLPlMQJZ8rfb1OTVhKRdt0rr1rS6e7bcnngfs0qJ7pLzNL4CsXYAByzJSspjSXPgbqkyemyiaRP7aPeMT8Wqs7gqtkuTUmKSmZSwdN_3)

When the sync is done, you can sanity check that this is all working by making a search request to Meilisearch. Replication can take several minutes depending on the size of your Slack instance.

```Shell
curl 'http://localhost:7700/indexes/messages/search' --data '{ "q": "<search-term>" }'
```

For example, I have the following message in one of the messages that I replicated: welcome to airbyte..

```Shell
curl 'http://localhost:7700/indexes/messages/search' --data '{ "q": "welcome to" }'
# => {"hits":[{"_ab_pk":"7ff9a858_6959_45e7_ad6b_16f9e0e91098","channel_id":"C01M2UUP87P","client_msg_id":"77022f01-3846-4b9d-a6d3-120a26b2c2ac","type":"message","text":"welcome to airbyte.","user":"U01AS8LGX41","ts":"2021-02-05T17:26:01.000000Z","team":"T01AB4DDR2N","blocks":[{"type":"rich_text"}],"file_ids":[],"thread_ts":"1612545961.000800"}],"offset":0,"limit":20,"nbHits":2,"exhaustiveNbHits":false,"processingTimeMs":21,"query":"test-72"}
```

**Search via a UI**
-------------------

Making curl requests to search your Slack History is a little clunky, so we have modified the example UI that Meilisearch provides in [their docs](https://docs.meilisearch.com/learn/tutorials/getting_started.html#integrate-with-your-project) to search through the Slack results.

Download (or copy and paste) this [html file](https://github.com/airbytehq/airbyte/blob/master/docs/tutorials/slack-history/index.html) to your workstation. Then, open it using a browser. You should now be able to write search terms in the search bar and get results instantly!

![](https://lh6.googleusercontent.com/JfzrnvxFz-08gIL6hMyWeW5TB8_XGgAUibx26o0gXhxJVc97IgW_YnqvWEV2ta8OvJbTQwQUUpYpsHggvbvRSJp8YVTw9w6Y3Ocl8E33Ab-L0E5visu-Beh_kqJwolt-9m_ZEk8N)

**"Productionizing" saving Slack history**
------------------------------------------

You can find instructions for how to host Airbyte on various cloud platforms [here](https://docs.airbyte.io/deploying-airbyte).

Documentation on how to host Meilisearch on cloud platforms can be found [here](https://meilisearch.org.cn/docs/learn/cookbooks/running_production).

If you want to use the UI mentioned in the section above, we recommend statically hosting it on S3, GCS, or equivalent.

Save and search through your Slack history on a free Slack plan

Hey everybody! As some of you may know, I [recently joined Meilisearch](/blog/caro/)s a Developer Advocate. Part of my job is to help the community by answering questions, so my priority over the last few months has been to get to know Meilisearch. I believe the best way to learn new software is to use it just as any developer would: to build something. So, I set out to make a demo.

<Callout>
  This demo was created when the latest version of Meilisearch was v0.19, some of the workarounds described in this blogpost are no longer necessary due to the addition of new features in more recent versions of Meilisearch.
</Callout>

Meilisearch x MoMA
------------------

The first step was to find a nice dataset that I enjoyed working with. After several unsuccessful attempts to tame some unstructured datasets, I stumbled upon the [repository of the Museum of Modern Art (MoMA)](https://github.com/MuseumofModernArt/collection). What a lucky find! They have two datasets: artists and artworks. I decided to go for the artworks dataset since it has all the essential information about each art piece: title, artist, dimensions, medium, even the artist’s biography. But the best part is that it’s available in JSON format! No conversion needed, no MongoDB dump to restore, no scraping: Meilisearch ready 😀

I used [Meilisearch JavaScript](https://github.com/meilisearch/meilisearch-js) to create the indexes, add the documents, and customize the settings. For the front-end, I decided to go for [Instant Meilisearch](https://github.com/meilisearch/meilisearch-js-plugins/tree/main/packages/instant-meilisearch) combined with [Vue InstantSearch](https://github.com/algolia/vue-instantsearch/) as described in the [meilisearch-vue repository](https://github.com/meilisearch/meilisearch-vue/). I’m a little lazy, so if I find a tool that provides nice results effortlessly, I will use it! Fortunately, InstantSearch provides all the front-end tools to customize the search environment at will, so you can experience the power of Meilisearch and its search-as-you-type feature with just a few lines of code. Finally, I tried to add some decent styling, but it’s not my forte 😅 I apologize in advance for the visual design!

**You can see the result** [**here**](https://moma.meilisearch.com/)**.**

![Web interface with searchbar and results for the query "Picasso"](https://unable-actionable-car.media.strapiapp.com/Capture_d_e_cran_2021_02_18_a_16_40_57_41c7a62d0f.png)

Solving Problems
----------------

So, I had found a dataset, indexed it in a Meilisearch instance, and set up a front-end for the search. All done, right? Not exactly; now came the time to iterate and make the search results feel good.

I was lucky to find a structured JSON dataset that worked effortlessly with Meilisearch. Nevertheless, I had to make some small changes to better display the results. Since Meilisearch’s [automatic highlighting](https://meilisearch.org.cn/docs/learn/what_is_meilisearch/features#highlighting) doesn’t work on query results that are stored in an array, I had to **convert array values into strings** before adding them.

I also wanted to allow users to **sort the results by date**. Since the date field didn’t have a standard format, I had to retrieve the year and store it in a new \`sortByDate\` field. Then there was another problem: Meilisearch doesn’t support sorting at query time (**at least, not yet**)! To circumvent that and implement this feature, I created two more indexes with custom ranking rules desc(DateToSortBy) and asc(DateToSortBy). Every time you change the sorting option in the drop-down menu, Meilisearch is actually searching in a completely different index, but it’s so fast that the change is not visible to the human eye 🤯

Here you can see the sorting in action:

![Web interface with the query "Picasso" sorting by ascending and then descending date gif](https://unable-actionable-car.media.strapiapp.com/sorting2_f59a0e2432.gif)

🧐 You might have noticed that I said Meilisearch doesn’t support query-time sorting **yet**—that’s because it’s one of the most requested features on [our public roadmap](https://roadmap.meilisearch.com/tabs/1-under-consideration), and it’s now under consideration 🥳 So if you haven’t done it yet, take a look at Meilisearch’s roadmap and vote for your favorite feature or submit your own ideas! **👉 Update note:** query-time sorting was released with Meilisearch v0.22.

The most challenging part of creating this demo was working with an unknown dataset of 138,151 documents, because the large number of documents makes it difficult to know the possible values and length of the different fields. I first wanted the user to be able to filter results by \`medium\` (e.g.  “photograph” or “paint”). That is, until I realized some of the artworks had \`medium\` fields that were many lines long! Take this one for example:

> "H (vol. IX): Cover with lithographed manuscript text by Kliun on front; 1 lithographed illustration by Terent'ev; lithographed manuscript text. L (vol. XIII): Cover with lithographed illustration and manuscript design by Kirill Zdanevich on front; lithographed manuscript and typed text. M (vol. XIV): Cover with lithographed manuscript design and illustration on front by Kirill Zdanevich; lithographed manuscript and typed text. P (vol. XVII): Cover with lithographed manuscript design on front by Goncharova; and lithographed manuscript text by Mikhail Pustynin and Olga Olesha-Suok"

Can you imagine having this as a [facet filter](https://meilisearch.org.cn/docs/learn/advanced/faceted_search)? Not very nice for the UI…

Close to Perfect
----------------

The easiest part of making this demo was setting up Meilisearch. Once I decided which attributes I wanted to be [displayed](https://meilisearch.org.cn/docs/learn/configuration/displayed_searchable_attributes#displayed-fields) and [searchable](https://meilisearch.org.cn/docs/learn/configuration/displayed_searchable_attributes#searchable-fields), the rest was a piece of cake. Aside from the highlighting and sorting issues mentioned above, the last thing I changed was [the attribute ranking order](https://meilisearch.org.cn/docs/learn/core_concepts/relevancy#attribute-ranking-order). By default, the attribute ranking order is generated automatically based on the attributes' order of appearance in the first document indexed. In my case, the first attribute was \`title\`, which meant that artwork with matching query terms in the \`title\` field topped the results list. This delivered decent results, but I was pretty sure I could do better.

I not only had to consider which attributes are most important for this particular dataset; I also had to think about what types of queries are more likely to be made. If a user queries for a specific art piece using its title, he will get relevant results because the words used are unlikely to be found in lots of other fields. However, if a user queries the name of a famous artist, it is very possible to find that name in an artwork title, for example as a tribute. So I decided to place \`artist\` at the top of [the searchable attributes list](https://meilisearch.org.cn/docs/learn/configuration/displayed_searchable_attributes#the-searchableattributes-list). Before I made the change, this is what you would find among the first results when searching for “Van Gogh” :

![Information and image of a litograph called "Do You Leave without seeing the 150 Van Gogh's" by Willem Jacob Henri Berend Sandberg](https://unable-actionable-car.media.strapiapp.com/Capture_d_e_cran_2021_02_22_a_11_34_08_073b869794.png)

As you can see, it’s an art piece created by an artist named Willem Jacob Henri Berend Sandberg where the name “Van Gogh” appears in the title, but it’s not an actual Van Gogh.

Now, after changing the order of the searchable attributes in [the settings](https://meilisearch.org.cn/docs/reference/api/settings#searchable-attributes), the first result is well and truly a piece of art created by Vincent Van Gogh:

![Information and image of the litograph "The Potato Eaters" by Vincent van Gogh](https://unable-actionable-car.media.strapiapp.com/Capture_d_e_cran_2021_02_22_a_11_41_41_7bdabf659b.png)

  
Pretty amazing how a simple change like this can impact the search results. Meilisearch is ultra relevant out-of-the-box, but it lets you tune the relevancy of the results according to your needs, and that is essential to provide an awesome experience for the end user.

An Open-Source Museum Experience
--------------------------------

The demo source code is available on [GitHub](https://github.com/meilisearch/demo-MoMA/). Feel free to play with it and show me what you can do! 😁

How cool is it that we’re able to access this extraordinary catalog? Thanks to MoMA’s generosity, you can explore the museum from anywhere in the world. And now, thanks to Meilisearch, it’s only 50 milliseconds away 🚀

* * *

_Photo by [Robert Bye](https://unsplash.com/@robertbye#unsplash&utm_medium=referral&utm_content=creditCopyText) on [Unsplash](https://unsplash.com/#unsplash&utm_medium=referral&utm_content=creditCopyText)_

Meilisearch: a blank canvas

A quick introduction
--------------------

Hopefully, you already know that [MeiliSearch](https://github.com/meilisearch/MeiliSearch) is a powerful and fast open-source search engine built in [Rust](https://rust-lang.net.cn). It was designed to provide users with a very useful and customizable search experience including out-of-the-box features such as typo-tolerance, filtering, and synonyms for any kind of project.

Running a Meilisearch instance for testing purposes is incredibly easy and can be done in [many ways](https://docs.meilisearch.com/learn/tutorials/getting_started.html): using Docker, brew, aptitude, binaries, a simple curl, or even the source code. If you are new to MeiliSearch, we suggest that you take a tour around the documentation.

Using MeiliSearch on your own machine for your weekend project is fun, let's agree on that. However, you may want to go live and deploy a project in production, to take it to the next level. What steps and details would you need to **deploy MeiliSearch in production** and ensure it is **safe and ready to use**?

Get your MeiliSearch ready for production
-----------------------------------------

For this tutorial, we will be using a Debian 10 server, running on DigitalOcean. You can easily try it on your own, with plans starting at $5/month. And if you want some credits to start running your MeiliSearch and are not already registered on DigitalOcean, you can get $100 for free using [this referral link](https://m.do.co/c/7c67bd97e101).

Prerequisites
-------------

*   An up-to-date server that runs Debian 10
*   An ssh keypair to connect to that machine
*   MeiliSearch is a database which means that it needs a file system it can write to, and which must be persistent.

> _TIPS:_ learn how to connect via SSH to your [DigitalOcean droplet](https://www.digitalocean.com/docs/droplets/how-to/connect-with-ssh/) or any [Linux or windows server](https://phoenixnap.com/kb/ssh-to-connect-to-remote-server-linux-or-windows)

Step 1: Install MeiliSearch
---------------------------

Installing and running MeiliSearch is easy and straightforward. In order to keep this tutorial as simple as possible, let's use a script that will carry out the installation process. It will copy a binary of MeiliSearch to your machine and enable you to use it immediately.

Once you are logged in into your machine via SSH, ensure your system and its dependencies are up-to-date before proceeding with the installation.

```bash
# Update the list of available packages and their versions
$ apt update
# Install curl which is required to install MeiliSearch in the next step
$ apt install curl -y
# Install MeiliSearch latest version from the script
$ curl -L https://install.meilisearch.com | sh

```

> The different options to achieve a MeiliSearch installation are detailed in **[this guide](https://docs.meilisearch.com/reference/features/installation.html#download-and-launch)**.  
> It is important to know that there are different ways to get MeiliSearch running on your machine. As an open source project, you can always compile the latest stable release of MeiliSearch from the source code to ensure the binary uses your achitecture in the best possible way.

You can always check the latest MeiliSearch stable version, and get MeiliSearch for the Operating System of your choice, by visiting the following link:

**[Latest MeiliSearch Stable Version](https://github.com/meilisearch/MeiliSearch/releases/latest)**

MeiliSearch is finally installed and ready to use. To make it accessible from everywhere in your system, move the binary file into your system binaries folder:

```bash
# Move the MeiliSearch binary to your system binaries
$ mv ./meilisearch /usr/bin/

```

You can now start using MeiliSearch! In your terminal, run:

```bash
$ meilisearch

# --- Expected output for v0.10.1 ---
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

[2020-05-04T11:47:13Z INFO  meilisearch] Database path: "./data.ms"
[2020-05-04T11:47:13Z INFO  meilisearch] Start server on: "127.0.0.1:7700"

```

Step 2: Run MeiliSearch as a service
------------------------------------

In Linux environments, a `service` is a process that can be launched when the operating system is booting and which will keep running in the background. One of its biggest advantages is making your program available at any moment. Even if some execution problems or crashes occur, the service will be restarted and your program will be run again.

> If you are new to services and `systemd`, you can learn more about the basics of Linux services [here](https://www.hostinger.com/tutorials/manage-and-list-services-in-linux/).

In Debian and other Linux distributions, `systemd` allows you to create and manage your own custom services. In order to make sure that MeiliSearch will always respond to your requests, you can build your own service. This way, you will ensure its availability in case of a crash or in case of system reboot. If any of these occur, `systemd` will automatically restart MeiliSearch.

### 2.1 Create a service file

Service files are text files that tell your operating system how to run your program, and when. They live in the `/etc/systemd/system` directory, and your system will load them at boot time. In this case, let's use a very simple service file that will run MeiliSearch on port `7700`.

To run MeiliSearch in a production environment, use the `--env` flag. To generate a master key that will let MeiliSearch create reading and writing keys, use the `--master-key` flag. With those keys, you can easily control who can access or create new documents, indexes, or change the configuration. You can change the `Master Key` to any value in the following command. However, for security concerns, it's better to choose a safe and random key, never share it and, just, **keep it safe**.

```bash
$ cat << EOF >/etc/systemd/system/meilisearch.service
[Unit]
Description=MeiliSearch
After=systemd-user-sessions.service

[Service]
Type=simple
ExecStart=/usr/bin/meilisearch --http-addr 127.0.0.1:7700 --env production --master-key Y0urVery-S3cureAp1K3y

[Install]
WantedBy=default.target
EOF


```

> For more information on MeiliSearch authentication and API keys see the **[Authentication Docs](https://docs.meilisearch.com/reference/features/authentication.html)**. For more information on MeiliSearch options and flags see the **[MeiliSearch configuration options](https://docs.meilisearch.com/reference/features/configuration.html)**

As for now, it is not time yet to expose your MeiliSearch instance to the external world. To keep running it safely inside your own environment, make it available locally at `127.0.0.1`. This means that only programs running on your machine are allowed to make requests to your MeiliSearch instance.

### 2.2. Enable and start service

The service file you just built is all you need for creating your service. Now you must `enable` it to tell the operating system that we want it to run MeiliSearch at every boot. You can then `start` the service to make it run immediately. Ensure everything is working smoothly by checking the service `status`.

```bash
# Set the service meilisearch
$ systemctl enable meilisearch

# Start the meilisearch service
$ systemctl start meilisearch

# Verify that the service is actually running
$ systemctl status meilisearch

-# --- Expected output ---
● meilisearch.service - MeiliSearch
   Loaded: loaded (/etc/systemd/system/meilisearch.service; enabled; vendor preset: enabled)
   Active: active (running) since Fri 2020-04-10 14:27:49 UTC; 1min 8s ago
 Main PID: 14960 (meilisearch)

```

At this point, MeiliSearch is installed and running. It is protected from eventual crashes, system restarts, and most of the problems it could find while running. But it is still hidden and protected inside the walls (or firewalls) of your machine, and unreachable from the outside world. You can stop here if all the requests you do to MeiliSearch are done by another application living in the same machine.

But you probably want to open your MeiliSearch to the outside world, and for now, it is isolated. Let's fix that in a safe way.

Step 3: Secure and finish your setup. Using a Reverse Proxy, domain name and HTTPS
----------------------------------------------------------------------------------

It's time to safely make your brand new MeiliSearch available to be requested from the outside world. For this purpose, you will use two of the main technologies available on the web: a Reverse Proxy and SSL/TLS.

### 3.1. Creating a Reverse Proxy with [Nginx](https://www.nginx.com/)

A reverse proxy is basically an application that will handle every communication between the outside world and your internal applications. Nginx will receive external HTTP requests and redirect them to MeiliSearch. When MeiliSearch has done its amazing job, it will communicate its response to Nginx, which will then transfer the latter to the user who originally sent the request. This is a common way to isolate and protect any application by adding a robust, secure, and fast gate-keeper such as Nginx, one of the safest and most efficient tools available online, and of course, open-source!

> Reverse proxies are very useful regarding security, performance, scalability, and logging concerns. If you are new to Reverse proxies, you may enjoy this article explaining the why and the how of [reverse proxies](https://www.keycdn.com/support/nginx-reverse-proxy).

Configuring Nginx as a proxy server is really simple. First of all, install it on your machine.

```bash
# Install Nginx on Debian
$ apt-get install nginx -y

```

First, deleting the default configuration file is important as the default port for HTTP, the `port 80`, is used by Nginx by default. Thus, trying to use it for MeiliSearch will create a conflict. Replace the default file by your own configuration file. You can also make MeiliSearch listen to another port by specifying it in the Nginx configuration file, but we will not cover this option in this tutorial.

```bash
# Delete the default configuration file for Nginx
$ rm -f /etc/nginx/sites-enabled/default

# Add your configuration file specifying the Reverse Proxy settings
$ cat << EOF > /etc/nginx/sites-enabled/meilisearch
server {
    listen 80 default_server;
    listen [::]:80 default_server;
    server_name _;
    location / {
        proxy_pass  http://127.0.0.1:7700;
    }
}
EOF

```

Finally, enable and start the Nginx service again to make sure it is still available.

```bash
# Reload the operating system daemons / services
$ systemctl daemon-reload

# Enable and start Nginx service
$ systemctl enable nginx
$ systemctl restart nginx

```

MeiliSearch is now up, deployed in a production environment, using a safe API key, and being served by a Reverse Proxy Nginx. You should now be able to send requests to your server from the outside world. Open your web browser and visit: ([http://your-ip-address](http://your-ip-address)). The IP address is the same you used to connect to your machine via SSH in Step 1.

> If you want to learn more about using Nginx as a Reverse Proxy, see [this dedicated documentation](https://docs.nginx.com/nginx/admin-guide/web-server/reverse-proxy/).

The only remaining problem is that MeiliSearch processes requests via HTTP without any additional security. The content that is being transmitted over HTTP could easily be read or modified by attackers, and someone could get full or partial access to your data. In order to prevent this to happen, it's important to use the HTTPS, which will enable you to use a SSL/TLS certificate, and securely transmit data.

### 3.2. Set up SSL/TLS for your MeiliSearch

SSL will let the user or client establish an authenticated connection to MeiliSearch. In this way, a user can verify server's identity before sending sensitive data or making any request to it. Then, data is sent in an encrypted way that only MeiliSearch server will be able to decrypt, providing you a fast, reliable, and automatic layer of security.

In most cases, when enabling SSL, you may want to use your own domain name (or a sub-domain). The first step you need to follow is to register your own domain name and change the DNS records. To make your domain name point to your newly installed MeiliSearch server, you just need to add an `A record` pointing to the IP address used to connect to your own server. This process is simple and fast but can vary for every domain name provider. Thus, we will not cover that process in this article.

> When you register a domain name and add an `A record`, you should be automatically able to request MeiliSearch directly by using that domain name.  
> To illustrate this, if you had registered your domain name `example.com`, requesting indexes would be done at [http://example.com/indexes](http://example.com/indexes)

Once your domain name has been set up, you are ready to configure SSL/TLS and use HTTPS. You have two different options to achieve this goal. The first one is using [Certbot](https://certbot.openssl.ac.cn/), an amazing, free, and very easy to use tool. If you already have SSL certificates issued from a `Certificate Authority or CA` for your domain name, the second option covers the steps you need to follow. Then, you will be ready to use MeiliSearch safely in production!

#### 3.2. Option A: Certbot

Using certbot in your Linux server is very easy and straightforward. This tool will generate a free SSL/TLS certificate for your domain name, and automatically handle its installation on your server. The certbot documentation contains detailed instructions for many operating systems and servers, but we will follow the instructions for [Certbot on Debian with Nginx](https://certbot.openssl.ac.cn/lets-encrypt/debianbuster-nginx).

First of all, install the packages on your system:

```bash
$ sudo apt-get install certbot python-certbot-nginx -y

```

Let's run the Certbot script to be guided through the installation process:

```bash
certbot --nginx

```

Enter your email address, agree to the Terms and Conditions, and input your domain name. You will then be prompted with these options:

```bash
Please choose whether or not to redirect HTTP traffic to HTTPS, removing HTTP access.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
1: No redirect - Make no further changes to the webserver configuration.
2: Redirect - Make all requests redirect to secure HTTPS access. Choose this for
new sites, or if you're confident your site works on HTTPS. You can undo this
change by editing your web server's configuration.

```

We recommend that you choose option 2, to redirect HTTP to HTTPS and always use a secure connection. You should be able to request your domain name with SSL as in `https://example.com` or `https://example.com/indexes`.

#### 3.2. Option B: Custom SSL/TLS Certificates

When a `Certificate Authority` issues a SSL certificate for you, you receive at least two files with encrypted keys:

*   Your **certificate** (commonly named `your_domain_name.pem` or `example.pem`)
*   Your **key** (commonly named `your_domain_name.key` or `example.key`)

> `example.pem` and `example.key` will be used in the following examples. Make sure to replace `example` by the names of your own certificate files.

All you need to do is store the certificate files in a secure location and use appropriate file system security permissions. Then, set the location of the certificates in Nginx configuration. It is also strongly recommended to redirect all HTTP requests to HTTPS (port 80 to 443).

First, let's copy your certificate files in their conventional directory so the server can find them:

```bash
# Create a directory /etc/ssl/example to store the certificate files
$ mkdir -p /etc/ssl/example

# Move your files to /etc/ssl/example. We will suppose that your
# files are called example.pem and example.key

$ mv path-to-your-files/example.pem /etc/ssl/example/
$ mv path-to-your-files/example.key /etc/ssl/example/

```

Finally, we create a new Nginx configuration file, and restart the daemons and Nginx service

> Remember to replace `example.com` in both `server_name` fields with your **own domain name**

```bash

# Replace example.com in both `server_name` fields with your own domain name

$ cat << EOF > /etc/nginx/sites-enabled/meilisearch
server {
      listen 80 default_server;
      listen [::]:80 default_server;

      server_name example.com;

      return 301 https://\$server_name\$request_uri;
}
server {
    server_name example.com;

    location / {
        proxy_pass  http://127.0.0.1:7700;
    }

    listen [::]:443 ssl ipv6only=on;
    listen 443 ssl;

    access_log /var/log/nginx/nginx.vhost.access.log;
    error_log /var/log/nginx/nginx.vhost.error.log;
    ssl_certificate /etc/ssl/example/example.pem;
    ssl_certificate_key /etc/ssl/example/example.key;
}
EOF

$ systemctl restart nginx

```

Your SSL certificates should be working and Nginx should be able to find them. Every request to `http://example.com` will now be redirected to `https://example.com`

Conclusion
----------

You have followed the main steps to provide a safe and stable service. Your MeiliSearch instance should be up and running, in a safe environment and ready to stay available even when the most common issues occur. In addition, it is protected by a reverse proxy with your own domain name and API key, so your data and configuration are accessible only to trusted clients. Communication with your server is now encrypted. Furthermore, its identity will be verified every time before sending sensitive data in a fast and automated manner.

You are now ready to start using your **Production-ready MeiliSearch**!

Meilisearch 最新消息和公司动态

控制 Meilisearch 的拼写容错

如何使用 Meilisearch 将相关搜索集成到 Strapi v4 中

如何在您的多租户应用程序中使用 Meilisearch

使用 Meilisearch 将搜索栏添加到您的 Gatsby 项目

排序的艺术

如何使用 Meilisearch 将相关搜索添加到您的 Strapi 应用程序

在免费的 Slack 计划中保存并搜索您的 Slack 历史记录

Meilisearch：一张白板

MeiliSearch 在生产环境中：将其提升到新的水平