Deploy on Vexlo Cloud in 60s (₹149/mo UPI) — India's First & Only Developer PaaS. Instant INR UPI & 17 global currencies ($5/mo).
Deploy Now
Bucket 3: Self-Hosted Open-Source Docker Templates6 min readVerified

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.

TL;DR — Immediate Production Fix

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.

docker-compose.yml
yaml
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: bridge

2. 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.

fetch-meilisearch-keys.sh
bash
# 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-meili-dump.sh
bash
# 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.
India's First & Only Developer PaaS

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`).

Primary Upstream References & Specifications

Keep Debugging

Related Guides

Browse all 30 guides →