How to Use Meilisearch: The Beginner's Guide (First Server, First Index, First Search, and the Master-Key Rule)

CodexFuse Team · 2026-10-31T03:57:27.257Z · 12 min read

Learn how to use Meilisearch: start the server with Docker, add your first documents, run your first typo-tolerant search, and wire it into your app.

How to Use Meilisearch: The Beginner's Guide (First Server, First Index, First Search, and the Master-Key Rule)

Learning how to use Meilisearch is the moment a developer stops dreading the word "search." Meilisearch is an open-source, Rust-based search engine that gives your app instant, typo-tolerant full-text search through a simple REST API — no cluster to configure, no relevance-tuning PhD required. This meilisearch tutorial — a complete meilisearch for beginners guide — runs the whole ladder in one sitting: start your first server with Docker, protect it with a master key, add your first documents (and understand why indexing is asynchronous), run your first search with a deliberate typo, tune the settings that control relevance, and wire a real search box into a website. Along the way you will learn the one rule that keeps every beginner deployment safe: the master key lives in environment variables, never in code.

You will build in this order: generate a master key, start Meilisearch with one Docker command, verify the server with the version endpoint, index a small set of documents with the JavaScript client, poll the async task until it succeeds, run your first typo-tolerant search, adjust searchable and filterable attributes, and connect a search box with the official instant-search adapter. Once the REST API is responding, you can probe every endpoint in this guide with a free REST API tester before you write a line of client code.

What is Meilisearch and why would you use it?

Meilisearch is a search engine you run next to your app so your users can search your content — products, docs, blog posts, anything stored as JSON — and get relevant results in milliseconds, even when they misspell the query. It exists for one specific frustration: your database's LIKE queries are slow and dumb, and Elasticsearch is a second infrastructure project you never asked for. Meilisearch sits in the middle — smarter than SQL search, lighter than a full search cluster.

The engine is open source (MIT) and ships as a single binary or Docker image, which is why the meilisearch self hosted version has no feature limits: the community guides describe sub-50ms responses on millions of documents with typo tolerance working out of the box. Whichever path you take, the meilisearch install itself takes seconds — the learning curve is in keys, tasks, and settings, which is what this guide covers. There is also a managed option, Meilisearch Cloud, which LogRocket's July-2026-updated guide describes as carrying a 14-day free trial with a web dashboard — the fastest way to follow this tutorial without touching Docker. Whether you choose Cloud or self-hosted, the API is identical from this point onward, so nothing in this guide locks you into one path.

What do you need before you start?

You need three things: Docker installed, a terminal, and about fifteen minutes. If Docker is new to you, work through a Docker beginner guide first — Meilisearch is a multi-option app but the one-command Docker start in this guide assumes you can run a container. You do not need a JavaScript project yet; the guide uses curl for the API steps and adds the JavaScript client later.

If you want Meilisearch running 24/7 instead of on your laptop, you need a server. A small VPS is the standard home for it — see what is VPS hosting if that term is new — and every command in this guide works there unchanged. The only decision to make now is Cloud versus self-hosted: Cloud removes the server step entirely, self-hosted keeps your data on your own machine with zero usage limits.

How do you start your first Meilisearch server?

You start Meilisearch with one Docker command plus a master key — the whole 30-second arc is: generate the key, launch the container with a data volume, and verify the server answers.

1. Generate a master key. The master key is the password that protects your entire instance, and Meilisearch requires it to be at least 16 bytes. Generate a random one with openssl rand -hex 16 (or openssl rand -base64 16), and store it in an environment variable: export MEILI_MASTER_KEY=$(openssl rand -hex 16). This is the key-generation approach the Scaleway deployment docs and community guides both use — never type a memorable password here, and never paste the key into code samples you share.
2. Launch the container with a data volume. This meilisearch docker command is the only install step most readers will ever run: docker run -d -p 7700:7700 -e MEILI_MASTER_KEY="$MEILI_MASTER_KEY" -v $(pwd)/meili_data:/meili_data getmeili/meilisearch. The -v mount is load-bearing: Meilisearch stores its database inside /meili_data in the container, so without the volume your entire index vanishes every time the container stops. The official Docker guide (updated 2026-07-03) confirms the working directory is /meili_data and that a dedicated volume is how you keep data intact between reboots.
3. Verify the server answers. Run curl -H "Authorization: Bearer $MEILI_MASTER_KEY" http://localhost:7700/version. A JSON response with the version means your server is up. Note the header: current Meilisearch authenticates with the standard Authorization: Bearer header — LogRocket's July 2026 update flags that the old X-Meili-API-Key header is no longer used, so any tutorial still showing it is stale.
4. Decide about analytics. Meilisearch collects anonymous usage analytics by default; the community Docker guides set MEILI_NO_ANALYTICS=true to disable it. Add -e MEILI_NO_ANALYTICS=true to your run command if you prefer a quiet instance.
5. Prefer the binary? Download it with curl -L https://install.meilisearch.com | sh and start it with ./meilisearch --db-path ./meili_data --http-addr 127.0.0.1:7700 --master-key "$MEILI_MASTER_KEY". The flags set the data directory, the listen address, and the key — the same three concepts as the Docker command, minus the container.

