` HTML element. `lvlX` selectors should use the standard title tags like `h1`, `h2`, `h3`, etc. You can also use static classes. Set a unique `id` or `name` attribute to these elements. All searchable `lvl` elements outside this main documentation container (for instance, in a sidebar) must be `global` selectors. They will be globally picked up and injected to every document built from your page. If you use VuePress for your documentation, you can check out the [configuration file](https://github.com/meilisearch/documentation/blob/main/docs-scraper.config.json) we use in production. In our case, the main container is `theme-default-content` and the selector titles and subtitles are `h1`, `h2`... More [optional fields are available](https://github.com/meilisearch/docs-scraper#all-the-config-file-settings) to fit your needs. #### Run the scraper You can run the scraper with Docker. With our local Meilisearch instance set up at [the first step](#run-a-meilisearch-instance), we run: ```bash docker run -t --rm \ --network=host \ -e MEILISEARCH_HOST_URL='MEILISEARCH_URL' \ -e MEILISEARCH_API_KEY='MASTER_KEY' \ -v :/docs-scraper/config.json \ getmeili/docs-scraper:latest pipenv run ./docs_scraper config.json ``` If you don't want to use Docker, here are [other ways to run the scraper](https://github.com/meilisearch/docs-scraper#installation-and-usage). `` should be the **absolute** path of your configuration file defined at [the previous step](#configuration-file). The API key should have the permissions to add documents into your Meilisearch instance. In a production environment, we recommend providing the `Default Admin API Key` as it has enough permissions to perform such requests. _More about [Meilisearch security](/learn/security/basic_security)._ We recommend running the scraper at each new deployment of your documentation, [as we do for the Meilisearch's one](https://github.com/meilisearch/documentation/blob/main/.github/workflows/scraper.yml). ### Integrate the search bar If your documentation is not a VuePress application, you can directly go to [this section](#for-all-kinds-of-documentation). #### For VuePress documentation sites If you use VuePress for your documentation, we provide a [Vuepress plugin](https://github.com/meilisearch/vuepress-plugin-meilisearch). This plugin is used in production in the Meilisearch documentation. In your VuePress project: ```bash yarn add vuepress-plugin-meilisearch ``` ```bash npm install vuepress-plugin-meilisearch ``` In your `config.js` file: ```js module.exports = { plugins: [ [ "vuepress-plugin-meilisearch", { "hostUrl": "", "apiKey": "", "indexUid": "docs" } ], ], } ``` The `hostUrl` and the `apiKey` fields are the credentials of the Meilisearch instance. Following on from this tutorial, they are respectively `MEILISEARCH_URL` and `MASTER_KEY`. `indexUid` is the index identifier in your Meilisearch instance in which your website content is stored. It has been defined in the [config file](#configuration-file). These three fields are mandatory, but more [optional fields are available](https://github.com/meilisearch/vuepress-plugin-meilisearch#customization) to customize your search bar. Since the configuration file is public, we strongly recommend providing a key that can only access [the search endpoint](/reference/api/search) , such as the `Default Search API Key`, in a production environment. Read more about [Meilisearch security](/learn/security/basic_security). #### For all kinds of documentation If you don't use VuePress for your documentation, we provide a [front-end SDK](https://github.com/meilisearch/docs-searchbar.js) to integrate a powerful and relevant search bar to any documentation website. ![Docxtemplater search bar updating results for "HTML"](/assets/images/tuto-searchbar-for-docs/docxtemplater-searchbar-demo.gif) _[Docxtemplater](https://docxtemplater.com/) search bar demo_ ```html ``` The `hostUrl` and the `apiKey` fields are the credentials of the Meilisearch instance. Following on from this tutorial, they are respectively `MEILISEARCH_URL` and `MASTER_KEY`. `indexUid` is the index identifier in your Meilisearch instance in which your website content is stored. It has been defined in the [config file](#configuration-file). `inputSelector` is the `id` attribute of the HTML search input tag. We strongly recommend providing a `Default Search API Key` in a production environment, which is enough to perform search requests. Read more about [Meilisearch security](/learn/security/basic_security). The default behavior of this library fits perfectly for a documentation search bar, but you might need [some customizations](https://github.com/meilisearch/docs-searchbar.js#customization). For more concrete examples, you can check out this [basic HTML file](https://github.com/meilisearch/docs-searchbar.js/blob/main/playgrounds/html/index.html) or [this more advanced Vue file](https://github.com/meilisearch/vuepress-plugin-meilisearch/blob/main/MeiliSearchBox.vue). ### What's next? At this point, you should have a working search engine on your website, congrats! 🎉 You can check [this tutorial](/guides/deployment/running_production) if you now want to run Meilisearch in production! --- title: Search result pagination — Meilisearch documentation description: Follow this guide to learn more about the two pagination types available Meilisearch. --- ## Search result pagination In a perfect world, users would not need to look beyond the first search result to find what they were looking for. In practice, however, it is usually necessary to create some kind of pagination interface to browse through long lists of results. In this guide, we discuss two different approaches to pagination supported by Meilisearch: one using `offset` and `limit`, and another using `hitsPerPage` and `page`. ### Choosing the right pagination UI There are many UI patterns that help your users navigate through search results. One common and efficient solution in Meilisearch is using `offset` and `limit` to create interfaces centered around ["Previous" and "Next" buttons](#previous-and-next-buttons). Other solutions, such as [creating a page selector](/guides/front_end/pagination#numbered-page-selectors) allowing users to jump to any search results page, make use of `hitsPerPage` and `page` to obtain the exhaustive total number of matched documents. These tend to be less efficient and may result in decreased performance. Whatever UI pattern you choose, there is a limited maximum number of search results Meilisearch will return for any given query. You can use [the `maxTotalHits` index setting](/reference/api/settings#pagination) to configure this, but be aware that higher limits will negatively impact search performance. ### "Previous" and "Next" buttons Using "Previous" and "Next" buttons for pagination means that users can easily navigate through results, but don't have the ability to jump to an arbitrary results page. This is Meilisearch's recommended solution when creating paginated interfaces. Though this approach offers less precision than a full-blown page selector, it does not require knowing the exact number of search results. Since calculating the exhaustive number of documents matching a query is a resource-intensive process, interfaces like this might offer better performance. #### Implementation To implement this interface in a website or application, we make our queries with the `limit` and `offset` search parameters. Response bodies will include an `estimatedTotalHits` field, containing a partial count of search results. This is Meilisearch's default behavior: ```json { "hits": [ … ], "query": "", "processingTimeMs": 15, "limit": 10, "offset": 0, "estimatedTotalHits": 471 } ``` ##### `limit` and `offset` "Previous" and "Next" buttons can be implemented using the [`limit`](/reference/api/search#limit) and [`offset`](/reference/api/search#offset) search parameters. `limit` sets the size of a page. If you set `limit` to `10`, Meilisearch's response will contain a maximum of 10 search results. `offset` skips a number of search results. If you set `offset` to `20`, Meilisearch's response will skip the first 20 search results. For example, you can use Meilisearch's JavaScript SDK to get the first ten films in a movies database: ```js const results = await index.search("tarkovsky", { limit: 10, offset: 0 }); ``` You can use both parameters together to create search pages. ##### Search pages and calculating `offset` If you set `limit` to `20` and `offset` to `0`, you get the first twenty search results. We can call this our first page. ```js const results = await index.search("tarkovsky", { limit: 20, offset: 0 }); ``` Likewise, if you set `limit` to `20` and `offset` to `40`, you skip the first 40 search results and get documents ranked from 40 through 59. We can call this the third results page. ```js const results = await index.search("tarkovsky", { limit: 20, offset: 40 }); ``` You can use this formula to calculate a page's offset value: `offset = limit * (target page number - 1)`. In the previous example, the calculation would look like this: `offset = 20 * (3 - 1)`. This gives us `40` as the result: `offset = 20 * 2 = 40`. Once a query returns fewer `hits` than your configured `limit`, you have reached the last results page. ##### Keeping track of the current page number Even though this UI pattern does not allow users to jump to a specific page, it is still useful to keep track of the current page number. The following JavaScript snippet stores the page number in an HTML element, `.pagination`, and updates it every time the user moves to a different search results page: ```js function updatePageNumber(elem) { const directionBtn = elem.id // Get the page number stored in the pagination element let pageNumber = parseInt(document.querySelector('.pagination').dataset.pageNumber) // Update page number if (directionBtn === 'previous_button') { pageNumber = pageNumber - 1 } else if (directionBtn === 'next_button') { pageNumber = pageNumber + 1 } // Store new page number in the pagination element document.querySelector('.pagination').dataset.pageNumber = pageNumber } // Add data to our HTML element stating the user is on the first page document.querySelector('.pagination').dataset.pageNumber = 0 // Each time a user clicks on the previous or next buttons, update the page number document.querySelector('#previous_button').onclick = function () { updatePageNumber(this) } document.querySelector('#next_button').onclick = function () { updatePageNumber(this) } ``` ##### Disabling navigation buttons for first and last pages It is often helpful to disable navigation buttons when the user cannot move to the "Next" or "Previous" page. The "Previous" button should be disabled whenever your `offset` is `0`, as this indicates your user is on the first results page. To know when to disable the "Next" button, we recommend setting your query's `limit` to the number of results you wish to display per page plus one. That extra `hit` should not be shown to the user. Its purpose is to indicate that there is at least one more document to display on the next page. The following JavaScript snippet runs checks whether we should disable a button every time the user navigates to another search results page: ```js function updatePageNumber() { const pageNumber = parseInt(document.querySelector('.pagination').dataset.pageNumber) const offset = pageNumber * 20 const results = await index.search('x', { limit: 21, offset }) // If offset equals 0, we're on the first results page if (offset === 0 ) { document.querySelector('#previous_button').disabled = true; } // If offset is bigger than 0, we're not on the first results page if (offset > 0 ) { document.querySelector('#previous_button').disabled = false; } // If Meilisearch returns 20 items or fewer, // we are on the last page if (results.hits.length < 21 ) { document.querySelector('#next_button').disabled = true; } // If Meilisearch returns exactly 21 results // and our page can only show 20 items at a time, // we have at least one more page with one result in it if (results.hits.length === 21 ) { document.querySelector('#next_button').disabled = false; } } document.querySelector('#previous_button').onclick = function () { updatePageNumber(this) } document.querySelector('#next_button').onclick = function () { updatePageNumber(this) } ``` ### Numbered page selectors This type of pagination consists of a numbered list of pages accompanied by "Next" and "Previous" buttons. This is a common UI pattern that offers users a significant amount of precision when navigating results. Calculating the total amount of search results for a query is a resource-intensive process. **Numbered page selectors might lead to performance issues**, especially if you increase `maxTotalHits` above its default value. #### Implementation By default, Meilisearch queries only return `estimatedTotalHits`. This value is likely to change as a user navigates search results and should not be used to create calculate the number of search result pages. When your query contains either [`hitsPerPage`](/reference/api/search#number-of-results-per-page), [`page`](/reference/api/search#page), or both these search parameters, Meilisearch returns `totalHits` and `totalPages` instead of `estimatedTotalHits`. `totalHits` contains the exhaustive number of results for that query, and `totalPages` contains the exhaustive number of pages of search results for the same query: ```json { "hits": [ … ], "query": "", "processingTimeMs": 35, "hitsPerPage": 20, "page": 1, "totalPages": 4, "totalHits": 100 } ``` ##### Search pages with `hitsPerPage` and `page` `hitsPerPage` defines the maximum number of search results on a page. Since `hitsPerPage` defines the number of results on a page, it has a direct effect on the total number of pages for a query. For example, if a query returns 100 results, setting `hitsPerPage` to `25` means you will have four pages of search results. Settings `hitsPerPage` to `50`, instead, means you will have only two pages of search results. The following example returns the first 25 search results for a query: ```js const results = await index.search( "tarkovsky", { hitsPerPage: 25, } ); ``` To navigate through pages of search results, use the `page` search parameter. If you set `hitsPerPage` to `25` and your `totalPages` is `4`, `page` `1` contains documents from 1 to 25. Setting `page` to `2` instead returns documents from 26 to 50: ```js const results = await index.search( "tarkovsky", { hitsPerPage: 25, page: 2 } ); ``` `hitsPerPage` and `page` take precedence over `offset` and `limit`. If a query contains either `hitsPerPage` or `page`, any values passed to `offset` and `limit` are ignored. ##### Create a numbered page list The `totalPages` field included in the response contains the exhaustive count of search result pages based on your query's `hitsPerPage`. Use this to create a numbered list of pages. For ease of use, queries with `hitsPerPage` and `page` always return the current page number. This means you do not need to manually keep track of which page you are displaying. In the following example, we create a list of page buttons dynamically and highlight the current page: ```js const pageNavigation = document.querySelector('#page-navigation'); const listContainer = pageNavigation.querySelector('#page-list'); const results = await index.search( "tarkovsky", { hitsPerPage: 25, page: 1 } ); const totalPages = results.totalPages; const currentPage = results.page; for (let i = 0; i < totalPages; i += 1) { const listItem = document.createElement('li'); const pageButton = document.createElement('button'); pageButton.innerHTML = i; if (currentPage === i) { listItem.classList.add("current-page"); } listItem.append(pageButton); listContainer.append(listItem); } ``` ##### Adding navigation buttons Your users are likely to be more interested in the page immediately after or before the current search results page. Because of this, it is often helpful to add "Next" and "Previous" buttons to your page list. In this example, we add these buttons as the first and last elements of our page navigation component: ```js const pageNavigation = document.querySelector('#page-navigation'); const buttonNext = document.createElement('button'); buttonNext.innerHTML = 'Next'; const buttonPrevious = document.createElement('button'); buttonPrevious.innerHTML = 'Previous'; pageNavigation.prepend(buttonPrevious); pageNavigation.append(buttonNext); ``` We can also disable them as required when on the first or last page of search results: ```js buttonNext.disabled = results.page === results.totalPages; buttonPrevious.disabled = results.page === 1; ``` --- title: Laravel Scout guide — Meilisearch documentation description: Learn how to use Meilisearch with Laravel Scout. sidebarDepth: 3 --- ## Laravel Scout guide In this guide, you will see how to setup [Laravel Scout](https://laravel.com/docs/10.x/scout) to use Meilisearch in your Laravel 10 application. ### Prerequisites Before you start, make sure you have the following installed on your machine: - PHP - [Composer](https://getcomposer.org/) You will also need a Laravel application. If you don't have one, you can create a new one by running the following command: ```sh composer create-project laravel/laravel my-application ``` ### Installing Laravel Scout Laravel comes with out-of-the-box full-text search capabilities via Laravel Scout. To enable it, navigate to your Laravel application directory and install Scout via the Composer package manager: ```sh composer require laravel/scout ``` After installing Scout, you need to publish the Scout configuration file. You can do this by running the following `artisan` command: ```sh php artisan vendor:publish --provider="Laravel\Scout\ScoutServiceProvider" ``` This command should create a new configuration file in your application directory: `config/scout.php`. ### Configuring the Laravel Scout driver Now you need to configure Laravel Scout to use the Meilisearch driver. First, install the dependencies required to use Scout with Meilisearch via Composer: ```sh composer require meilisearch/meilisearch-php http-interop/http-factory-guzzle ``` Then, update the environment variables in your `.env` file: ```sh SCOUT_DRIVER=meilisearch ## Use the host below if you're running Meilisearch via Laravel Sail MEILISEARCH_HOST=http://meilisearch:7700 MEILISEARCH_KEY=masterKey ``` #### Local development Laravel’s official Docker development environment, Laravel Sail, comes with a Meilisearch service out-of-the-box. Please note that when running Meilisearch via Sail, Meilisearch’s host is `http://meilisearch:7700` (instead of say, `http://localhost:7700`). Check out Docker [Bridge network driver](https://docs.docker.com/network/drivers/bridge/#differences-between-user-defined-bridges-and-the-default-bridge) documentation for further detail. #### Running in production For production use cases, we recommend using a managed Meilisearch via [Meilisearch Cloud](https://www.meilisearch.com/cloud?utm_campaign=laravel&utm_source=docs&utm_medium=laravel-scout-guide). On Meilisearch Cloud, you can find your host URL in your project settings. Read the [Meilisearch Cloud quick start](/learn/getting_started/cloud_quick_start). If you prefer to self-host, read our guide for [running Meilisearch in production](/guides/deployment/running_production). ### Making Eloquent models searchable With Scout installed and configured, add the `Laravel\Scout\Searchable` trait to your Eloquent models to make them searchable. This trait will use Laravel’s model observers to keep the data in your model in sync with Meilisearch. Here’s an example model: ```php belongsTo(Company::class); } public function toSearchableArray(): array { // All model attributes are made searchable $array = $this->toArray(); // Then we add some additional fields $array['organization_id'] = $this->company->organization->id; $array['company_name'] = $this->company->name; $array['company_url'] = $this->company->url; return $array; } } ``` ### Configuring filterable and sortable attributes Configure which attributes are [filterable](/learn/filtering_and_sorting/filter_search_results) and [sortable](/learn/filtering_and_sorting/sort_search_results) via your Meilisearch index settings. In Laravel, you can configure your index settings via the `config/scout.php` file: ```php [ 'host' => env('MEILISEARCH_HOST', 'https://edge.meilisearch.com'), 'key' => env('MEILISEARCH_KEY'), 'index-settings' => [ Contact::class => [ 'filterableAttributes' => ['organization_id'], 'sortableAttributes' => ['name', 'company_name'] ], ], ], ]; ``` The example above updates Meilisearch index settings for the `Contact` model: - it makes the `organization_id` field filterable - it makes the `name` and `company_name` fields sortable After changing your index settings, you will need to synchronize your Scout index settings. ### Synchronizing your index settings To synchronize your index settings, run the following command: ```sh php artisan scout:sync-index-settings ``` ### Example usage You built an example application to demonstrate how to use Meilisearch with Laravel Scout. It showcases an app-wide search in a CRM (Customer Relationship Management) application. [![Laravel Scout example application](https://raw.githubusercontent.com/meilisearch/documentation/add-laravel-multitenancy-guide/assets/images/demos/saas-demo-screenshot.png)](https://saas.meilisearch.com/?utm_campaign=laravel&utm_source=docs&utm_medium=laravel-scout-guide) This demo application uses the following features: - [Multi-search](/reference/api/multi_search) (search across multiple indexes) - [Multi-tenancy](/learn/security/multitenancy_tenant_tokens) - [Filtering](/learn/filtering_and_sorting/filter_search_results) - [Sorting](/learn/filtering_and_sorting/sort_search_results) Of course, the code is open-sourced on [Github](https://github.com/meilisearch/saas-demo). 🎉 --- title: Strapi v4 guide description: Learn how to use Meilisearch with Strapi v4. --- ## Strapi v4 guide This tutorial will show you how to integrate Meilisearch with [Strapi](https://strapi.io/) to create a search-based web app. First, you will use Strapi’s quick start guide to create a restaurant collection, and then search this collection with Meilisearch. ### Prerequisites - [Node.js](https://nodejs.org/): active LTS or maintenance LTS versions, currently Node.js >=18.0.0 \<=20.x.x - npm >=6.0.0 (installed with Node.js) - A running instance of Meilisearch (v >= 1.x). If you need help with this part, you can consult the [Installation section](/learn/self_hosted/install_meilisearch_locally). ### Create a back end using Strapi #### Set up the project Create a directory called `my-app` where you will add the back and front-end parts of the application. Generate a back-end API using Strapi inside `my-app`: ```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 to access it. ![Strapi sign up form](/assets/images/strapi-v4/strapi-signup.png) Once you have created your account, you should be redirected to Strapi's admin dashboard. This is where you will configure your back-end API. #### Build and manage your content The next step is to create a new collection type. A collection is like a blueprint of your content—in this case, it will be a collection of restaurants. You will create another collection called "Category" to organize your restaurants later. ![Strapi dashboard with side menu 'Content-Type Builder' option circled](/assets/images/strapi-v4/strapi-dashboard.png) To follow along, complete "Part B: Build your data structure with the Content-type Builder" and steps 2 to 5 in "Part D: Add content to your Strapi Cloud project with the Content Manager" from Strapi's quick start guide. These will include: - creating collection types - creating new entries - setting roles & permissions - publishing the content #### Expand your database After finishing those steps of Strapi's quick start guide, two new collections named Restaurant and Category should have appeared under `Content Manager > Collection Types`. If you click on `Restaurant`, you can see that there is only one. 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](/assets/images/strapi-v4/strapi-restaurant-content-type.png) Add the following 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.` Next, 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](/assets/images/strapi-v4/strapi-add-category.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` Your Strapi back-end is now up and running. Strapi automatically creates a REST API for your Restaurants collection. Check 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 connect Strapi and Meilisearch and start searching. ### Connect Strapi and Meilisearch To add the Meilisearch plugin to Strapi, you need to first quit the Strapi app. Go to the terminal window running Strapi and push `Ctrl+C` to kill the process. Next, install the plugin in the `back` directory. ```bash npm install strapi-plugin-meilisearch ``` After the installation, you have to rebuild the Strapi app before starting it again in development mode, since it makes configuration easier. ```bash npm run build npm run develop ``` At this point, your Strapi app should be running once again on the default address: http://localhost:1337/admin/. Open it in your browser. You should see an admin log-in page. Enter the credentials you used to create your account. 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](/assets/images/strapi-v4/strapi-meilisearch-plugin.png) Add your Meilisearch credentials on the Settings tab of the `meilisearch` plugin page. ![Strapi dashboard with Meilisearch plugin selected: arrow pointing to the location of the settings tab](/assets/images/strapi-v4/strapi-meilisearch-credentials.png) 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](/assets/images/strapi-v4/add-collection-to-meilisearch.gif) 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. Access the [search preview](/learn/getting_started/search_preview) confirm everything is working correctly by searching for “butter”. ![GIF showing the word 'butter' being typed in the search bar and search results appearing instantly](/assets/images/strapi-v4/strapi-search-preview.gif) 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 page](https://github.com/meilisearch/strapi-plugin-meilisearch/#-customization). ### What's next This tutorial showed you how to add your Strapi collections to Meilisearch. In most real-life scenarios, you'll typically build a custom search interface and fetch results using Meilisearch's API. To learn how to quickly build a front-end interface of your own, check out the [Front-end integration page](/guides/front_end/front_end_integration) guide. --- title: Ruby on Rails quick start — Meilisearch documentation description: Integrate Meilisearch into your Ruby on Rails app. --- ## Ruby on Rails quick start Integrate Meilisearch into your Ruby on Rails app. ### 1. Create a Meilisearch project [Create a project](https://cloud.meilisearch.com) in the Meilisearch Cloud dashboard. Check out our [getting started guide](/learn/getting_started/cloud_quick_start) for step-by-step instructions. If you prefer to use the self-hosted version of Meilisearch, you can follow the[ quick start](https://www.meilisearch.com/docs/learn/self_hosted/getting_started_with_self_hosted_meilisearch) tutorial. ### 2. Create a Rails app Ensure your environment uses at least Ruby 2.7.0 and Rails 6.1. ```bash rails new blog ``` ### 3. Install the meilisearch-rails gem Navigate to your Rails app and install the `meilisearch-rails` gem. ```bash bundle add meilisearch-rails ``` ### 4. Add your Meilisearch credentials Run the following command to create a `config/initializers/meilisearch.rb` file. ```bash bin/rails meilisearch:install ``` Then add your Meilisearch URL and [Default Admin API Key](/learn/security/basic_security#obtaining-api-keys). On Meilisearch Cloud, you can find your credentials in your project settings. ```Ruby MeiliSearch::Rails.configuration = { meilisearch_url: '', meilisearch_api_key: '' } ``` ### 5. Generate the model and run the database migration Create an example `Article` model and generate the migration files. ```bash bin/rails generate model Article title:string body:text bin/rails db:migrate ``` ### 6. Index your model into Meilisearch Include the `MeiliSearch::Rails` module and the `meilisearch` block. ```Ruby class Article < ApplicationRecord include MeiliSearch::Rails meilisearch do # index settings # all attributes will be sent to Meilisearch if block is left empty end end ``` This code creates an `Article` index and adds search capabilities to your `Article` model. Once configured, `meilisearch-rails` automatically syncs your table data with your Meilisearch instance. ### 7. Create new records in the database Use the Rails console to create new entries in the database. ```bash bin/rails console ``` ```Ruby ## Use a loop to create and save 5 unique articles with predefined titles and bodies titles = ["Welcome to Rails", "Exploring Rails", "Advanced Rails", "Rails Tips", "Rails in Production"] bodies = [ "This is your first step into Ruby on Rails.", "Dive deeper into the Rails framework.", "Explore advanced features of Rails.", "Quick tips for Rails developers.", "Managing Rails applications in production environments." ] titles.each_with_index do |title, index| article = Article.new(title: title, body: bodies[index]) article.save # Saves the entry to the database end ``` ### 8. Start searching #### Backend search The backend search returns ORM-compliant objects reloaded from your database. ```Ruby ## Meilisearch is typo-tolerant: hits = Article.search('deepre') hits.first ``` We strongly recommend using the frontend search to enjoy the swift and responsive search-as-you-type experience. #### Frontend search For testing purposes, you can explore the records using our built-in [search preview](/learn/getting_started/search_preview). ![Searching through Rails table data with Meilisearch search preview UI](/assets/images/rails_quick_start/rails-qs-search-preview.gif) We also provide resources to help you quickly build your own [frontend interface](/guides/front_end/front_end_integration). ### Next steps When you're ready to use your own data, make sure to configure your [index settings](/reference/api/settings) first to follow [best practices](/learn/indexing/indexing_best_practices). For a full configuration example, see the [meilisearch-rails gem README](https://github.com/meilisearch/meilisearch-rails?tab=readme-ov-file#%EF%B8%8F-settings). --- title: Meilisearch & Model Context Protocol - Talk to Meilisearch with Claude desktop description: This guide walks Meilisearch users through setting up the MCP server with Claude desktop to talk to the Meilisearch API --- ## Model Context Protocol - Talk to Meilisearch with Claude desktop ### Introduction This guide will walk you through setting up and using Meilisearch through natural language interactions with Claude AI via Model Context Protocol (MCP). ### Requirements To follow this guide, you'll need: - [Claude Desktop](https://claude.ai/download) (free) - [A Meilisearch Cloud project](https://www.meilisearch.com/cloud) (14 days free-trial) - Python ≥ 3.9 - From the Meilisearch Cloud dashboard, your Meilisearch host & api key ### Setting up Claude Desktop with the Meilisearch MCP Server #### 1. Install Claude Desktop Download and install [Claude Desktop](https://claude.ai/download). #### 2. Install the Meilisearch MCP Server You can install the Meilisearch MCP server using `uv` or `pip`: ```bash ## Using uv (recommended) uv pip install meilisearch-mcp ## Using pip pip install meilisearch-mcp ``` #### 3. Configure Claude Desktop Open Claude Desktop, click on the Claude menu in the top bar, and select "Settings". In the Settings window, click on "Developer" in the left sidebar, then click "Edit Config". This will open your `claude_desktop_config.json` file. Add the Meilisearch MCP server to your configuration: ```json { "mcpServers": { "meilisearch": { "command": "uvx", "args": ["-n", "meilisearch-mcp"] } } ``` Save the file and restart Claude. ### Connecting to Your Meilisearch Instance Once Claude Desktop is set up with the Meilisearch MCP server, you can connect to your Meilisearch instance by asking Claude to update the connection settings. Open Claude Desktop and start a new conversation. Next, connect to your Meilisearch instance by asking Claude to update the connection settings, replacing `MEILISEARCH_URL` with your project URL and `API_KEY` with your project's API key: ``` Please connect to my Meilisearch instance at MEILISEARCH_URL using the API key API_KEY ``` Claude will use the MCP server's `update-connection-settings` tool to establish a connection to your Meilisearch instance. Finally, verify the connection by asking: ``` Can you check the connection to my Meilisearch instance and tell me what version it's running? ``` Claude will use the `get-version` and `health-check` tools to verify the connection and provide information about your instance. ### Create an e-commerce index Now you have configured the MCP to work with Meilisearch, you can use it to manage your indexes. First, verify what indexes you have in your project: ``` What indexes do I have in my Meilisearch instance? ``` Next, ask Claude to create an index optimized for e-commerce: ``` Create a new index called "products" for our e-commerce site with the primary key "product_id" ``` Finally, check the index has been created successfully and is completely empty: ``` How many documents are in my "products" index and what's its size? ``` ### Add documents to your new index Ask Calude to add a couple of test documents to your "products" index: ``` Add these products to my "products" index: [ {"product_id": 1, "name": "Ergonomic Chair", "description": "Comfortable office chair", "price": 299.99, "category": "Furniture"}, {"product_id": 2, "name": "Standing Desk", "description": "Adjustable height desk", "price": 499.99, "category": "Furniture"} ] ``` Since you are only using "products" for testing, you can also ask Claude to automatically populate it with placeholder data: ``` Add 10 documents in the index "products" with a name, category, price, and description of your choice ``` To verify data insertion worked as expected, retrieve the first few documents in your index: ``` Show me the first 5 products in my "products" index ``` ### Configure your index Before performing your first search, set a few index settings to ensure relevant results. Ask Claude to prioritize exact word matches over multiple partial matches: ``` Update the ranking rules for the "products" index to prioritize word matches and handle typos, but make exact matches more important than proximity ``` It's also a good practice to limit searchable attributes only to highly-relevant fields, and only return attributes you are going to display in your search interface: ``` Configure my "products" index to make the "name" and "description" fields searchable, but only "name", "price", and "category" should be displayed in results ``` ### Perform searches with MCP Perform your first search with the following prompt: ``` Search the "products" index for "desk" and return the top 3 results ``` You can also request your search uses other Meilisearch features such as filters and sorting: ``` Search the "products" index for "chair" where the price is less than 200 and the category is "Furniture". Sort results by price in ascending order. ``` Large Language Models like Claude tend to say "yes" to most requests, even if they can't actually perform them. Claude can only perform actions that are exposed through the Meilisearch API and implemented in the MCP server. If you're unsure whether a particular operation is possible, refer to the [Meilisearch documentation](https://docs.meilisearch.com) and the [MCP server README](https://github.com/meilisearch/meilisearch-mcp). ### Troubleshooting If you encounter issues with the Meilisearch MCP integration, try these steps #### 1. Ask Claude to verify your connection settings ``` What are the current Meilisearch connection settings? ``` #### 2. Ask Claude to check your Meilisearch instance health ``` Run a health check on my Meilisearch instance ``` #### 3. Review Claude's logs Open the logs file in your text editor or log viewer: - On macOS: `~/Library/Logs/Claude/mcp*.log` - On Windows: `%APPDATA%\Claude\logs\mcp*.log` #### 4. Test the MCP server independently Open your terminal and query the MCP Inspector with `npx`: ```bash npx @modelcontextprotocol/inspector uvx -n meilisearch-mcp ``` ### Conclusion The Meilisearch MCP integration with Claude can transform multiple API calls and configuration tasks into conversational requests. This can help you focus more on building your application and less on implementation details. For more information about advanced configurations and capabilities, refer to the [Meilisearch documentation](https://docs.meilisearch.com) and the [Meilisearch MCP server repository](https://github.com/meilisearch/meilisearch-mcp). --- title: Semantic Search with OpenAI Embeddings - Meilisearch documentation description: This guide will walk you through the process of setting up Meilisearch with OpenAI embeddings to enable semantic search capabilities. --- ## Semantic search with OpenAI embeddings ### Introduction This guide will walk you through the process of setting up Meilisearch with OpenAI embeddings to enable semantic search capabilities. By leveraging Meilisearch's AI features and OpenAI's embedding API, you can enhance your search experience and retrieve more relevant results. ### Requirements To follow this guide, you'll need: - A [Meilisearch Cloud](https://www.meilisearch.com/cloud) project running version >=1.13 - An OpenAI account with an API key for embedding generation. You can sign up for an OpenAI account at [OpenAI](https://openai.com/). - No backend required. ### Setting up Meilisearch To set up an embedder in Meilisearch, you need to configure it to your settings. You can refer to the [Meilisearch documentation](/reference/api/settings) for more details on updating the embedder settings. OpenAI offers three main embedding models: - `text-embedding-3-large`: 3,072 dimensions - `text-embedding-3-small`: 1,536 dimensions - `text-embedding-ada-002`: 1,536 dimensions Here's an example of embedder settings for OpenAI: ```json { "openai": { "source": "openAi", "apiKey": "", "dimensions": 1536, "documentTemplate": "", "model": "text-embedding-3-small" } } ``` In this configuration: - `source`: Specifies the source of the embedder, which is set to "openAi" for using OpenAI's API. - `apiKey`: Replace `` with your actual OpenAI API key. - `dimensions`: Specifies the dimensions of the embeddings. Set to 1536 for `text-embedding-3-small` and `text-embedding-ada-002`, or 3072 for `text-embedding-3-large`. - `documentTemplate`: Optionally, you can provide a [custom template](/learn/ai_powered_search/getting_started_with_ai_search) for generating embeddings from your documents. - `model`: Specifies the OpenAI model to use for generating embeddings. Choose from `text-embedding-3-large`, `text-embedding-3-small`, or `text-embedding-ada-002`. Once you've configured the embedder settings, Meilisearch will automatically generate embeddings for your documents and store them in the vector store. Please note that OpenAI has rate limiting, which is managed by Meilisearch. If you have a free account, the indexation process may take some time, but Meilisearch will handle it with a retry strategy. It's recommended to monitor the tasks queue to ensure everything is running smoothly. You can access the tasks queue using the Cloud UI or the [Meilisearch API](/reference/api/tasks) ### Testing semantic search With the embedder set up, you can now perform semantic searches using Meilisearch. When you send a search query, Meilisearch will generate an embedding for the query using the configured embedder and then use it to find the most semantically similar documents in the vector store. To perform a semantic search, you simply need to make a normal search request but include the hybrid parameter: ```json { "q": "", "hybrid": { "semanticRatio": 1, "embedder": "openai" } } ``` In this request: - `q`: Represents the user's search query. - `hybrid`: Specifies the configuration for the hybrid search. - `semanticRatio`: Allows you to control the balance between semantic search and traditional search. A value of 1 indicates pure semantic search, while a value of 0 represents full-text search. You can adjust this parameter to achieve a hybrid search experience. - `embedder`: The name of the embedder used for generating embeddings. Make sure to use the same name as specified in the embedder configuration, which in this case is "openai". You can use the Meilisearch API or client libraries to perform searches and retrieve the relevant documents based on semantic similarity. ### Conclusion By following this guide, you should now have Meilisearch set up with OpenAI embedding, enabling you to leverage semantic search capabilities in your application. Meilisearch's auto-batching and efficient handling of embeddings make it a powerful choice for integrating semantic search into your project. To explore further configuration options for embedders, consult the [detailed documentation about the embedder setting possibilities](/reference/api/settings). --- title: Implementing semantic search with LangChain description: This guide shows you how to implement semantic search using LangChain and similarity search. --- ## Implementing semantic search with LangChain In this guide, you’ll use OpenAI’s text embeddings to measure the similarity between document properties. Then, you’ll use the LangChain framework to seamlessly integrate Meilisearch and create an application with semantic search. ### Requirements This guide assumes a basic understanding of Python and LangChain. Beginners to LangChain will still find the tutorial accessible. - Python (LangChain requires >= 3.8.1 and < 4.0) and the pip CLI - A [Meilisearch >= 1.6 project](/learn/getting_started/cloud_quick_start) - An [OpenAI API key](https://platform.openai.com/account/api-keys) ### Creating the application Create a folder for your application with an empty `setup.py` file. Before writing any code, install the necessary dependencies: ```bash pip install langchain openai meilisearch python-dotenv ``` First create a .env to store our credentials: ``` ## .env MEILI_HTTP_ADDR="your Meilisearch host" MEILI_API_KEY="your Meilisearch API key" OPENAI_API_KEY="your OpenAI API key" ``` Now that you have your environment variables available, create a `setup.py` file with some boilerplate code: ```python ## setup.py import os from dotenv import load_dotenv # remove if not using dotenv from langchain.vectorstores import Meilisearch from langchain.embeddings.openai import OpenAIEmbeddings from langchain.document_loaders import JSONLoader load_dotenv() # remove if not using dotenv ## exit if missing env vars if "MEILI_HTTP_ADDR" not in os.environ: raise Exception("Missing MEILI_HTTP_ADDR env var") if "MEILI_API_KEY" not in os.environ: raise Exception("Missing MEILI_API_KEY env var") if "OPENAI_API_KEY" not in os.environ: raise Exception("Missing OPENAI_API_KEY env var") ## Setup code will go here 👇 ``` ### Importing documents and embeddings Now that the project is ready, import some documents in Meilisearch. First, download this small movies dataset: movies-lite.json Then, update the setup.py file to load the JSON and store it in Meilisearch. You will also use the OpenAI text search models to generate vector embeddings. To use vector search, we need to set the embedders index setting. In this case, you are using an `userProvided` source which requires to specify the size of the vectors in a `dimensions` field. The default model used by `OpenAIEmbeddings()` is `text-embedding-ada-002`, which has 1,536 dimensions. ```python ## setup.py ## previous code ## Load documents loader = JSONLoader( file_path="./movies-lite.json", jq_schema=".[] | {id: .id, overview: .overview, title: .title}", text_content=False, ) documents = loader.load() print("Loaded {} documents".format(len(documents))) ## Store documents in Meilisearch embeddings = OpenAIEmbeddings() embedders = { "custom": { "source": "userProvided", "dimensions": 1536 } } embedder_name = "custom" vector_store = Meilisearch.from_documents(documents=documents, embedding=embeddings, embedders=embedders, embedder_name=embedder_name) print("Started importing documents") ``` Your Meilisearch instance will now contain your documents. Meilisearch runs tasks like document import asynchronously, so you might need to wait a bit for documents to be available. Consult [the asynchronous operations explanation](/learn/async/asynchronous_operations) for more information on how tasks work. ### Performing similarity search Your database is now populated with the data from the movies dataset. Create a new `search.py` file to make a semantic search query: searching for documents using similarity search. ```python ## search.py import os from dotenv import load_dotenv from langchain.vectorstores import Meilisearch from langchain.embeddings.openai import OpenAIEmbeddings import meilisearch load_dotenv() ## You can use the same code as `setup.py` to check for missing env vars ## Create the vector store client = meilisearch.Client( url=os.environ.get("MEILI_HTTP_ADDR"), api_key=os.environ.get("MEILI_API_KEY"), ) embeddings = OpenAIEmbeddings() vector_store = Meilisearch(client=client, embedding=embeddings) ## Make similarity search embedder_name = "custom" query = "superhero fighting evil in a city at night" results = vector_store.similarity_search( query=query, embedder_name=embedder_name, k=3, ) ## Display results for result in results: print(result.page_content) ``` Run `search.py`. If everything is working correctly, you should see an output like this: ``` {"id": 155, "title": "The Dark Knight", "overview": "Batman raises the stakes in his war on crime. With the help of Lt. Jim Gordon and District Attorney Harvey Dent, Batman sets out to dismantle the remaining criminal organizations that plague the streets. The partnership proves to be effective, but they soon find themselves prey to a reign of chaos unleashed by a rising criminal mastermind known to the terrified citizens of Gotham as the Joker."} {"id": 314, "title": "Catwoman", "overview": "Liquidated after discovering a corporate conspiracy, mild-mannered graphic artist Patience Phillips washes up on an island, where she's resurrected and endowed with the prowess of a cat -- and she's eager to use her new skills ... as a vigilante. Before you can say \"cat and mouse,\" handsome gumshoe Tom Lone is on her tail."} {"id": 268, "title": "Batman", "overview": "Batman must face his most ruthless nemesis when a deformed madman calling himself \"The Joker\" seizes control of Gotham's criminal underworld."} ``` Congrats 🎉 You managed to make a similarity search using Meilisearch as a LangChain vector store. ### Going further Using Meilisearch as a LangChain vector store allows you to load documents and search for them in different ways: - [Import documents from text](https://python.langchain.com/docs/integrations/vectorstores/meilisearch#adding-text-and-embeddings) - [Similarity search with score](https://python.langchain.com/docs/integrations/vectorstores/meilisearch#similarity-search-with-score) - [Similarity search by vector](https://python.langchain.com/docs/integrations/vectorstores/meilisearch#similarity-search-by-vector) For additional information, consult: [Meilisearch Python SDK docs](https://python-sdk.meilisearch.com/) Finally, should you want to use Meilisearch's vector search capabilities without LangChain or its hybrid search feature, refer to the [dedicated tutorial](/learn/ai_powered_search/getting_started_with_ai_search). --- title: Semantic Search with Hugging Face Inference Endpoints - Meilisearch documentation description: This guide will walk you through the process of setting up Meilisearch with Hugging Face Inference Endpoints. --- ## Semantic search with Hugging Face Inference Endpoints ### Introduction This guide will walk you through the process of setting up a Meilisearch REST embedder with [Hugging Face Inference Endpoints](https://ui.endpoints.huggingface.co/) to enable semantic search capabilities. You can use Hugging Face and Meilisearch in two ways: running the model locally by setting the embedder source to `huggingface`, or remotely in Hugging Face's servers by setting the embeder source to `rest`. ### Requirements To follow this guide, you'll need: - A [Meilisearch Cloud](https://www.meilisearch.com/cloud) project running version >=1.13 - A [Hugging Face account](https://huggingface.co/) with a deployed inference endpoint - The endpoint URL and API key of the deployed model on your Hugging Face account ### Configure the embedder Set up an embedder using the update settings endpoint: ```json { "hf-inference": { "source": "rest", "url": "ENDPOINT_URL", "apiKey": "API_KEY", "dimensions": 384, "documentTemplate": "CUSTOM_LIQUID_TEMPLATE", "request": { "inputs": ["{{text}}", "{{..}}"], "model": "baai/bge-small-en-v1.5" }, "response": ["{{embedding}}", "{{..}}"] } } ``` In this configuration: - `source`: declares Meilisearch should connect to this embedder via its REST API - `url`: replace `ENDPOINT_URL` with the address of your Hugging Face model endpoint - `apiKey`: replace `API_KEY` with your Hugging Face API key - `dimensions`: specifies the dimensions of the embeddings, which are 384 for `baai/bge-small-en-v1.5` - `documentTemplate`: an optional but recommended [template](/learn/ai_powered_search/getting_started_with_ai_search) for the data you will send the embedder - `request`: defines the structure and parameters of the request Meilisearch will send to the embedder - `response`: defines the structure of the embedder's response Once you've configured the embedder, Meilisearch will automatically generate embeddings for your documents. Monitor the task using the Cloud UI or the [get task endpoint](/reference/api/tasks). This example uses [BAAI/bge-small-en-v1.5](https://huggingface.co/BAAI/bge-small-en-v1.5) as its model, but Hugging Face offers [other options that may fit your dataset better](https://ui.endpoints.huggingface.co/catalog?task=sentence-embeddings). ### Perform a semantic search With the embedder set up, you can now perform semantic searches. Make a search request with the `hybrid` search parameter, setting `semanticRatio` to `1`: ```json { "q": "QUERY_TERMS", "hybrid": { "semanticRatio": 1, "embedder": "hf-inference" } } ``` In this request: - `q`: the search query - `hybrid`: enables AI-powered search functionality - `semanticRatio`: controls the balance between semantic search and full-text search. Setting it to `1` means you will only receive semantic search results - `embedder`: the name of the embedder used for generating embeddings ### Conclusion You have set up with an embedder using Hugging Face Inference Endpoints. This allows you to use pure semantic search capabilities in your application. Consult the [embedder setting documentation](/reference/api/settings) for more information on other embedder configuration options. --- title: Semantic Search with Cloudflare Worker AI Embeddings - Meilisearch documentation description: This guide will walk you through the process of setting up Meilisearch with Cloudflare Worker AI embeddings to enable semantic search capabilities. --- ## Semantic search with Cloudflare Worker AI embeddings ### Introduction This guide will walk you through the process of setting up Meilisearch with Cloudflare Worker AI embeddings to enable semantic search capabilities. By leveraging Meilisearch's AI features and Cloudflare Worker AI's embedding API, you can enhance your search experience and retrieve more relevant results. ### Requirements To follow this guide, you'll need: - A [Meilisearch Cloud](https://www.meilisearch.com/cloud) project running version >=1.13 - A Cloudflare account with access to Worker AI and an API key. You can sign up for a Cloudflare account at [Cloudflare](https://www.cloudflare.com/) - Your Cloudflare account ID ### Setting up Meilisearch To set up an embedder in Meilisearch, you need to configure it to your settings. You can refer to the [Meilisearch documentation](/reference/api/settings) for more details on updating the embedder settings. Cloudflare Worker AI offers the following embedding models: - `baai/bge-base-en-v1.5`: 768 dimensions - `baai/bge-large-en-v1.5`: 1024 dimensions - `baai/bge-small-en-v1.5`: 384 dimensions Here's an example of embedder settings for Cloudflare Worker AI: ```json { "cloudflare": { "source": "rest", "apiKey": "", "dimensions": 384, "documentTemplate": "", "url": "https://api.cloudflare.com/client/v4/accounts//ai/run/@cf/", "request": { "text": ["{{text}}", "{{..}}"] }, "response": { "result": { "data": ["{{embedding}}", "{{..}}"] } } } } ``` In this configuration: - `source`: Specifies the source of the embedder, which is set to "rest" for using a REST API. - `apiKey`: Replace `` with your actual Cloudflare API key. - `dimensions`: Specifies the dimensions of the embeddings. Set to 384 for `baai/bge-small-en-v1.5`, 768 for `baai/bge-base-en-v1.5`, or 1024 for `baai/bge-large-en-v1.5`. - `documentTemplate`: Optionally, you can provide a [custom template](/learn/ai_powered_search/getting_started_with_ai_search) for generating embeddings from your documents. - `url`: Specifies the URL of the Cloudflare Worker AI API endpoint. - `request`: Defines the request structure for the Cloudflare Worker AI API, including the input parameters. - `response`: Defines the expected response structure from the Cloudflare Worker AI API, including the embedding data. Be careful when setting up the `url` field in your configuration. The URL contains your Cloudflare account ID (``) and the specific model you want to use (``). Make sure to replace these placeholders with your actual account ID and the desired model name (e.g., `baai/bge-small-en-v1.5`). Once you've configured the embedder settings, Meilisearch will automatically generate embeddings for your documents and store them in the vector store. Please note that Cloudflare may have rate limiting, which is managed by Meilisearch. If you have a free account, the indexation process may take some time, but Meilisearch will handle it with a retry strategy. It's recommended to monitor the tasks queue to ensure everything is running smoothly. You can access the tasks queue using the Cloud UI or the [Meilisearch API](/reference/api/tasks). ### Testing semantic search With the embedder set up, you can now perform semantic searches using Meilisearch. When you send a search query, Meilisearch will generate an embedding for the query using the configured embedder and then use it to find the most semantically similar documents in the vector store. To perform a semantic search, you simply need to make a normal search request but include the hybrid parameter: ```json { "q": "", "hybrid": { "semanticRatio": 1, "embedder": "cloudflare" } } ``` In this request: - `q`: Represents the user's search query. - `hybrid`: Specifies the configuration for the hybrid search. - `semanticRatio`: Allows you to control the balance between semantic search and traditional search. A value of 1 indicates pure semantic search, while a value of 0 represents full-text search. You can adjust this parameter to achieve a hybrid search experience. - `embedder`: The name of the embedder used for generating embeddings. Make sure to use the same name as specified in the embedder configuration, which in this case is "cloudflare". You can use the Meilisearch API or client libraries to perform searches and retrieve the relevant documents based on semantic similarity. ### Conclusion By following this guide, you should now have Meilisearch set up with Cloudflare Worker AI embedding, enabling you to leverage semantic search capabilities in your application. Meilisearch's auto-batching and efficient handling of embeddings make it a powerful choice for integrating semantic search into your project. To explore further configuration options for embedders, consult the [detailed documentation about the embedder setting possibilities](/reference/api/settings). --- title: Semantic Search with Cohere Embeddings - Meilisearch documentation description: This guide will walk you through the process of setting up Meilisearch with Cohere embeddings to enable semantic search capabilities. --- ## Semantic search with Cohere embeddings ### Introduction This guide will walk you through the process of setting up Meilisearch with Cohere embeddings to enable semantic search capabilities. By leveraging Meilisearch's AI features and Cohere's embedding API, you can enhance your search experience and retrieve more relevant results. ### Requirements To follow this guide, you'll need: - A [Meilisearch Cloud](https://www.meilisearch.com/cloud) project running version >=1.13 - A Cohere account with an API key for embedding generation. You can sign up for a Cohere account at [Cohere](https://cohere.com/). - No backend required. ### Setting up Meilisearch To set up an embedder in Meilisearch, you need to configure it to your settings. You can refer to the [Meilisearch documentation](/reference/api/settings) for more details on updating the embedder settings. Cohere offers multiple embedding models: - `embed-english-v3.0` and `embed-multilingual-v3.0`: 1024 dimensions - `embed-english-light-v3.0` and `embed-multilingual-light-v3.0`: 384 dimensions Here's an example of embedder settings for Cohere: ```json { "cohere": { "source": "rest", "apiKey": "", "dimensions": 1024, "documentTemplate": "", "url": "https://api.cohere.com/v1/embed", "request": { "model": "embed-english-v3.0", "texts": [ "{{text}}", "{{..}}" ], "input_type": "search_document" }, "response": { "embeddings": [ "{{embedding}}", "{{..}}" ] }, } } ``` In this configuration: - `source`: Specifies the source of the embedder, which is set to "rest" for using a REST API. - `apiKey`: Replace `` with your actual Cohere API key. - `dimensions`: Specifies the dimensions of the embeddings, set to 1024 for the `embed-english-v3.0` model. - `documentTemplate`: Optionally, you can provide a [custom template](/learn/ai_powered_search/getting_started_with_ai_search) for generating embeddings from your documents. - `url`: Specifies the URL of the Cohere API endpoint. - `request`: Defines the request structure for the Cohere API, including the model name and input parameters. - `response`: Defines the expected response structure from the Cohere API, including the embedding data. Once you've configured the embedder settings, Meilisearch will automatically generate embeddings for your documents and store them in the vector store. Please note that most third-party tools have rate limiting, which is managed by Meilisearch. If you have a free account, the indexation process may take some time, but Meilisearch will handle it with a retry strategy. It's recommended to monitor the tasks queue to ensure everything is running smoothly. You can access the tasks queue using the Cloud UI or the [Meilisearch API](https://www.meilisearch.com/docs/reference/api/tasks). ### Testing semantic search With the embedder set up, you can now perform semantic searches using Meilisearch. When you send a search query, Meilisearch will generate an embedding for the query using the configured embedder and then use it to find the most semantically similar documents in the vector store. To perform a semantic search, you simply need to make a normal search request but include the hybrid parameter: ```json { "q": "", "hybrid": { "semanticRatio": 1, "embedder": "cohere" } } ``` In this request: - `q`: Represents the user's search query. - `hybrid`: Specifies the configuration for the hybrid search. - `semanticRatio`: Allows you to control the balance between semantic search and traditional search. A value of 1 indicates pure semantic search, while a value of 0 represents full-text search. You can adjust this parameter to achieve a hybrid search experience. - `embedder`: The name of the embedder used for generating embeddings. Make sure to use the same name as specified in the embedder configuration, which in this case is "cohere". You can use the Meilisearch API or client libraries to perform searches and retrieve the relevant documents based on semantic similarity. ### Conclusion By following this guide, you should now have Meilisearch set up with Cohere embedding, enabling you to leverage semantic search capabilities in your application. Meilisearch's auto-batching and efficient handling of embeddings make it a powerful choice for integrating semantic search into your project. To explore further configuration options for embedders, consult the [detailed documentation about the embedder setting possibilities](/reference/api/settings). --- title: Semantic Search with Mistral Embeddings - Meilisearch documentation description: This guide will walk you through the process of setting up Meilisearch with Mistral embeddings to enable semantic search capabilities. --- ## Semantic search with Mistral embeddings ### Introduction This guide will walk you through the process of setting up Meilisearch with Mistral embeddings to enable semantic search capabilities. By leveraging Meilisearch's AI features and Mistral's embedding API, you can enhance your search experience and retrieve more relevant results. ### Requirements To follow this guide, you'll need: - A [Meilisearch Cloud](https://www.meilisearch.com/cloud) project running version >=1.13 - A Mistral account with an API key for embedding generation. You can sign up for a Mistral account at [Mistral](https://mistral.ai/). - No backend required. ### Setting up Meilisearch To set up an embedder in Meilisearch, you need to configure it to your settings. You can refer to the [Meilisearch documentation](/reference/api/settings) for more details on updating the embedder settings. While using Mistral to generate embeddings, you'll need to use the model `mistral-embed`. Unlike some other services, Mistral currently offers only one embedding model. Here's an example of embedder settings for Mistral: ```json { "mistral": { "source": "rest", "apiKey": "", "dimensions": 1024, "documentTemplate": "", "url": "https://api.mistral.ai/v1/embeddings", "request": { "model": "mistral-embed", "input": ["{{text}}", "{{..}}"] }, "response": { "data": [ { "embedding": "{{embedding}}" }, "{{..}}" ] } } } ``` In this configuration: - `source`: Specifies the source of the embedder, which is set to "rest" for using a REST API. - `apiKey`: Replace `` with your actual Mistral API key. - `dimensions`: Specifies the dimensions of the embeddings, set to 1024 for the `mistral-embed` model. - `documentTemplate`: Optionally, you can provide a [custom template](/learn/ai_powered_search/getting_started_with_ai_search) for generating embeddings from your documents. - `url`: Specifies the URL of the Mistral API endpoint. - `request`: Defines the request structure for the Mistral API, including the model name and input parameters. - `response`: Defines the expected response structure from the Mistral API, including the embedding data. Once you've configured the embedder settings, Meilisearch will automatically generate embeddings for your documents and store them in the vector store. Please note that most third-party tools have rate limiting, which is managed by Meilisearch. If you have a free account, the indexation process may take some time, but Meilisearch will handle it with a retry strategy. It's recommended to monitor the tasks queue to ensure everything is running smoothly. You can access the tasks queue using the Cloud UI or the [Meilisearch API](/reference/api/tasks) ### Testing semantic search With the embedder set up, you can now perform semantic searches using Meilisearch. When you send a search query, Meilisearch will generate an embedding for the query using the configured embedder and then use it to find the most semantically similar documents in the vector store. To perform a semantic search, you simply need to make a normal search request but include the hybrid parameter: ```json { "q": "", "hybrid": { "semanticRatio": 1, "embedder": "mistral" } } ``` In this request: - `q`: Represents the user's search query. - `hybrid`: Specifies the configuration for the hybrid search. - `semanticRatio`: Allows you to control the balance between semantic search and traditional search. A value of 1 indicates pure semantic search, while a value of 0 represents full-text search. You can adjust this parameter to achieve a hybrid search experience. - `embedder`: The name of the embedder used for generating embeddings. Make sure to use the same name as specified in the embedder configuration, which in this case is "mistral". You can use the Meilisearch API or client libraries to perform searches and retrieve the relevant documents based on semantic similarity. ### Conclusion By following this guide, you should now have Meilisearch set up with Mistral embedding, enabling you to leverage semantic search capabilities in your application. Meilisearch's auto-batching and efficient handling of embeddings make it a powerful choice for integrating semantic search into your project. To explore further configuration options for embedders, consult the [detailed documentation about the embedder setting possibilities](/reference/api/settings). --- title: Semantic Search with Voyage AI Embeddings - Meilisearch documentation description: This guide will walk you through the process of setting up Meilisearch with Voyage AI embeddings to enable semantic search capabilities. --- ## Semantic search with Voyage AI embeddings ### Introduction This guide will walk you through the process of setting up Meilisearch with Voyage AI embeddings to enable semantic search capabilities. By leveraging Meilisearch's AI features and Voyage AI's embedding API, you can enhance your search experience and retrieve more relevant results. ### Requirements To follow this guide, you'll need: - A [Meilisearch Cloud](https://www.meilisearch.com/cloud) project running version >=1.13 - A Voyage AI account with an API key for embedding generation. You can sign up for a Voyage AI account at [Voyage AI](https://www.voyageai.com/). - No backend required. ### Setting up Meilisearch To set up an embedder in Meilisearch, you need to configure it to your settings. You can refer to the [Meilisearch documentation](/reference/api/settings) for more details on updating the embedder settings. Voyage AI offers the following embedding models: - `voyage-large-2-instruct`: 1024 dimensions - `voyage-multilingual-2`: 1024 dimensions - `voyage-large-2`: 1536 dimensions - `voyage-2`: 1024 dimensions Here's an example of embedder settings for Voyage AI: ```json { "voyage": { "source": "rest", "apiKey": "", "dimensions": 1024, "documentTemplate": "", "url": "https://api.voyageai.com/v1/embeddings", "request": { "model": "voyage-2", "input": ["{{text}}", "{{..}}"] }, "response": { "data": [ { "embedding": "{{embedding}}" }, "{{..}}" ] } } } ``` In this configuration: - `source`: Specifies the source of the embedder, which is set to "rest" for using a REST API. - `apiKey`: Replace `` with your actual Voyage AI API key. - `dimensions`: Specifies the dimensions of the embeddings. Set to 1024 for `voyage-2`, `voyage-large-2-instruct`, and `voyage-multilingual-2`, or 1536 for `voyage-large-2`. - `documentTemplate`: Optionally, you can provide a [custom template](/learn/ai_powered_search/getting_started_with_ai_search) for generating embeddings from your documents. - `url`: Specifies the URL of the Voyage AI API endpoint. - `request`: Defines the request structure for the Voyage AI API, including the model name and input parameters. - `response`: Defines the expected response structure from the Voyage AI API, including the embedding data. Once you've configured the embedder settings, Meilisearch will automatically generate embeddings for your documents and store them in the vector store. Please note that most third-party tools have rate limiting, which is managed by Meilisearch. If you have a free account, the indexation process may take some time, but Meilisearch will handle it with a retry strategy. It's recommended to monitor the tasks queue to ensure everything is running smoothly. You can access the tasks queue using the Cloud UI or the [Meilisearch API](/reference/api/tasks). ### Testing semantic search With the embedder set up, you can now perform semantic searches using Meilisearch. When you send a search query, Meilisearch will generate an embedding for the query using the configured embedder and then use it to find the most semantically similar documents in the vector store. To perform a semantic search, you simply need to make a normal search request but include the hybrid parameter: ```json { "q": "", "hybrid": { "semanticRatio": 1, "embedder": "voyage" } } ``` In this request: - `q`: Represents the user's search query. - `hybrid`: Specifies the configuration for the hybrid search. - `semanticRatio`: Allows you to control the balance between semantic search and traditional search. A value of 1 indicates pure semantic search, while a value of 0 represents full-text search. You can adjust this parameter to achieve a hybrid search experience. - `embedder`: The name of the embedder used for generating embeddings. Make sure to use the same name as specified in the embedder configuration, which in this case is "voyage". You can use the Meilisearch API or client libraries to perform searches and retrieve the relevant documents based on semantic similarity. ### Conclusion By following this guide, you should now have Meilisearch set up with Voyage AI embedding, enabling you to leverage semantic search capabilities in your application. Meilisearch's auto-batching and efficient handling of embeddings make it a powerful choice for integrating semantic search into your project. To explore further configuration options for embedders, consult the [detailed documentation about the embedder setting possibilities](/reference/api/settings). --- title: Computing Hugging Face embeddings with the GPU — Meilisearch documentation description: This guide for experienced users shows you how to compile a Meilisearch binary that generates Hugging Face embeddings with an Nvidia GPU. --- ## Computing Hugging Face embeddings with the GPU This guide is aimed at experienced users working with a self-hosted Meilisearch instance. It shows you how to compile a Meilisearch binary that generates Hugging Face embeddings with an Nvidia GPU. ### Prerequisites - A [CUDA-compatible Linux distribution](https://docs.nvidia.com/cuda/cuda-installation-guide-linux/index.html#id12) - An Nvidia GPU with CUDA support - A modern Rust compiler ### Install CUDA Follow Nvidia's [CUDA installation instructions](https://docs.nvidia.com/cuda/cuda-installation-guide-linux/index.html). ### Verify your CUDA install After you have installed CUDA in your machine, run the following command in your command-line terminal: ```sh nvcc --version | head -1 ``` If CUDA is working correctly, you will see the following response: ``` nvcc: NVIDIA (R) Cuda compiler driver ``` ### Compile Meilisearch First, clone Meilisearch: ```sh git clone https://github.com/meilisearch/meilisearch.git ``` Then, compile the Meilisearch binary with `cuda` enabled: ```sh cargo build --release --features cuda ``` This might take a few moments. Once the compiler is done, you should have a CUDA-compatible Meilisearch binary. ### Configure the Hugging Face embedder Run your freshly compiled binary: ```sh ./meilisearch ``` Then add the Hugging Face embedder to your index settings: ```sh curl \ -X PATCH 'MEILISEARCH_URL/indexes/INDEX_NAME/settings/embedders' \ -H 'Content-Type: application/json' \ --data-binary '{ "default": { "source": "huggingFace" } }' ``` Meilisearch will return a summarized task object and place your request on the task queue: ```json { "taskUid": 1, "indexUid": "INDEX_NAME", "status": "enqueued", "type": "settingsUpdate", "enqueuedAt": "2024-03-04T15:05:43.383955Z" } ``` Use the task object's `taskUid` to [monitor the task status](/reference/api/tasks#get-one-task). The Hugging Face embedder will be ready to use once the task is completed. ### Conclusion You have seen how to compile a Meilisearch binary that uses your Nvidia GPU to compute vector embeddings. Doing this should significantly speed up indexing when using Hugging Face. --- title: Improve relevancy when working with large documents — Meilisearch documentation description: Use JavaScript with Node.js to split a single large document and configure Meilisearch with a distinct attribute to prevent duplicated results. --- ## Improve relevancy when working with large documents Meilisearch is optimized for handling paragraph-sized chunks of text. Datasets with many documents containing large amounts of text may lead to reduced search result relevancy. In this guide, you will see how to use JavaScript with Node.js to split a single large document and configure Meilisearch with a distinct attribute to prevent duplicated results. ### Requirements - A running Meilisearch project - A command-line console - Node.js v18 ### Dataset `stories.json` contains two documents, each storing the full text of a short story in its `text` field: ```json [ { "id": 0, "title": "A Haunted House", "author": "Virginia Woolf", "text": "Whatever hour you woke there was a door shutting. From room to room they went, hand in hand, lifting here, opening there, making sure—a ghostly couple.\n\n \"Here we left it,\" she said. And he added, \"Oh, but here too!\" \"It's upstairs,\" she murmured. \"And in the garden,\" he whispered. \"Quietly,\" they said, \"or we shall wake them.\"\n\nBut it wasn't that you woke us. Oh, no. \"They're looking for it; they're drawing the curtain,\" one might say, and so read on a page or two. \"Now they've found it,\" one would be certain, stopping the pencil on the margin. And then, tired of reading, one might rise and see for oneself, the house all empty, the doors standing open, only the wood pigeons bubbling with content and the hum of the threshing machine sounding from the farm. \"What did I come in here for? What did I want to find?\" My hands were empty. \"Perhaps it's upstairs then?\" The apples were in the loft. And so down again, the garden still as ever, only the book had slipped into the grass.\n\nBut they had found it in the drawing room. Not that one could ever see them. The window panes reflected apples, reflected roses; all the leaves were green in the glass. If they moved in the drawing room, the apple only turned its yellow side. Yet, the moment after, if the door was opened, spread about the floor, hung upon the walls, pendant from the ceiling—what? My hands were empty. The shadow of a thrush crossed the carpet; from the deepest wells of silence the wood pigeon drew its bubble of sound. \"Safe, safe, safe,\" the pulse of the house beat softly. \"The treasure buried; the room ...\" the pulse stopped short. Oh, was that the buried treasure?\n\nA moment later the light had faded. Out in the garden then? But the trees spun darkness for a wandering beam of sun. So fine, so rare, coolly sunk beneath the surface the beam I sought always burnt behind the glass. Death was the glass; death was between us; coming to the woman first, hundreds of years ago, leaving the house, sealing all the windows; the rooms were darkened. He left it, left her, went North, went East, saw the stars turned in the Southern sky; sought the house, found it dropped beneath the Downs. \"Safe, safe, safe,\" the pulse of the house beat gladly. \"The Treasure yours.\"\n\nThe wind roars up the avenue. Trees stoop and bend this way and that. Moonbeams splash and spill wildly in the rain. But the beam of the lamp falls straight from the window. The candle burns stiff and still. Wandering through the house, opening the windows, whispering not to wake us, the ghostly couple seek their joy.\n\n\"Here we slept,\" she says. And he adds, \"Kisses without number.\" \"Waking in the morning—\" \"Silver between the trees—\" \"Upstairs—\" \"In the garden—\" \"When summer came—\" \"In winter snowtime—\" The doors go shutting far in the distance, gently knocking like the pulse of a heart.\n\nNearer they come; cease at the doorway. The wind falls, the rain slides silver down the glass. Our eyes darken; we hear no steps beside us; we see no lady spread her ghostly cloak. His hands shield the lantern. \"Look,\" he breathes. \"Sound asleep. Love upon their lips.\"\n\nStooping, holding their silver lamp above us, long they look and deeply. Long they pause. The wind drives straightly; the flame stoops slightly. Wild beams of moonlight cross both floor and wall, and, meeting, stain the faces bent; the faces pondering; the faces that search the sleepers and seek their hidden joy.\n\n\"Safe, safe, safe,\" the heart of the house beats proudly. \"Long years—\" he sighs. \"Again you found me.\" \"Here,\" she murmurs, \"sleeping; in the garden reading; laughing, rolling apples in the loft. Here we left our treasure—\" Stooping, their light lifts the lids upon my eyes. \"Safe! safe! safe!\" the pulse of the house beats wildly. Waking, I cry \"Oh, is this _your_ buried treasure? The light in the heart." }, { "id": 1, "title": "Monday or Tuesday", "author": "Virginia Woolf", "text": "Lazy and indifferent, shaking space easily from his wings, knowing his way, the heron passes over the church beneath the sky. White and distant, absorbed in itself, endlessly the sky covers and uncovers, moves and remains. A lake? Blot the shores of it out! A mountain? Oh, perfect—the sun gold on its slopes. Down that falls. Ferns then, or white feathers, for ever and ever——\n\nDesiring truth, awaiting it, laboriously distilling a few words, for ever desiring—(a cry starts to the left, another to the right. Wheels strike divergently. Omnibuses conglomerate in conflict)—for ever desiring—(the clock asseverates with twelve distinct strokes that it is midday; light sheds gold scales; children swarm)—for ever desiring truth. Red is the dome; coins hang on the trees; smoke trails from the chimneys; bark, shout, cry \"Iron for sale\"—and truth?\n\nRadiating to a point men's feet and women's feet, black or gold-encrusted—(This foggy weather—Sugar? No, thank you—The commonwealth of the future)—the firelight darting and making the room red, save for the black figures and their bright eyes, while outside a van discharges, Miss Thingummy drinks tea at her desk, and plate-glass preserves fur coats——\n\nFlaunted, leaf-light, drifting at corners, blown across the wheels, silver-splashed, home or not home, gathered, scattered, squandered in separate scales, swept up, down, torn, sunk, assembled—and truth?\n\nNow to recollect by the fireside on the white square of marble. From ivory depths words rising shed their blackness, blossom and penetrate. Fallen the book; in the flame, in the smoke, in the momentary sparks—or now voyaging, the marble square pendant, minarets beneath and the Indian seas, while space rushes blue and stars glint—truth? or now, content with closeness?\n\nLazy and indifferent the heron returns; the sky veils her stars; then bares them." } ] ``` Meilisearch works best with documents under 1kb in size. This roughly translates to a maximum of two or three paragraphs of text. ### Splitting documents Create a `split_documents.js` file in your working directory: ```js ##!/usr/bin/env node const datasetPath = process.argv[2]; const datasetFile = fs.readFileSync(datasetPath); const documents = JSON.parse(datasetFile); const splitDocuments = []; for (let documentNumber = documents.length, i = 0; i < documentNumber; i += 1) { const document = documents[i]; const story = document.text; const paragraphs = story.split("\n\n"); for (let paragraphNumber = paragraphs.length, o = 0; o < paragraphNumber; o += 1) { splitDocuments.push({ "id": document.id, "title": document.title, "author": document.author, "text": paragraphs[o] }); } } fs.writeFileSync("stories-split.json", JSON.stringify(splitDocuments)); ``` Next, run the script on your console, specifying the path to your JSON dataset: ```sh node ./split_documents.js ./stories.json ``` This script accepts one argument: a path pointing to a JSON dataset. It reads the file and parses each document in it. For each paragraph in a document's `text` field, it creates a new document with a new `id` and `text` fields. Finally, it writes the new documents on `stories-split.json`. ### Generating unique IDs Right now, Meilisearch would not accept the new dataset because many documents share the same primary key. Update the script from the previous step to create a new field, `story_id`: ```js ##!/usr/bin/env node const datasetPath = process.argv[2]; const datasetFile = fs.readFileSync(datasetPath); const documents = JSON.parse(datasetFile); const splitDocuments = []; for (let documentNumber = documents.length, i = 0; i < documentNumber; i += 1) { const document = documents[i]; const story = document.text; const paragraphs = story.split("\n\n"); for (let paragraphNumber = paragraphs.length, o = 0; o < paragraphNumber; o += 1) { splitDocuments.push({ "story_id": document.id, "id": `${document.id}-${o}`, "title": document.title, "author": document.author, "text": paragraphs[o] }); } } ``` The script now stores the original document's `id` in `story_id`. It then creates a new unique identifier for each new document and stores it in the primary key field. ### Configuring distinct attribute This dataset is now valid, but since each document effectively points to the same story, queries are likely to result in duplicated search results. To prevent that from happening, configure `story_id` as the index's distinct attribute: ```sh curl \ -X PUT 'MEILISEARCH_URL/indexes/INDEX_NAME/settings/distinct-attribute' \ -H 'Content-Type: application/json' \ --data-binary '"story_id"' ``` Users searching this dataset will now be able to find more relevant results across large chunks of text, without any loss of performance and no duplicates. ### Conclusion You have seen how to split large documents to improve search relevancy. You also saw how to configure a distinct attribute to prevent Meilisearch from returning duplicate results. Though this guide used JavaScript, you can replicate the process with any programming language you are comfortable using. --- title: Using HTTP/2 and SSL with Meilisearch — Meilisearch documentation description: Learn how to configure a server to use Meilisearch with HTTP/2. --- ## Using HTTP/2 and SSL with Meilisearch For those willing to use HTTP/2, please be aware that it is **only possible if your server is configured with SSL certificate**. Therefore, you will see how to launch a Meilisearch server with SSL. This tutorial gives a short introduction to do it locally, but you can as well do the same thing on a remote server. First of all, you need the binary of Meilisearch, or you can also use docker. In the latter case, it is necessary to pass the parameters using environment variables and the SSL certificates via a volume. A tool to generate SSL certificates is also required. In this How To, you will use [mkcert](https://github.com/FiloSottile/mkcert). However, if on a remote server, you can also use certbot or certificates signed by a Certificate Authority. Then, use `curl` to do requests. It is a simple way to specify that you want to send HTTP/2 requests by using the `--http2` option. ### Try to use HTTP/2 without SSL Start by running the binary. ```bash ./meilisearch ``` And then, send a request. ```bash curl -kvs --http2 --request GET 'http://localhost:7700/indexes' ``` You will get the following answer from the server: ```bash * Trying ::1... * TCP_NODELAY set * Connection failed * connect to ::1 port 7700 failed: Connection refused * Trying 127.0.0.1... * TCP_NODELAY set * Connected to localhost (127.0.0.1) port 7700 (#0) > GET /indexes HTTP/1.1 > Host: localhost:7700 > User-Agent: curl/7.64.1 > Accept: */* > Connection: Upgrade, HTTP2-Settings > Upgrade: h2c > HTTP2-Settings: AAMAAABkAARAAAAAAAIAAAAA > < HTTP/1.1 200 OK < content-length: 2 < content-type: application/json < date: Fri, 17 Jul 2020 11:01:02 GMT < * Connection #0 to host localhost left intact []* Closing connection 0 ``` You can see on line `> Connection: Upgrade, HTTP2-Settings` that the server tries to upgrade to HTTP/2, but is unsuccessful. The answer `< HTTP/1.1 200 OK` indicates that the server still uses HTTP/1. ### Try to use HTTP/2 with SSL This time, start by generating the SSL certificates. mkcert creates two files: `127.0.0.1.pem` and `127.0.0.1-key.pem`. ```bash mkcert '127.0.0.1' ``` Then, use the certificate and the key to configure Meilisearch with SSL. ```bash ./meilisearch --ssl-cert-path ./127.0.0.1.pem --ssl-key-path ./127.0.0.1-key.pem ``` Next, make the same request as above but change `http://` to `https://`. ```bash curl -kvs --http2 --request GET 'https://localhost:7700/indexes' ``` You will get the following answer from the server: ```bash * Trying ::1... * TCP_NODELAY set * Connection failed * connect to ::1 port 7700 failed: Connection refused * Trying 127.0.0.1... * TCP_NODELAY set * Connected to localhost (127.0.0.1) port 7700 (#0) * ALPN, offering h2 * ALPN, offering http/1.1 * successfully set certificate verify locations: * CAfile: /etc/ssl/cert.pem CApath: none * TLSv1.2 (OUT), TLS handshake, Client hello (1): * TLSv1.2 (IN), TLS handshake, Server hello (2): * TLSv1.2 (IN), TLS handshake, Certificate (11): * TLSv1.2 (IN), TLS handshake, Server key exchange (12): * TLSv1.2 (IN), TLS handshake, Server finished (14): * TLSv1.2 (OUT), TLS handshake, Client key exchange (16): * TLSv1.2 (OUT), TLS change cipher, Change cipher spec (1): * TLSv1.2 (OUT), TLS handshake, Finished (20): * TLSv1.2 (IN), TLS change cipher, Change cipher spec (1): * TLSv1.2 (IN), TLS handshake, Finished (20): * SSL connection using TLSv1.2 / ECDHE-RSA-AES256-GCM-SHA384 * ALPN, server accepted to use h2 * Server certificate: * subject: O=mkcert development certificate; OU=quentindequelen@s-iMac (Quentin de Quelen) * start date: Jun 1 00:00:00 2019 GMT * expire date: Jul 17 10:38:53 2030 GMT * issuer: O=mkcert development CA; OU=quentindequelen@s-iMac (Quentin de Quelen); CN=mkcert quentindequelen@s-iMac (Quentin de Quelen) * SSL certificate verify result: unable to get local issuer certificate (20), continuing anyway. * Using HTTP2, server supports multi-use * Connection state changed (HTTP/2 confirmed) * Copying HTTP/2 data in stream buffer to connection buffer after upgrade: len=0 * Using Stream ID: 1 (easy handle 0x7ff601009200) > GET /indexes HTTP/2 > Host: localhost:7700 > User-Agent: curl/7.64.1 > Accept: */* > * Connection state changed (MAX_CONCURRENT_STREAMS == 4294967295)! < HTTP/2 200 < content-length: 2 < content-type: application/json < date: Fri, 17 Jul 2020 11:06:27 GMT < * Connection #0 to host localhost left intact []* Closing connection 0 ``` You can see that the server now supports HTTP/2. ```bash * Using HTTP2, server supports multi-use * Connection state changed (HTTP/2 confirmed) ``` The server successfully receives HTTP/2 requests. ```bash < HTTP/2 200 ``` --- title: Laravel multitenancy guide — Meilisearch documentation description: Learn how to implement secure, multitenant search in your Laravel applications. --- ## Laravel multitenancy guide This guide will walk you through implementing search in a multitenant Laravel application. We'll use the example of a customer relationship manager (CRM) application that allows users to store contacts. ### Requirements This guide requires: - A Laravel 10 application with [Laravel Scout](https://laravel.com/docs/10.x/scout) configured to use the `meilisearch` driver - A Meilisearch server running — see our [quick start](/learn/getting_started/cloud_quick_start) - A search API key — available in your Meilisearch dashboard - A search API key UID — retrieve it using the [keys endpoints](/reference/api/keys) Prefer self-hosting? Read our [installation guide](/learn/self_hosted/install_meilisearch_locally). ### Models & relationships Our example CRM is a multitenant application, where each user can only access data belonging to their organization. On a technical level, this means: - A `User` model that belongs to an `Organization` - A `Contact` model that belongs to an `Organization` (can only be accessed by users from the same organization) - An `Organization` model that has many `User`s and many `Contact`s With that in mind, the first step is to define such these models and their relationship: In `app/Models/Contact.php`: ```php belongsTo(Organization::class, 'organization_id'); } } ``` In `app/Models/User.php`: ```php */ protected $fillable = [ 'name', 'email', 'password', ]; /** * The attributes that should be hidden for serialization. * * @var array */ protected $hidden = [ 'password', 'remember_token', ]; /** * The attributes that should be cast. * * @var array */ protected $casts = [ 'email_verified_at' => 'datetime', 'password' => 'hashed', ]; public function organization() { return $this->belongsTo(Organization::class, 'organization_id'); } } ``` And in `app/Models/Organization.php`: ```php hasMany(Contact::class); } } ``` Now you have a solid understanding of your application's models and their relationships, you are ready to generate tenant tokens. ### Generating tenant tokens Currently, all `User`s can search through data belonging to all `Organizations`. To prevent that from happening, you need to generate a tenant token for each organization. You can then use this token to authenticate requests to Meilisearch and ensure that users can only access data from their organization. All `User` within the same `Organization` will share the same token. In this guide, you will generate the token when the organization is retrieved from the database. If the organization has no token, you will generate one and store it in the `meilisearch_token` attribute. Update `app/Models/Organization.php`: ```php hasMany(Contact::class); } protected static function booted() { static::retrieved(function (Organization $organization) { // You may want to add some logic to skip generating tokens in certain environments if (env('SCOUT_DRIVER') === 'array' && env('APP_ENV') === 'testing') { $organization->meilisearch_token = 'fake-tenant-token'; return; } // Early return if the organization already has a token if ($organization->meilisearch_token) { Log::debug('Organization ' . $organization->id . ': already has a token'); return; } Log::debug('Generating tenant token for organization ID: ' . $organization->id); // The object belows is used to generate a tenant token that: // • applies to all indexes // • filters only documents where `organization_id` is equal to this org ID $searchRules = (object) [ '*' => (object) [ 'filter' => 'organization_id = ' . $organization->id, ] ]; // Replace with your own Search API key and API key UID $meiliApiKey = env('MEILISEARCH_SEARCH_KEY'); $meiliApiKeyUid = env('MEILISEARCH_SEARCH_KEY_UID'); // Generate the token $token = self::generateMeiliTenantToken($meiliApiKeyUid, $searchRules, $meiliApiKey); // Save the token in the database $organization->meilisearch_token = $token; $organization->save(); }); } protected static function generateMeiliTenantToken($meiliApiKeyUid, $searchRules, $meiliApiKey) { $meilisearch = resolve(EngineManager::class)->engine(); return $meilisearch->generateTenantToken( $meiliApiKeyUid, $searchRules, [ 'apiKey' => $meiliApiKey, 'expiresAt' => new DateTime('2030-12-31'), ] ); } } ``` Now the `Organization` model is generating tenant tokens, you need to provide the front-end with these tokens so that it can access Meilisearch securely. ### Using tenant tokens with Laravel Blade Use [view composers](https://laravel.com/docs/10.x/views#view-composers) to provide views with your search token. This way, you ensure the token is available in all views, without having to pass it manually. If you prefer, you can pass the token manually to each view using the `with` method. Create a new `app/View/Composers/AuthComposer.php` file: ```php with([ 'meilisearchToken' => $user->organization->meilisearch_token, ]); } } ``` Now, register this view composer in the `AppServiceProvider`: ```php import { instantMeiliSearch } from "@meilisearch/instant-meilisearch" const props = defineProps<{ host: string, apiKey: string, indexName: string, }>() const { searchClient } = instantMeiliSearch(props.host, props.apiKey) ``` You can use the `Meilisearch` component it in any Blade view by providing it with the tenant token. Don't forget to add the `@vite` directive to include the Vue app in your view. ```blade

@push('scripts') @vite('resources/js/vue-app.js') @endpush ``` Et voilà! You now have a search interface that is secure and multitenant. Users can only access data from their organization, and you can rest assured that data from other tenants is safe. ### Conclusion In this guide, you saw how to implement secure, multitenant search in a Laravel application. You then generated tenant tokens for each organization and used them to secure access to Meilisearch. You also built a search interface using Vue InstantSearch and provided it with the tenant token. All the code in this guide is a simplified example of what we implemented in the [Laravel CRM](https://saas.meilisearch.com/?utm_campaign=oss&utm_source=docs&utm_medium=laravel-multitenancy) example application. Find the full code on [GitHub](https://github.com/meilisearch/saas-demo). --- title: Node.js multitenancy guide — Meilisearch documentation description: Learn how to implement secure, multitenant search in your Node.js applications. sidebarDepth: 3 --- ## Node.js multitenancy guide This guide will walk you through implementing search in a multitenant Node.js application handling sensitive medical data. ### What is multitenancy? 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 implement this using [tenant tokens](/learn/security/multitenancy_tenant_tokens). ### Requirements - [Node.js](https://nodejs.org/en) and a package manager like `npm`, `yarn`, or `pnpm` - [Meilisearch JavaScript SDK](/learn/resources/sdks) - A Meilisearch server running — see our [quick start](/learn/getting_started/cloud_quick_start) - A search API key — available in your Meilisearch dashboard - A search API key UID — retrieve it using the [keys endpoints](/reference/api/keys) Prefer self-hosting? Read our [installation guide](/learn/self_hosted/install_meilisearch_locally). ### Data models This guide uses a simple data model to represent medical appointments. The documents in the Meilisearch index will look like this: ```json [ { "id": 1, "patient": "John", "details": "I think I caught a cold. Can you help me?", "status": "pending" }, { "id": 2, "patient": "Zia", "details": "I'm suffering from fever. I need an appointment ASAP.", "status": "pending" }, { "id": 3, "patient": "Kevin", "details": "Some confidential information Kevin has shared.", "status": "confirmed" } ] ``` For the purpose of this guide, we assume documents are stored in an `appointments` index. ### Creating a tenant token The first step is generating a tenant token that will allow a given patient to search only for their appointments. To achieve this, you must first create a tenant token that filters results based on the patient's ID. Create a `search.js` file and use the following code to generate a tenant token: ```js // search.js import { Meilisearch } from 'meilisearch' const apiKey = 'YOUR_SEARCH_API_KEY' const apiKeyUid = 'YOUR_SEARCH_API_KEY_UID' const indexName = 'appointments' const client = new Meilisearch({ host: 'https://edge.meilisearch.com', // Your Meilisearch host apiKey: apiKey }) export function createTenantToken(patientName) { const searchRules = { [indexName]: { 'filter': `patient = ${patientName}` } } const tenantToken = client.generateTenantToken( apiKeyUid, searchRules, { expiresAt: new Date('2030-01-01'), // Choose an expiration date apiKey: apiKey, } ) return tenantToken } ``` When Meilisearch gets a search query with a tenant token, it decodes it and applies the search rules to the search request. In this example, the results are filtered by the `patient` field. This means that a patient can only search for their own appointments. ### Using the tenant token Now that you have a tenant token, use it to perform searches. To achieve this, you will need to: - On the server: create an endpoint to send the token to your front-end - On the client: retrieve the token and use it to perform searches #### Serving the tenant token This guide uses [Express.js](https://expressjs.com/en/starter/installing.html) to create the server. You can install `express` by running: ```sh ## with NPM npm i express ## with Yarn yarn add express ## with pnpm pnpm add express ``` Then, add the following code in a `server.js` file: ```js // server.js import express from 'express' import { createTenantToken } from './search.js' const server = express() server.get('/token', async (request, response) => { const { id: patientId } = request.query const token = createTenantToken(patientId) return response.json({ token }); }) server.listen(3000, () => { console.log('Server is running on port 3000') }) ``` This code creates an endpoint at `http://localhost:3000/token` that accepts an `id` query parameter and returns a tenant token. #### Making a search Now that we have an endpoint, you will use it to retrieve the tenant token in your front-end application. This guide uses [InstantSearch.js](/guides/front_end/front_end_integration) to create a search interface. You will use CDN links to include InstantSearch.js and the Meilisearch InstantSearch.js connector in your HTML file. Create `client.html` file and insert this code: ```html

``` Ta-da! You have successfully implemented a secure, multitenant search in your Node.js application. Users will only be able to search for documents that belong to them. ### Conclusion In this guide, you saw how to implement secure, multitenant search in a Node.js application. You then created an endpoint to generate tenant tokens for each user. You also built a search interface with InstantSearch to make searches using the tenant token. All the code in this guide is a taken from our [multitenacy example](https://tenant-token.meilisearch.com/?utm_campaign=oss&utm_source=docs&utm_medium=node-multitenancy) application. The code is available on [GitHub](https://github.com/meilisearch/tutorials/tree/main/src/tenant-token-tutorial). --- title: Running Meilisearch in production — Meilisearch documentation description: Deploy Meilisearch in a Digital Ocean droplet. Covers installation, server configuration, and securing your instance. --- ## Running a self-hosted Meilisearch project in production This tutorial will guide you through setting up a production-ready Meilisearch instance. These instructions use a DigitalOcean droplet running Debian, but should be compatible with any hosting service running a Linux distro. [Meilisearch Cloud](https://www.meilisearch.com/cloud?utm_campaign=oss&utm_source=docs&utm_medium=running-production-oss) is the recommended way to run Meilisearch in production environments. ### Requirements - A DigitalOcean droplet running Debian 12 - An SSH key pair to connect to that machine DigitalOcean has extensive documentation on [how to use SSH to connect to a droplet](https://www.digitalocean.com/docs/droplets/how-to/connect-with-ssh/). ### Step 1: Install Meilisearch Log into your server via SSH, update the list of available packages, and install `curl`: ```sh apt update apt install curl -y ``` Using the latest version of a package is good security practice, especially in production environments. Next, use `curl` to download and run the Meilisearch command-line installer: ```sh ## Install Meilisearch latest version from the script curl -L https://install.meilisearch.com | sh ``` The Meilisearch installer is a set of scripts that ensure you will get the correct binary for your system. Next, you need to make the binary accessible from anywhere in your system. Move the binary file into `/usr/local/bin`: ```sh mv ./meilisearch /usr/local/bin/ ``` Meilisearch is now installed in your system, but it is not publicly accessible. ### Step 2: Create system user Running applications as root exposes you to unnecessary security risks. To prevent that, create a dedicated user for Meilisearch: ```sh useradd -d /var/lib/meilisearch -s /bin/false -m -r meilisearch ``` Then give the new user ownership of the Meilisearch binary: ```sh chown meilisearch:meilisearch /usr/local/bin/meilisearch ``` ### Step 3: Create a configuration file After installing Meilisearch and taking the first step towards keeping your data safe, you need to set up a basic configuration file. First, create the directories where Meilisearch will store its data: ```bash mkdir /var/lib/meilisearch/data /var/lib/meilisearch/dumps /var/lib/meilisearch/snapshots chown -R meilisearch:meilisearch /var/lib/meilisearch chmod 750 /var/lib/meilisearch ``` In this tutorial, you're creating the directories in your droplet's local disk. If you are using additional block storage, create these directories there. Next, download the default configuration to `/etc`: ```bash curl https://raw.githubusercontent.com/meilisearch/meilisearch/latest/config.toml > /etc/meilisearch.toml ``` Finally, update the following lines in the `meilisearch.toml` file so Meilisearch uses the directories you created earlier to store its data, replacing `MASTER_KEY` with a 16-byte string: ```ini env = "production" master_key = "MASTER_KEY" db_path = "/var/lib/meilisearch/data" dump_dir = "/var/lib/meilisearch/dumps" snapshot_dir = "/var/lib/meilisearch/snapshots" ``` Remember to choose a [safe master key](/learn/security/basic_security#creating-the-master-key-in-a-self-hosted-instance) and avoid exposing it in publicly accessible locations. You have now configured your Meilisearch instance. ### Step 4: 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. If your program stops running for any reason, Linux will immediately restart the service, helping reduce downtime. #### 4.1. Create a service file Service files are text files that tell your operating system how to run your program. Run this command to create a service file in `/etc/systemd/system`: ```bash cat << EOF > /etc/systemd/system/meilisearch.service [Unit] Description=Meilisearch After=systemd-user-sessions.service [Service] Type=simple WorkingDirectory=/var/lib/meilisearch ExecStart=/usr/local/bin/meilisearch --config-file-path /etc/meilisearch.toml User=meilisearch Group=meilisearch Restart=on-failure [Install] WantedBy=multi-user.target EOF ``` #### 4.2. Enable and start service With your service file now ready to go, activate the service using `systemctl`: ```bash systemctl enable meilisearch systemctl start meilisearch ``` With `systemctl enable`, you're telling the operating system you want it to run at every boot. `systemctl start` then immediately starts the Meilisearch service. Ensure everything is working by checking the service status: ```sh systemctl status meilisearch ``` You should see a message confirming your service is running: ```sh ● meilisearch.service - Meilisearch Loaded: loaded (/etc/systemd/system/meilisearch.service; enabled; vendor preset: enabled) Active: active (running) since Fri 2023-04-10 14:27:49 UTC; 1min 8s ago Main PID: 14960 (meilisearch) ``` ### Step 5: Secure and finish your setup At this point, Meilisearch is installed and running. It is also protected from eventual crashes and system restarts. The next step is to make your instance publicly accessible. If all the requests you send to Meilisearch are done by another application living in the same machine, you can safely skip this section. #### 5.1. Creating a reverse proxy with Nginx A [reverse proxy](https://www.keycdn.com/support/nginx-reverse-proxy) is an application that will handle every communication between the outside world and your application. In this tutorial, you will use [Nginx](https://www.nginx.com/) as your reverse proxy to receive external HTTP requests and redirect them to Meilisearch. First, install Nginx on your machine: ```bash apt-get install nginx -y ``` Next, delete the default configuration file: ```bash rm -f /etc/nginx/sites-enabled/default ``` Nginx comes with a set of default settings, such as its default HTTP port, that might conflict with Meilisearch. Create a new configuration file specifying the reverse proxy settings: ```sh cat << EOF > /etc/nginx/sites-enabled/meilisearch server { listen 80 default_server; listen [::]:80 default_server; server_name _; location / { proxy_pass http://localhost:7700; } } EOF ``` Finally, enable the Nginx service: ```bash systemctl daemon-reload systemctl enable nginx systemctl restart nginx ``` Your Meilisearch instance is now publicly available. #### 5.2. Enable HTTPS The only remaining problem is that Meilisearch processes requests via HTTP without any additional security. This is a major security flaw that could result in an attacker accessing your data. This tutorial assumes you have a registered domain name, and you have correctly configured its DNS's `A record` to point to your DigitalOcean droplet's IP address. Consult the [DigitalOcean DNS documentation](https://docs.digitalocean.com/products/networking/dns/getting-started/dns-registrars/) for more information. Use [certbot](https://certbot.eff.org/) to configure enable HTTPS in your server. First, install the required packages on your system: ```bash sudo apt install certbot python3-certbot-nginx -y ``` Next, run certbot: ```bash certbot --nginx ``` Enter your email address, agree to the Terms and Conditions, and choose your domain. When prompted if you want to automatically redirect HTTP traffic, choose option `2: Redirect`. Certbot will finish configuring Nginx. Once it is done, all traffic to your server will use HTTPS and you will have finished securing your Meilisearch instance. Your security certificate must be renewed every 90 days. Certbot schedules the renewal automatically. Run a test to verify this process is in place: ```bash sudo certbot renew --dry-run ``` If this command returns no errors, you have successfully enabled HTTPS in your Nginx server. ### Conclusion You have followed the main steps to provide a safe and stable service. Your Meilisearch instance is now up and running in a safe and publicly accessible environment thanks to the combination of a reverse proxy, HTTPS, and Meilisearch's built-in security keys. --- title: Deploy a Meilisearch instance on AWS — Meilisearch documentation description: Use Meilisearch's AMI to deploy on AWS in just a few minutes. sidebarDepth: 3 --- ## Deploy a Meilisearch instance on Amazon Web Services (AWS) Using our **Meilisearch [AMI](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AMIs.html)**, Meilisearch can be deployed on AWS in just a few minutes. The following guide will walk you through every step to deploy Meilisearch in an AWS EC2 instance. If you have any issues with our AWS image, please create an issue in [this repository](https://github.com/meilisearch/cloud-providers/). [Refer to AWS's documentation to learn more about creating and configuring instances.](https://docs.aws.amazon.com/) ### Part 1: Deploy an out-of-the-box Meilisearch instance #### 1. Launch an instance from the AWS console After logging into your [AWS Console](https://aws.amazon.com/console), navigate to the "Compute" service. Then go to "EC2", and finally open your "Instances" console. ![Page titled 'Instances'. Text in center of screen: You do not have any instances in this region](/assets/images/aws/01.launch-instances.png) In the top-right corner, click on the "Launch instances" button to start the process of configuring your Meilisearch instance. #### 2. Select 'Meilisearch' AMI from 'Community AMIs' You will now select which AMI or system Image to use to run your instance. Type `meilisearch` in the search bar and select the "Community AMIs" tab on the left sidebar. Meilisearch's owner id is 567502172578. ![Page titled: 'Step 1: Choose an Amazon Machine Image (AMI)'](/assets/images/aws/02.select-ami.png) Click on "Select" (right side of the screen) to confirm your choice. #### 3. Size and specs Select the specifications of the server you want Meilisearch to run on. ![Page titled: 'Step 2: Choose an Instance Type'. Selecting the free tier eligible instance type](/assets/images/aws/03.size-and-specs.png) We recommend prioritizing memory allocation for better Meilisearch performance. The free tier is sufficient for tests or prototypes, but not recommended for large datasets. Once you've made your choice, click on "Next: Configure instance details" to continue. #### 4. Instance details Here you can specify [details of your Instance](https://docs.aws.amazon.com/efs/latest/ug/gs-step-one-create-ec2-resources.html). Since **this section is not required to run Meilisearch**, we won't cover it in this guide. ![Page titled 'Step 3: Configure Instance Details'. Important: You can launch multiple instances from the same AMI, request Spot instances to take advantage of lower pricing, and assign access management role to the instance.](/assets/images/aws/04.instance-details.png) Click "Next: Add Storage" to keep going. #### 5. Storage Choose the storage **device** and **size** for your Meilisearch instance. ![Page titled 'Step 4: Add Storage'. Text at bottom of screen: Free tier eligible users can get up to 30GB of EBS General Purpose (SSD) or Magnetic storage.](/assets/images/aws/05.storage.png) The amount of storage space required can [vary drastically](/learn/engine/storage#measured-disk-usage) depending on the data you plan to index. In this example, we will use 25 GiB, which is more than enough for most small datasets (< 1 million documents). We have the "Volume Type" set to "General Purpose SSD (gp2)". When you're ready, click on "Next: Add Tags" to continue. #### 6. Tags Tags are used to identify your resources in AWS. **They are not required by Meilisearch**. ![Page titled 'Step 5: Add Tags'. Text in center of screen: Make sure your IAM policy includes permissions to create tags. ](/assets/images/aws/06.tags.png) Click on "Next: Configure Security Groups". #### 7. Security groups: Networking and connectivity For your Meilisearch instance to communicate with the outside world, it is very important to allow SSH connections, HTTP, and HTTPS traffic. - Click on "Add rule" and select "SSH" from the drop-down menu. This will open the SSH port (22) - Click on "Add rule" and select "HTTP" from the drop-down menu. This will open the HTTP port (80) - Click on "Add rule" and select "HTTPS" from the drop-down menu. This will open the HTTPS port (443) ![Page titled 'Step 6: Configure Security group'. Warning: Rules with sources of 0.0.0.0/0 allow all IP addresses to access your instance. We recommend setting security group rules to allow access from known IP addresses only.](/assets/images/aws/07.security.png) By default, opened ports accept inbound traffic from any origin. If you prefer to restrict the IP addresses that are allowed to request your Meilisearch instance, go to the "Source" column and select the "Custom" option. The "Source" is set to "Anywhere" by default. You can also **use an existing security group**, if preferred. Once your configuration looks similar to the above image, click on "Review and Launch". #### 8. Set and download key pair Once you have reviewed your instance configuration, there is one last step before you can launch your Instance. Click on "Launch" and a pop-up window will ask you to select a **key pair**. This key pair is very important as it will be your private key to access the instance via SSH, which is required to [configure your Meilisearch instance in a production environment](#part-2-configure-production-settings). ![A popup titled: "Select an existing key pair or create a new key pair". Inside the popup, there is a form that allows you to configure key pairs. It also contains a warning: "Download and store your private key file in a secure accessible location. You cannot download it again once it has been created"](/assets/images/aws/08.key-pair.png) If you have an existing Key Pair, you can use that. Otherwise, select the option "Create a new key pair" and give it a name. Then, click on "Download Key Pair" and store this file somewhere safe. Once you've downloaded your key pair (and only then), click on "Launch Instances", then on "View Instances". #### 9. Enjoy your Meilisearch instance running on AWS! Your instance may take a minute or two to get up and running (see the "Instance state" column). ![AWS dashboard showing an active instance](/assets/images/aws/09.launch.png) Once the "Instance state" is "Running", use your web browser to navigate to the "Public IPv4 address" or the "Public IPv4 DNS" displayed in your AWS instances dashboard. You should see the Meilisearch local preview. ![Meilisearch local preview allowing users to search an example dataset](/assets/images/aws/10.enjoy.png) Your Meilisearch instance is now ready to use! Keep in mind that your Meilisearch instance is currently running in a _development environment_, which is unsafe for production usage. If you want to set up a _production environment_, continue to the [next section](#part-2-configure-production-settings). Otherwise, if you want to get started creating indexes and adding documents, don't hesitate to check out our [getting started guide](/learn/self_hosted/getting_started_with_self_hosted_meilisearch) or [API reference](/reference/api/overview). And of course, **enjoy**! ### Part 2: Configure production settings Configuring your Meilisearch instance in a production environment is not just straightforward—it's completely automated. Simply establish an SSH connection with your instance, and a script will guide you through the process. #### 1. Make your domain name point to your instance IP If you want to use your own domain name (or sub-domain), add an `A record` in your domain name provider account. Otherwise, **you can skip this step**. ![An interface for editing DNS records with "Type": A, "Name": my-aws-instance, "IPv4 address": 35.180.61.104, and "TTL": Auto](/assets/images/aws/11.domain.png) Your domain name should now be linked to your Meilisearch instance. Run a health check to verify that your instance is running and your DNS is well configured: ```bash curl -v http:///health ``` The server should answer with a `200 OK` status code as shown in the example below: ```bash ... < HTTP/1.1 200 OK ... ``` #### 2. Set API key and SSL (HTTPS) Meilisearch is currently running in a **development** environment. You haven't set up an **API key**, meaning that anyone can read/write from your Meilisearch, and you aren't using HTTPS yet, which makes this configuration unsafe for **production**. To start the configuration process, connect via SSH to your new Meilisearch instance and follow the instructions that appear. #### 2.1. Secure your key pair Open a terminal window and navigate to wherever you saved your [key pair](#8-set-and-download-key-pair). It should be a `.pem` file. Run the following command to secure your key pair. ```bash chmod 400 .pem ``` #### 2.2. Run the configuration script Next, start a new SSH connection with the **Public IPv4 address** or **your domain name**, using 'admin' as the username. You'll also need to supply the relative path to your `.pem` file. ```bash ssh -i admin@ ``` ```bash ssh -i admin@ ``` You should see something like this: ``` ________________________________________________ ________________________________________________ _ _ _ __ _ /\/\ ___(_) (_) _\ ___ __ _ _ __ ___| |__ / \ / _ \ | | \ \ / _ \/ _` | '__/ __| '_ \ / /\/\ \ __/ | | |\ \ __/ (_| | | | (__| | | | \/ \/\___|_|_|_\__/\___|\__,_|_| \___|_| |_| ________________________________________________ ________________________________________________ ``` When asked if you would like to use Meilisearch in a production environment, write `yes` and press `Enter` to accept the authentication process. A script will run automatically, asking for your settings and desired configuration. If you want to run this script again at any time, you can do so by using the following command: ```bash meilisearch-setup ``` #### 3. Enjoy your ready-to-use Meilisearch instance Your Meilisearch Instance is up and running on AWS, and it is ready to be used in **production**. To check if everything is running smoothly, do another HTTP call to the `/health` route: ```bash curl -v https:///health ``` Note that this time, **we're using HTTPS.** The server should answer with a `200 OK` status code as shown in the example below: ```bash ... < HTTP/1.1 200 OK ... ``` You're all set to use Meilisearch in production with AWS! If you have any issues with our AWS image, please create an issue in [this repository]( https://github.com/meilisearch/cloud-providers/). --- title: Deploy a Meilisearch instance on DigitalOcean — Meilisearch documentation description: Deploy and configure Meilisearch on Digital Ocean in just a few steps. sidebarDepth: 3 --- ## Deploy a Meilisearch instance on DigitalOcean ### Part 1: Deploy Meilisearch on a Droplet #### 1. Create a new Droplet DigitalOcean Droplets are Linux-based virtual machines in which you can run your applications. Once you log in to your DigitalOcean account, click the green "Create" button at the top-right of the page and select "Droplets". ![Selecting "Droplets" from the "Create" dropdown](/assets/images/digitalocean/create.png) [Refer to DigitalOcean's documentation to learn more about creating and configuring Droplets.](https://docs.digitalocean.com/tutorials/droplets/) #### 2. Select a region for your Droplet Select the region where you want to deploy your Droplet. Remember, the closer you are to your users, the better their search experience with Meilisearch will be. ![Selecting the London data center region](/assets/images/digitalocean/select-region.png) #### 3. Select Meilisearch image By default, DigitalOcean displays the "OS" tab. Select the "Marketplace" tab, search for "Meilisearch", and select the image. ![Search results for 'Meilisearch' in Marketplace](/assets/images/digitalocean/marketplace.png) #### 4. Choose Droplet size This is where you choose the amount of RAM, storage, and CPU cores your Droplet will have. Select your plan based on your needs. Memory-optimized options will give you better results when working with big datasets. ![Selecting the plan based on your usage](/assets/images/digitalocean/select-plan.png) #### 5. Choose an authentication method You can either use SSH keys or a password to access your Droplet. We recommend using SSH keys as they are more secure. ![Selecting SSH keys for authentication](/assets/images/digitalocean/add-ssh-key.png) Select the SSH keys you want to add to your Droplet. If you don't have a key, [follow DigitalOcean's instructions on how to create one](https://www.digitalocean.com/docs/droplets/how-to/add-ssh-keys/to-account/). #### 6. Choose your Droplet name and tags Here you can select the name that will be visible everywhere in your DigitalOcean account. Droplets can only contain alphanumeric characters, dashes, and periods. ![Adding 'meilisearch-droplet-name' as the hostname](/assets/images/digitalocean/droplet-name.png) Tags are great for managing resources. They are custom labels you assign to droplets. Tags can contain letters, numbers, colons, dashes, and underscores. You can use multiple tags for a single resource. Try naming tags based on a droplet's function. ![The search bar, meilisearch, and search-team tags](/assets/images/digitalocean/add-tags.png) #### 7. Click on "Create Droplet" ![The "Create Droplet" button](/assets/images/digitalocean/create-droplet.png) #### 8. Test Meilisearch Once created, click on the Droplet's public IP address to copy it: ![meilisearch-droplet-name instance's IP: 165.227.56.77](/assets/images/digitalocean/copy-ip.png) Paste it into your browser. If you can access the local preview, Meilisearch is ready to use. ![Meilisearch local preview](/assets/images/digitalocean/test-meili.png) ### Part 2: Configure production settings in your Meilisearch Droplet To configure Meilisearch for **production** on a DigitalOcean Droplet, [use SSH to access your Droplet](https://docs.digitalocean.com/products/droplets/how-to/connect-with-ssh/) and a script will guide you through the process. Alternatively, use the [Droplet Console](https://docs.digitalocean.com/products/droplets/how-to/connect-with-console/) with your preferred browser. #### 1. Make your domain name point to your Droplet If you want to use your own domain, click the "Create" button and select "Domain/DNS". ![Selecting Domain/DNS from the Create menu](/assets/images/digitalocean/domain.png) Type in your domain name in the "Enter domain field" and click "Add Domain". ![Domains tab on the Networking page](/assets/images/digitalocean/add-domain.png) This should work out of the box. Your domain name should now be linked to your Meilisearch instance. Use `curl` to access it and verify DNS has been properly configured: ```bash curl -v http:///health ``` The server should answer with a `200 OK` status code and the following body `{"status": "available"}`: ```bash … HTTP/1.1 200 OK … {"status": "available"} … ``` #### 2. Set master key and SSL (HTTPS) Meilisearch is currently running in a **development** environment. We haven't set up a master key, meaning anyone can read/write to the Meilisearch instance. Since we aren't using HTTPS yet, this configuration is unsafe for **production**. To start the configuration process, either connect to your Droplet via SSH or use the Droplet Console in your preferred browser and follow the instructions: #### 2.1. Run the configuration script Open a terminal and start a new SSH connection with the IP you got from DigitalOcean. Type in the following command in your terminal and press Enter to establish a connection: ```bash ssh root@DIGITAL_OCEAN_IP_ADDRESS ``` Type `yes` and press Enter to accept the authentication process. The above command is not required if you are using the Droplet Console. A script will run automatically, asking for your settings and desired configuration. If you want to run this script again anytime, you can do so by using the following command: ```bash meilisearch-setup ``` The same script will run automatically if you use the Droplet Console. #### 3. Enjoy your ready-to-use Meilisearch droplet Your Meilisearch Droplet is ready to be used in **production**. To check if everything is running smoothly, do an HTTP call to the `/health` route: ```bash curl -v https:///health ``` The server should answer with a `200 OK` status code and the following body `{"status": "available"}` as shown in the example below: ```bash … HTTP/1.1 200 OK … {"status": "available"} … ``` --- title: Deploy Meilisearch on Koyeb — Meilisearch documentation description: Deploy Meilisearch on Koyeb using a simplified one-click deploy with default settings compatible with most use-cases. --- ## Deploy Meilisearch on Koyeb ### Introduction This guide explains how to deploy a ready-to-use Meilisearch instance on Koyeb. [Koyeb](https://www.koyeb.com) is a developer-friendly serverless platform to deploy apps globally. The platform lets you seamlessly run Docker containers, web apps, and APIs with git-based deployment, TLS encryption, native autoscaling, a global edge network, and built-in service mesh & discovery. ### Requirements To successfully follow and complete this guide, you need a [Koyeb account](https://app.koyeb.com). ### Deploy Meilisearch The fastest way to deploy Meilisearch on Koyeb is to use the **Deploy to Koyeb** button. [](https://app.koyeb.com/deploy?type=docker&image=getmeili/meilisearch&name=meilisearch-on-koyeb&ports=7700;http;/&env[MEILI_MASTER_KEY]=REPLACE_ME_WITH_A_STRONG_KEY) Take care to replace the `MEILI_MASTER_KEY` environment variable value with a strong key to secure your Meilisearch instance. You can for instance run the following command from the terminal to generate a strong secret to use as a master key: ```bash python -c 'import os,base64; print(base64.urlsafe_b64encode(os.urandom(32)).decode())' ``` Using a master key is optional but strongly recommended when running in production. If you launch without a master key, your Meilisearch instance will be unprotected and publicly accessible. #### Test Meilisearch Copy the public URL (for example, `https://meili-myorg.koyeb.app`) from the [Koyeb control panel](https://app.koyeb.com) and paste it in your browser. You should land on the Meilisearch [search preview](/learn/getting_started/search_preview), where you are asked to enter your master key. You are now ready to [create your first index](/learn/self_hosted/getting_started_with_self_hosted_meilisearch)! **Enjoy**! --- title: Deploy a Meilisearch instance on Qovery — Meilisearch documentation description: Deploy Meilisearch on Qovery in six steps. sidebarDepth: 3 --- ## Deploy a Meilisearch instance on Qovery [Qovery](https://www.qovery.com) is a fully-managed cloud platform that runs on your AWS, DigitalOcean, or Scaleway account where you can host static sites, backend APIs, databases, cron jobs, and all your other apps in one place. Qovery provides **free hosting** for individual developers and includes the following features: * Continuous, automatic builds & deploys from GitHub and GitLab * Automatic SSL certificates through [Let's Encrypt](https://letsencrypt.org) * Free SSD storage * Unlimited collaborators * Unlimited [custom domains](https://hub.qovery.com/docs/using-qovery/configuration/application/#domains) ### Setup #### 1. Create a Qovery account Visit the [Qovery dashboard](https://start.qovery.com) to create an account if you don't already have one. #### 2. Create a project * Click on **Create project** and give a name to your project * Click on **Next** !["Create Project" button](https://hub.qovery.com/img/heroku/heroku-2.png) #### 3. Create a new environment * Click on **Create environment** and give it a name (for example, staging, production). !["Create environment" button](https://hub.qovery.com/img/heroku/heroku-3.png) #### 4. Add your Meilisearch app * Click on **Create an application**, give it a name, and select the GitHub or GitLab repository where your Meilisearch app is located * Define the main branch name and the root application path * Click on **Create** ![Choose your repository in the "Create Application" pop-up](https://hub.qovery.com/img/rust/rust.png) After the application has been created: * Navigate to your application **Settings** * Select **Port** * Add port used by your Meilisearch application #### 5. Add storage To add storage, go to your application **Settings**: ![Set storage to 10GB SSD](https://hub.qovery.com/img/add-storage.png) #### 6. Deploy the app on Qovery All you have to do now is to navigate to your application and click on **Deploy**. ![Choose "Deploy" from the "Actions" dropdown](https://hub.qovery.com/img/heroku/heroku-1.png) That's it! Watch the status and wait until the app is deployed. To open the application in your browser, click on **Action** and **Open** in your application overview. ### Support Chat with Qovery developers on [Discord](https://discord.qovery.com) if you need help. --- title: Deploy a Meilisearch instance on Railway — Meilisearch documentation description: This article covers how to deploy Meilisearch on Railway with a single click and how to secure your newly-created instance. --- ## Deploy a Meilisearch instance on Railway ### Introduction This guide explains how to deploy a ready-to-use Meilisearch instance on Railway. [Railway](https://railway.app) is a deployment platform where you can provision infrastructure, develop with that infrastructure locally, and then deploy to the cloud. Railway aims to be the simplest way to develop, deploy, and diagnose issues with your application. ### Requirements To follow along, you need a [Railway account](https://railway.app). If you don't have one, you can visit the link above and click on "Login" in the top right corner to log in either with your GitHub account or email. ### Deploy Meilisearch Click the button below to deploy a Meilisearch instance to Railway quickly. [![Deploy on Railway](https://railway.app/button.svg)](https://railway.app/new/template/meilisearch) #### Environment Variables `MEILI_ENV`: by default, this template sets the `MEILI_ENV` environment variable to `production`. If you would like access to the Meilisearch [search preview](/learn/getting_started/search_preview), update `MEILI_ENV` to `development`. `MEILI_MASTER_KEY`: replace the `MEILI_MASTER_KEY` environment variable with a strong key to secure your Meilisearch instance. If you want to quickly generate a secure random key, you can run the following command from your terminal: ```bash openssl rand -base64 48 ``` To define the desired length of your password, you can either add `| cut -c-${DESIRED_LENGTH}` or `| head -c${DESIRED_LENGTH}` to the command as such: ```bash openssl rand -base64 48 | cut -c1-32 ``` ```bash openssl rand -base64 48 | head -c32 ``` which in this case will generate a 32-character long string. Setting a master key is optional, but without it, your server will accept unidentified requests, which can affect your usage quota on the server. If you need some protection in production, we strongly recommend setting a master key. #### Test Meilisearch If you have set the `MEILI_ENV` environment variable to `development` in the Railway service, you will have access to the Meilisearch [search preview](/learn/getting_started/search_preview). Copy the public URL (for example, `meilisearch-production-up.railway.app`) of your project from your [Railway account dashboard](https://railway.app/dashboard) and paste it into your browser. ![Railway dashboard](/assets/images/railway/public-url.png) You should land on the Meilisearch [search preview](/learn/getting_started/search_preview), where you will be asked to enter your master key. You are now ready to [create your first index](/learn/self_hosted/getting_started_with_self_hosted_meilisearch)! **Enjoy**! --- title: Integrate Meilisearch Cloud with Vercel — Meilisearch documentation description: Link Meilisearch Cloud to a Vercel Project. --- ## Integrate Meilisearch Cloud with Vercel In this guide you will learn how to link a [Meilisearch Cloud](https://www.meilisearch.com/cloud?utm_campaign=oss&utm_source=docs&utm_medium=vercel-integration) instance to your Vercel project. ### Introducing our tools #### What is Vercel? [Vercel](https://vercel.com/) is a cloud platform for building and deploying web applications. It works out of the box with most popular web development tools. #### What is Meilisearch Cloud? [Meilisearch Cloud](https://www.meilisearch.com/cloud?utm_campaign=oss&utm_source=docs&utm_medium=vercel-integration) offers a managed search service that is scalable, reliable, and designed to meet the needs of all companies. ### Integrate Meilisearch into your Vercel project #### Create and deploy a Vercel project From your Vercel dashboard, create a new project. You can create a project from a template, or import a Git repository. ![Create a new project on Vercel dashboard](/assets/images/vercel/01.create-new-project-on-vercel-dashboard.png) Select your project, then click on **Deploy**. Once deployment is complete, go back to your project’s dashboard. #### Add the Meilisearch integration Go to the project settings tab and click on **Integrations** on the sidebar menu to the left of your screen. ![Selecting the integration tab in the project settings](/assets/images/vercel/02.project-settings-integrations-tab.png) Search for the [Meilisearch integration](https://vercel.com/integrations/meilisearch-cloud) in the search bar. Click on the **Add integration** button. ![Meilisearch integration page in Vercel's marketplace](/assets/images/vercel/03.meilisearch-cloud-integration-page-in-marketplace.png) Select the Vercel account or team and the project you to which you want to add the integration. You may add the Meilisearch integration to one or more projects in this menu. ![Form to add Meilisearch integration, the "Specific projects" option is selected](/assets/images/vercel/04.add-meilisearch-cloud-form.png) Click on **Continue**. Vercel will display a list with the permissions the integration needs to work properly. Review it, then click on **Add Integration**. #### Set up Meilisearch Cloud Vercel will redirect you to the Meilisearch Cloud page. Log in or create an account. New accounts enjoy a 14-day free trial period. You can choose an existing project or create a new one. To create a new project, complete the form with the project name and region. ![Meilisearch Cloud form to create a project complete, with "search-app" as the project's name and "Frankfurt" as the region](/assets/images/vercel/05.create-a-meilisearch-cloud-project-form.png) Once you click on **Create project**, you should see the following message: “Your Meilisearch + Vercel integration is one click away from being completed.” Click "Finish the Vercel integration setup". Meilisearch will then redirect you back to the Vercel integration page. ![Meilisearch integration page in Vercel's dashboard](/assets/images/vercel/06.meilisearch-cloud-integration-page-in-vercel-dashboard.png) #### Understand and use Meilisearch API keys Meilisearch creates two default API keys: [`Default Search API Key` and `Default Admin API Key`](/learn/security/basic_security#obtaining-api-keys). ##### Admin API key Use the `Default Admin API Key`, to control who can access or create new documents, indexes, and change index settings. Be careful with the admin key and avoid exposing it in public environments. ##### Search API key Use the `Default Search API Key` to access the [search route](/reference/api/search). This is the one you want to use in your front end. Both keys are automatically added to Vercel along with the Meilisearch URL. The master key–which hasn’t been added to Vercel–grants users full control over an instance. You can find it in your project’s overview on your [Meilisearch Cloud dashboard](https://cloud.meilisearch.com/projects/?utm_campaign=oss&utm_source=docs&utm_medium=vercel-integration). Read more about [Meilisearch security](https://www.meilisearch.com/docs/learn/security/master_api_keys). #### Review your project settings Go back to your project settings and check the new Meilisearch environment variables: - `MEILISEARCH_ADMIN_KEY` - `MEILISEARCH_URL` - `MEILISEARCH_SEARCH_KEY` ![Display the environment variables in the project settings](/assets/images/vercel/07.project-settings-environment-variables-tab.png) When using [Next.js](https://nextjs.org/), ensure you prefix your browser-facing environment variables with `NEXT_PUBLIC_`. This makes them available to the browser side of your application. ### Take advantage of the Meilisearch Cloud dashboard ![Meilisearch Cloud dashboard: overview of the "search-app" project](/assets/images/vercel/08.meilisearch-cloud-dashboard.png) Use the [Meilisearch Cloud dashboard](https://cloud.meilisearch.com/projects/?utm_campaign=oss&utm_source=docs&utm_medium=vercel-integration), to index documents and manage your project settings. ### Resources and next steps Check out the [quick start guide](/learn/self_hosted/getting_started_with_self_hosted_meilisearch#add-documents) for a short introduction on how to use Meilisearch. We also provide many [SDKs and tools](/learn/resources/sdks), so you can use Meilisearch in your favorite language or framework. You are now ready to [start searching](/reference/api/search)! --- title: Postman collection for Meilisearch — Meilisearch documentation description: This how-to guide explains how to use Postman when testing and debugging Meilisearch's API. --- ## Postman collection for Meilisearch Are you tired of using the `curl` command in your terminal to test Meilisearch? It can be tedious to re-write every route when wanting to try out an API. Postman is a platform that lets you create HTTP requests you can easily reuse and share with everyone. We provide a Postman collection containing all the routes of the Meilisearch API! 🚀 If you don't have Postman already, you can [download it here](https://www.postman.com/downloads/). It's free and available on many OS distributions. ### Import the collection Once you have downloaded the [Postman collection](https://raw.githubusercontent.com/meilisearch/documentation/main/assets/misc/meilisearch-collection-postman.json), you need to import it into Postman. ![The "Import" button](/assets/images/postman/import.png) ### Edit the configuration ![Selecting "Edit" from the overflow menu](/assets/images/postman/edit.png) Set the "Token" if needed (set to `masterKey` by default): ![The "Token" field set to masterKey and "Type" to Bearer Token in the "Authorization" tab.](/assets/images/postman/set_token.png) Set `url` (set to Meilisearch's local port by default) and `indexUID` (set to `indexUID` by default): ![Setting the "URL" to http://localhost:7700/ and "indexUID" to indexUId in the Variables tab.](/assets/images/postman/set_variables.png) The `url` and `indexUID` variables are used in all the collection routes, like in this one: ![Highlighting {{url}} and {{indexUID}}](/assets/images/postman/url.png) ### Start to use it! You can now [run your Meilisearch instance](/learn/self_hosted/getting_started_with_self_hosted_meilisearch#setup-and-installation) and create your first index: ![The "Send" button](/assets/images/postman/create_index.png) --- title: Using Meilisearch with Docker — Meilisearch documentation description: Learn how to use Docker to download and run Meilisearch, configure its behavior, and manage your Meilisearch data. --- ## Using Meilisearch with Docker In this guide you will learn how to use Docker to download and run Meilisearch, configure its behavior, and manage your Meilisearch data. Docker is a tool that bundles applications into containers. Docker containers ensure your application runs the same way in different environments. When using Docker for development, we recommend following [the official instructions to install Docker Desktop](https://docs.docker.com/get-docker/). ### Download Meilisearch with Docker Docker containers are distributed in images. To use Meilisearch, use the `docker pull` command to download a Meilisearch image: ```sh docker pull getmeili/meilisearch:v1.14 ``` Meilisearch deploys a new Docker image with every release of the engine. Each image is tagged with the corresponding Meilisearch version, indicated in the above example by the text following the `:` symbol. You can see [the full list of available Meilisearch Docker images](https://hub.docker.com/r/getmeili/meilisearch/tags#!) on Docker Hub. The `latest` tag will always download the most recent Meilisearch release. Meilisearch advises against using it, as it might result in different machines running different images if significant time passes between setting up each one of them. ### Run Meilisearch with Docker After completing the previous step, use `docker run` to launch the Meilisearch image: ```sh docker run -it --rm \ -p 7700:7700 \ -v $(pwd)/meili_data:/meili_data \ getmeili/meilisearch:v1.14 ``` #### Configure Meilisearch Meilisearch accepts a number of instance options during launch. You can configure these in two ways: environment variables and CLI arguments. Note that some options are only available as CLI arguments—[consult our configuration reference for more details](/learn/self_hosted/configure_meilisearch_at_launch). ##### Passing instance options with environment variables To pass environment variables to Docker, add the `-e` argument to `docker run`. The example below launches Meilisearch with a master key: ```sh docker run -it --rm \ -p 7700:7700 \ -e MEILI_MASTER_KEY='MASTER_KEY'\ -v $(pwd)/meili_data:/meili_data \ getmeili/meilisearch:v1.14 ``` ##### Passing instance options with CLI arguments If you want to pass command-line arguments to Meilisearch with Docker, you must add a line to the end of your `docker run` command explicitly launching the `meilisearch` binary: ```sh docker run -it --rm \ -p 7700:7700 \ -v $(pwd)/meili_data:/meili_data \ getmeili/meilisearch:v1.14 \ meilisearch --master-key="MASTER_KEY" ``` ### Managing data When using Docker, your working directory is `/meili_data`. This means the location of your database file is `/meili_data/data.ms`. #### Data persistency By default, data written to a Docker container is deleted every time the container stops running. This data includes your indexes and the documents they store. To keep your data intact between reboots, specify a dedicated volume by running Docker with the `-v` command-line option: ```sh docker run -it --rm \ -p 7700:7700 \ -v $(pwd)/meili_data:/meili_data \ getmeili/meilisearch:v1.14 ``` The example above uses `$(pwd)/meili_data`, which is a directory in the host machine. Depending on your OS, mounting volumes from the host to the container might result in performance loss and is only recommended when developing your application. #### Generating dumps and updating Meilisearch To export a dump, [use the create dump endpoint as described in our dumps guide](/learn/advanced/dumps). Once the task is complete, you can access the dump file in `/meili_data/dumps` inside the volume you passed with `-v`. To import a dump, use Meilisearch's `--import-dump` command-line option and specify the path to the dump file. Make sure the path points to a volume reachable by Docker: ```sh docker run -it --rm \ -p 7700:7700 \ -v $(pwd)/meili_data:/meili_data \ getmeili/meilisearch:v1.14 \ meilisearch --import-dump /meili_data/dumps/20200813-042312213.dump ``` Note that exporting and importing dumps require using command-line arguments. [For more information on how to run Meilisearch with CLI options and Docker, refer to this guide's relevant section.](#passing-instance-options-with-cli-arguments) If you are storing your data in a persistent volume as instructed in [the data persistency section](#data-persistency), you must delete `/meili_data/data.ms` in that volume before importing a dump. Use dumps to migrate data between different Meilisearch releases. [Read more about updating Meilisearch in our dedicated guide.](/learn/update_and_migration/updating) #### Snapshots To generate a Meilisearch snapshot with Docker, launch Meilisearch with `--schedule-snapshot` and `--snapshot-dir`: ```sh docker run -it --rm \ -p 7700:7700 \ -v $(pwd)/meili_data:/meili_data \ getmeili/meilisearch:v1.14 \ meilisearch --schedule-snapshot --snapshot-dir /meili_data/snapshots ``` `--snapshot-dir` should point to a folder inside the Docker working directory for Meilisearch, `/meili_data`. Once generated, snapshots will be available in the configured directory. To import a snapshot, launch Meilisearch with the `--import-snapshot` option: ```sh docker run -it --rm \ -p 7700:7700 \ -v $(pwd)/meili_data:/meili_data \ getmeili/meilisearch:v1.14 \ meilisearch --import-snapshot /meili_data/snapshots/data.ms.snapshot ``` Use snapshots for backup or when migrating data between two Meilisearch instances of the same version. [Read more about snapshots in our guide.](/learn/advanced/snapshots)

{{ item.name }}