Deploying Meilisearch in Production with Docker Compose, MEILI_MASTER_KEY & NVMe Volumes
Production docker-compose.yml for self-hosting Meilisearch v1.11+. Fix 'missing master key' startup errors, generate scoped Search vs Admin API keys, and tune MEILI_MAX_INDEXING_MEMORY.
When you set `MEILI_ENV=production` on the `getmeili/meilisearch` Docker image, Meilisearch disables its public web preview UI and enforces a hard startup check requiring `MEILI_MASTER_KEY` to be set to a cryptographically random string of at least 16 bytes. If `MEILI_MASTER_KEY` is missing or shorter than 16 characters, the container immediately exits with an error. Furthermore, you must never use `MEILI_MASTER_KEY` directly in your frontend or backend search queries—instead, call `GET /keys` once using the Master Key to retrieve the default scoped `Default Search API Key` and `Default Admin API Key`, and mount `/meili_data` to a persistent NVMe volume.
Verified Root Causes in Production Environments
- Missing or Short MEILI_MASTER_KEY in Production Mode: Setting `MEILI_ENV=production` without a 16+ byte `MEILI_MASTER_KEY` halts the Meilisearch binary at boot for security.
- Unbounded Indexing RAM Usage on Small VPS Nodes: By default, Meilisearch can allocate up to two-thirds of total host system memory during heavy batch document indexing unless `MEILI_MAX_INDEXING_MEMORY` is set.
- Breaking Upgrades Across Minor Versions Without Dumps: Upgrading the Docker image tag (e.g., `v1.10` to `v1.11`) without using `MEILI_EXPERIMENTAL_DUMPLESS_UPGRADE=true` or importing a `.dump` fails because LMDB binary index formats are version-specific.
1. Production Meilisearch docker-compose.yml With Memory & Thread Caps
Never use the mutable `getmeili/meilisearch:latest` tag in a production `docker-compose.yml`. Because Meilisearch's underlying LMDB key-value store ties index files inside `/meili_data/data.ms` to a specific minor release, an unintended `docker compose pull` across minor versions can prevent the container from starting unless dumpless upgrades are enabled.
Pin your image to a specific minor version (such as `getmeili/meilisearch:v1.11`), provide a 32-byte hex `MEILI_MASTER_KEY`, and cap `MEILI_MAX_INDEXING_MEMORY` so large bulk indexing jobs never trigger the Linux OOM killer on sibling containers.
services:
meilisearch:
image: getmeili/meilisearch:v1.11
container_name: vexlo-meilisearch
restart: unless-stopped
environment:
MEILI_ENV: production
# Generate via: openssl rand -hex 32 (MUST be >= 16 bytes in production)
MEILI_MASTER_KEY: ${MEILI_MASTER_KEY}
MEILI_NO_ANALYTICS: "true"
MEILI_HTTP_ADDR: "0.0.0.0:7700"
# Cap indexing RAM and CPU threads so multi-container VPS hosts stay responsive
MEILI_MAX_INDEXING_MEMORY: "1024MiB"
MEILI_MAX_INDEXING_THREADS: "2"
MEILI_EXPERIMENTAL_DUMPLESS_UPGRADE: "true"
ports:
- "127.0.0.1:7700:7700"
volumes:
- meili_data:/meili_data
networks:
- backend
healthcheck:
test: ["CMD", "curl", "-f", "http://127.0.0.1:7700/health"]
interval: 15s
timeout: 5s
retries: 3
volumes:
meili_data:
networks:
backend:
driver: bridge2. Retrieving Scoped Search & Admin API Keys Using Your Master Key
As highlighted in Meilisearch's Basic Security documentation, the `MEILI_MASTER_KEY` has unrestricted root privileges and should only be used to manage API keys via the `/keys` endpoint. On first boot, Meilisearch automatically generates two permanent API keys: a `Default Admin API Key` (for server-side indexing and settings updates) and a read-only `Default Search API Key` (safe for client-side search queries).
Run the following `curl` command against your running container to inspect both pre-generated keys, or create a tenant-scoped key with an expiration date.
# 1. Generate a 32-byte Master Key for your .env file
echo "MEILI_MASTER_KEY=$(openssl rand -hex 32)"
# 2. Verify Meilisearch container health
curl -s http://127.0.0.1:7700/health
# Output: {"status":"available"}
# 3. Fetch the auto-generated 'Default Search API Key' and 'Default Admin API Key'
curl -s -X GET 'http://127.0.0.1:7700/keys' \
-H "Authorization: Bearer ${MEILI_MASTER_KEY}" | jq '.results[] | {name, key, actions, indexes}'3. Creating Portable .dump Snapshots Before Version Upgrades
Even with `MEILI_EXPERIMENTAL_DUMPLESS_UPGRADE=true` available in newer releases, creating a compressed `.dump` file via `POST /dumps` before upgrading your Docker image guarantees a 100% portable backup of all indexes, settings, synonyms, and stop-words inside `/meili_data/dumps/`.
For multi-tenant SaaS applications hosted on Vexlo Cloud, use Meilisearch's Tenant Tokens (generated server-side via the official meilisearch Node.js SDK without making a network call) to enforce row-level security filters per customer organization. Tenant tokens embed signed search rules (such as filter: ['org_id = 42']) directly inside a JWT signed by your Default Search API Key.
# Trigger an asynchronous portable dump into /meili_data/dumps/
TASK=$(curl -s -X POST 'http://127.0.0.1:7700/dumps' \
-H "Authorization: Bearer ${MEILI_MASTER_KEY}")
echo "Started Dump Task: $TASK"
# Check dump completion status
TASK_UID=$(echo "$TASK" | jq -r '.taskUid')
curl -s "http://127.0.0.1:7700/tasks/${TASK_UID}" \
-H "Authorization: Bearer ${MEILI_MASTER_KEY}" | jq .Pre-Deployment Verification Checklist
- Pin `getmeili/meilisearch` to an explicit minor version tag (e.g., `v1.11`) instead of `:latest`.
- Set `MEILI_ENV=production` and inject a 32-byte random `MEILI_MASTER_KEY`.
- Mount `/meili_data` to a persistent Docker volume so `/meili_data/data.ms` and `/meili_data/dumps` survive container restarts.
- Cap `MEILI_MAX_INDEXING_MEMORY` to 50% of your container's RAM limit to prevent OOM kills during batch indexing.
Deploy on Vexlo Cloud in 60s (₹149/mo UPI)
Automated Docker & Nixpacks builds, managed PostgreSQL/Redis, and AI Deployment Doctor. Instant INR UPI for India or USD/EUR/GBP across 17 global currencies.
Frequently Asked Questions
Why does my Meilisearch Docker container exit immediately when I set MEILI_ENV=production?
In production mode (`MEILI_ENV=production`), Meilisearch refuses to boot unless `MEILI_MASTER_KEY` is provided and is at least 16 bytes long. Generate a key with `openssl rand -hex 32` and add it to your environment variables.
Why did the Meilisearch web dashboard disappear on port 7700 in production?
Meilisearch intentionally disables the built-in browser search preview dashboard when `MEILI_ENV=production` is set so unauthenticated visitors cannot browse your indexes. Use `GET /health` to test availability or query `/indexes` with an `Authorization: Bearer <API_KEY>` header.
How do I fix Meilisearch 'database version mismatch' after pulling a new Docker image?
Revert the Docker image tag in `docker-compose.yml` to the exact version indicated in the error message, export a dump via `POST /dumps`, upgrade the image tag, and pass `--import-dump /meili_data/dumps/<file>.dump` (or enable `MEILI_EXPERIMENTAL_DUMPLESS_UPGRADE=true`).