One more production note before you continue: never expose port 7700 to the internet without a master key set. An unprotected Meilisearch accepts writes from anyone who finds it — the key is the whole security model for a single instance.

How do you add your first documents?

You add documents with the JavaScript client, and you do not create the index first — your meilisearch first index is created implicitly the moment the first documents arrive. An index is simply a collection of documents, and each document needs a primary key that uniquely identifies it; if your JSON already has an id field, Meilisearch detects and uses it automatically, per LogRocket's current guide.

Install the meilisearch javascript client with npm install meilisearch and connect it — keeping the key in an environment variable, never hardcoded:

const { MeiliSearch } = require('meilisearch');

const client = new MeiliSearch({
  host: 'http://127.0.0.1:7700',
  apiKey: process.env.MEILI_MASTER_KEY,
});

const movies = [
  { id: 1, title: 'Inception', genre: 'Sci-Fi', year: 2010 },
  { id: 2, title: 'Interstellar', genre: 'Sci-Fi', year: 2014 },
  { id: 3, title: 'The Dark Knight', genre: 'Action', year: 2008 },
];

const task = await client.index('movies').addDocuments(movies);
console.log(task); // { taskUid: 0, status: 'enqueued', ... }

That response is the single most misunderstood part of Meilisearch: writes are asynchronous. The call does not return "done" — it returns a task with a taskUid and status enqueued, and the documents are not searchable until that task reaches succeeded. Searching immediately after adding documents and getting zero results is the classic beginner trap; the fix is to poll the task before your first search. Here is the arc the current guides teach:

let t = await client.tasks(task.taskUid);
while (t.status === 'enqueued' || t.status === 'processing') {
  await new Promise(r => setTimeout(r, 100));
  t = await client.tasks(task.taskUid);
}
console.log(t.status); // 'succeeded'

For a few dozen documents this loop finishes in well under a second; for a million-document import it is the honest progress bar. Only after succeeded should you run your first search — which is exactly what the next section does.

How do you run your first search?

You run your first search with one method call — and then you misspell the query on purpose, because the typo test is how you prove Meilisearch earned its reputation.

const index = client.index('movies');

// Exact match
const exact = await index.search('Inception');

// The typo test — note the missing 'e'
const typo = await index.search('Incepton');

// Filtered search with a limit
const filtered = await index.search('', {
  filter: 'genre = Sci-Fi AND year < 2012',
  sort: ['year:desc'],
  limit: 10,
});

The typo query still returns Inception. That is the default meilisearch typo tolerance at work: out of the box, Meilisearch forgives one typo in words of four or more characters and two typos in words of eight or more — the minWordSizeForTypos: { oneTypo: 4, twoTypos: 8 } defaults the community guides document. The empty-string query with a filter is equally useful: it turns the search endpoint into a faceted browser for your whole catalog, which is how most storefront search pages are actually built.

Prefer raw HTTP? The meilisearch search api is plain REST, and these equivalents use the same Bearer auth you verified with earlier:

curl 'http://localhost:7700/indexes/movies/search' \
  -H "Authorization: Bearer $MEILI_MASTER_KEY" \
  -d '{"q": "Incepton", "limit": 10}'

curl -X POST 'http://localhost:7700/indexes/movies/documents' \
  -H "Authorization: Bearer $MEILI_MASTER_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @movies.json

Every endpoint in this guide is reachable this way, which is why probing them with a REST client before writing code saves so much debugging time.

How do you make search results actually good?

You make results good by telling Meilisearch which fields matter — its defaults are sensible, but relevance is a configuration task, not magic. Four settings do almost all the work, and this decision table (an original summary of the settings the current guides document) tells you which one to reach for:

The single most common configuration mistake is filtering on a field you never declared filterable. Meilisearch rejects the query rather than silently ignoring the filter, so when a filter errors, check filterableAttributes first:

await client.index('movies').updateSettings({
  searchableAttributes: ['title', 'genre'],
  filterableAttributes: ['genre', 'year'],
  sortableAttributes: ['year'],
});

Settings changes are themselves async tasks, by the way — the same poll-until-succeeded habit from the indexing section applies before you re-test relevance.

How do you put Meilisearch search on a real website?

You put it on a website with the official instant-search adapter — a search box, live results, and facets with almost no custom code. The community guides wire it with react-instantsearch plus @meilisearch/instant-meilisearch:

import { InstantSearch, SearchBox, Hits } from 'react-instantsearch';
import { instantMeiliSearch } from '@meilisearch/instant-meilisearch';

const { searchClient } = instantMeiliSearch('http://localhost:7700', process.env.MEILI_SEARCH_KEY);

function Search() {
  return (
    <InstantSearch searchClient={searchClient} indexName="movies">
      <SearchBox />
      <Hits />
    </InstantSearch>
  );
}

