This quick start will walk you through setting up Meilisearch, adding documents, performing your first search, using the search preview, adding a search bar, and securing your instance.
All that is required is a command line for installation, and some way to interact with Meilisearch afterwards (for example, cURL or one of our SDKs).
Let's get started!
We'll start with downloading and installing Meilisearch. You have the option to install Meilisearch locally or deploy it over a cloud service.
:::: tabs
::: tab cURL Download the latest stable release of Meilisearch with cURL.
Launch Meilisearch to start the server.
# Install Meilisearch
curl -L https://install.meilisearch.com | sh
# Launch Meilisearch
./meilisearch:::
::: tab Homebrew Download the latest stable release of Meilisearch with Homebrew, a package manager for MacOS.
Launch Meilisearch to start the server.
# Update brew and install Meilisearch
brew update && brew install meilisearch
# Launch Meilisearch
meilisearch:::
::: tab Docker When using Docker, you can run any available tag.
These commands launch the latest stable release of Meilisearch.
# Fetch the latest version of Meilisearch image from DockerHub
docker pull getmeili/meilisearch:v0.30
# Launch Meilisearch in development mode with a master key
docker run -it --rm \
-p 7700:7700 \
-e MEILI_MASTER_KEY='MASTER_KEY'\
-v $(pwd)/meili_data:/meili_data \
getmeili/meilisearch:v0.30 \
meilisearch --env="development"You can learn more about using Meilisearch with Docker in our dedicated guide. :::
::: tab APT
Download the latest stable release of Meilisearch with APT.
Launch Meilisearch to start the server.
# Add Meilisearch package
echo "deb [trusted=yes] https://apt.fury.io/meilisearch/ /" | sudo tee /etc/apt/sources.list.d/fury.list
# Update APT and install Meilisearch
sudo apt update && sudo apt install meilisearch-http
# Launch Meilisearch
meilisearch:::
::: tab Source
Meilisearch is written in Rust. To compile it, install the Rust toolchain.
If the Rust toolchain is already installed, clone the repository on your local system and change it to your working directory.
git clone https://github.com/meilisearch/meilisearch
cd meilisearchChoose the release you want to use. You can find the full list here.
In the cloned repository, run the following command to access the most recent version of Meilisearch:
git checkout latestFinally, update the rust toolchain, compile the project, and execute the binary.
# Update the rust toolchain to the latest version
rustup update
# Compile the project
cargo build --release
# Execute the server binary
./target/release/meilisearch:::
::: tab Windows
To install Meilisearch on Windows, you can:
- Use Docker (see "Docker" tab above)
- Download the latest binary (see "Direct download" tab above)
- Use the installation script (see "cURL" tab above) if you have installed Cygwin, WSL, or equivalent
- Compile from source (see "Source" tab above)
To learn more about the Windows command prompt, follow this introductory guide.
:::
::: tab Direct download
If none of the other installation options work for you, you can always download the Meilisearch binary directly on GitHub.
Go to the latest Meilisearch release, scroll down to "Assets", and select the binary corresponding to your operating system.
:::
::::
To deploy Meilisearch on a cloud service, follow one of our dedicated guides:
On successfully running Meilisearch, you should see the following response:
888b d888 d8b 888 d8b 888
8888b d8888 Y8P 888 Y8P 888
88888b.d88888 888 888
888Y88888P888 .d88b. 888 888 888 .d8888b .d88b. 8888b. 888d888 .d8888b 88888b.
888 Y888P 888 d8P Y8b 888 888 888 88K d8P Y8b "88b 888P" d88P" 888 "88b
888 Y8P 888 88888888 888 888 888 "Y8888b. 88888888 .d888888 888 888 888 888
888 " 888 Y8b. 888 888 888 X88 Y8b. 888 888 888 Y88b. 888 888
888 888 "Y8888 888 888 888 88888P' "Y8888 "Y888888 888 "Y8888P 888 888
Database path: "./data.ms"
Server listening on: "localhost:7700"
Congratulations! You're ready to move on to the next step!
For this quick start, we will be using a collection of movies as our dataset. To follow along, first click this link to download the file: movies.json. Then, move the downloaded file into your working directory.
Open a new terminal window and run the following command:
Meilisearch stores data in the form of discrete records, called documents. Documents are grouped into collections, called indexes.
::: note Meilisearch currently only accepts data in JSON, NDJSON, and CSV formats. You can read more about this in our documents guide. :::
The previous command added documents from movies.json to a new index called movies and set id as the primary key. If it isn't set manually, Meilisearch infers it from your dataset.
Every index must have a primary key, an attribute shared across all documents in that index. If you try adding documents to an index and even a single one is missing the primary key, none of the documents will be stored.
By default, Meilisearch combines consecutive document requests into a single batch and processes them together. This process is called auto-batching, and it significantly speeds up indexing. After adding documents, you should receive a response like this:
{
"taskUid": 0,
"indexUid": "movies",
"status": "enqueued",
"type": "documentAdditionOrUpdate",
"enqueuedAt": "2021-08-11T09:25:53.000000Z"
}Most database operations in Meilisearch are asynchronous. This means that rather than being processed instantly, API requests are added to a queue and processed one at a time.
Use the returned taskUid to check the status of your documents:
If the document addition is successful, the response should look like this:
{
"uid": 0,
"indexUid": "movies",
"status": "succeeded",
"type": "documentAdditionOrUpdate",
"canceledBy": null,
"details":{
"receivedDocuments": 19547,
"indexedDocuments": 19547
},
"error": null,
"duration": "PT0.030750S",
"enqueuedAt": "2021-12-20T12:39:18.349288Z",
"startedAt": "2021-12-20T12:39:18.352490Z",
"finishedAt": "2021-12-20T12:39:18.380038Z"
}If the status field has the value enqueued or processing, all you have to do is wait a short time and check again. Proceed to the next step once the task status has changed to succeeded.
Now that you have Meilisearch set up, you can start searching!
In the above code sample, the parameter q represents the search query. The documents you added in the previous step will be searched for text that matches botman.
Meilisearch response:
{
"hits": [
{
"id": 29751,
"title": "Batman Unmasked: The Psychology of the Dark Knight",
"poster": "https://image.tmdb.org/t/p/w1280/jjHu128XLARc2k4cJrblAvZe0HE.jpg",
"overview": "Delve into the world of Batman and the vigilante justice tha",
"release_date": "2008-07-15"
},
{
"id": 471474,
"title": "Batman: Gotham by Gaslight",
"poster": "https://image.tmdb.org/t/p/w1280/7souLi5zqQCnpZVghaXv0Wowi0y.jpg",
"overview": "ve Victorian Age Gotham City, Batman begins his war on crime",
"release_date": "2018-01-12"
},
…
],
"estimatedTotalHits": 66,
"query": "botman",
"limit": 20,
"offset": 0,
"processingTimeMs": 12
}By default, Meilisearch only returns the first 20 results for a search query. This can be changed using the limit parameter.
Meilisearch offers a browser-based search preview where you can search through a selected index. You can access it any time Meilisearch is running at http://localhost:7700.
For security reasons, the search preview is only available in development mode.
If you have multiple indexes, you can switch between them using the indexes dropdown.
At this point, you can configure your entire Meilisearch instance, customize your indexes, and refine your results using:
The only step missing now is adding a search bar to your project. The easiest way of achieving this is to use instant-meilisearch: a plugin that establishes communication between your Meilisearch instance and InstantSearch. InstantSearch, an open-source project developed by Algolia, is the tool that renders all the components needed to start searching.
- Create an empty file and name it
index.html - Open it in a text editor like Notepad, Sublime Text, or Visual Studio Code
- Copy-paste one of the code samples above—either vanilla JavaScript, Vue 2, or React— and save the file
- Open
index.htmlin your browser by double-clicking it in your folder
You should now have a working front-end search interface 🚀🔥
The Meilisearch API is unprotected by default, making all routes publicly accessible. You can set a master key to protect your instance from unauthorized use:
:::: tabs
::: tab CLI
./meilisearch --master-key="MASTER_KEY":::
::: tab Environment variable
UNIX:
export MEILI_MASTER_KEY="MASTER_KEY"
./meilisearchWindows:
set MEILI_MASTER_KEY="MASTER_KEY"
./meilisearch:::
::::
When you launch your Meilisearch instance with a master key, two things happen:
- Your Meilisearch instance is now protected. Aside from the get health endpoint, all subsequent API requests must include a valid API key for authorization
- Two default API keys are automatically generated
Here's how to use the master key you set to get all keys:
The master key should only be used for retrieving and managing API keys. For regular API calls, such as search, use an API key:
::: warning
Accessing the /keys route without setting a master key will return an error.
:::
To learn more about key management, refer to our dedicated guide.
You now know all the basics: how to install Meilisearch, create an index, add documents, check the status of an asynchronous task, and perform a search.
To keep going, continue to the Meilisearch 101 for a guided overview of the main features, or check out the API references to dive right in!