Notice the key in that snippet is MEILI_SEARCH_KEY, not the master key — and that distinction is the whole security lesson of this section. The master key can do anything: add documents, change settings, delete indexes. A search-only API key can only search. Meilisearch lets you create scoped keys, and the rule is absolute: the browser gets a search-only key, the server keeps the master key. Shipping the master key in frontend JavaScript hands every visitor full write access to your search engine.

For multi-collection interfaces, the /multi-search endpoint runs one query across several indexes in a single request — the federated-search pattern the dev.to guides document for sites that search products, articles, and docs from one box.

Meilisearch vs Typesense vs Algolia vs Elasticsearch: which should you pick?

You pick by answering one question: who operates the search infrastructure, and what do they already know? These four are comparison options for the same job, not four guides — this section exists so you choose once, correctly:

For the beginner arc in this guide — a developer adding search to an app this week — Meilisearch and Typesense are the two self-hosted answers, Algolia is the pay-to-skip-ops answer, and Elasticsearch is the answer for teams that already run one.

What beginner mistakes break a Meilisearch setup?

Beginners break Meilisearch setups in the same five ways, and every one of them is in the table below so you can check yourself before you debug:

What is new in Meilisearch worth knowing about?

Worth knowing, not worth restructuring your first project around: LogRocket's July 2026 update documents that Meilisearch now supports hybrid and semantic search, conversational search, and AI-powered retrieval through a built-in /chats endpoint — the engine retrieves relevant documents from your indexes and passes them to an LLM you configure, with source citations. That is retrieval-augmented generation without a separate pipeline, and it is the direction the project is heading. Learn the core in this guide first; the AI features layer on top of the same indexes, keys, and API patterns.

Sources

Every fact in this guide was verified against sources fetched for this article — no numbers, commands, or claims were invented:

• LogRocket, "Getting started with Meilisearch: A complete guide" (updated July 2026) — Bearer authentication replacing X-Meili-API-Key, Meilisearch Cloud 14-day trial, async task model with taskUid, implicit index creation, primary-key auto-detection from id, hybrid/semantic search and the /chats RAG endpoint.
• Kinsta, "Harness the Power of Meilisearch for Your Web App" — Node.js integration arc, JavaScript client constructor, typo tolerance out of the box, ranking rules, RESTful API, self-host-or-Cloud framing.
• dev.to, 0012303 Meilisearch series ("Has a Free Search Engine", "Has a Free API You Should Know About", "Sets Up in 30 Seconds") — binary install line, getmeili/meilisearch Docker image, REST add/search endpoints, typo-tolerance defaults (oneTypo: 4, twoTypos: 8), filterable-attributes requirement, /multi-search, react-instantsearch integration, Cloud free-tier figures.
• Official Meilisearch documentation, "Using Meilisearch with Docker" (updated 2026-07-03) — -e environment-variable configuration, CLI arguments requiring an explicit binary, /meili_data working directory, volume persistence, dump export/import, snapshot scheduling.
• Scaleway documentation, "Deploying Meilisearch on a Scaleway Instance" — openssl rand -base64 16 master-key generation, Bearer-auth curl against /version.
• sarthakmishra.com, "Meilisearch is the Best Search You'll Never Need" — 16-byte master-key minimum, openssl rand -hex 16, volume-mount persistence requirement, MEILI_NO_ANALYTICS=true.
• StudyRaid, "Understand installing Meilisearch server" — binary CLI options --db-path, --http-addr, --master-key; env-var client configuration pattern.

Frequently asked questions

Do I need to create an index before adding documents?

No. Meilisearch creates the index implicitly when the first documents arrive — there is no create-index API call in the beginner arc, and if your JSON has an id field it becomes the primary key automatically. Name the index in your addDocuments call and move on.

What is the difference between the master key and an API key?

The master key is the root credential: it can add documents, change settings, create scoped keys, and delete indexes. Scoped API keys are derived from it with limited permissions — typically search-only — and those are what your frontend and your teammates get. The master key lives in server-side environment variables and never appears in client code, screenshots, or shared snippets.

Why does my search return nothing right after I add documents?

Because indexing is asynchronous. addDocuments returns a task, not a result; your documents are searchable only after that task's status becomes succeeded. Poll the task with its taskUid before your first search — for small datasets this takes a fraction of a second.

Is Meilisearch really free?

The self-hosted engine is open source (MIT) with no feature limits — you can index and search as much as your server handles. The managed Meilisearch Cloud is a paid product with a trial (LogRocket's current guide cites a 14-day free trial); community guides also cite a Cloud free tier of 100K documents and 10K searches per month, but check the current Cloud pricing page before relying on those figures.

Should I use Meilisearch or Typesense?

Both are self-hosted, typo-tolerant, instant-search engines with a friendly API, and both beat Elasticsearch on setup effort. Meilisearch currently has the larger guide ecosystem and the newer AI-retrieval features (hybrid/semantic search, the /chats RAG endpoint); Typesense is the closest alternative if you prefer its API or its specific relevance model. Either is a defensible choice — pick one and build.