How to Self-Host Meilisearch with Docker Compose and Caddy for Lightning-Fast Full-Text Search

Delivering instant, typo-tolerant search across internal documentation, product catalogs, customer records, or self-hosted applications has historically forced infrastructure engineers into an uncomfortable trade-off. Running enterprise search engines like Elasticsearch or OpenSearch requires massive Java Virtual Machine (JVM) heap allocations, gigabytes of baseline RAM, complex cluster topologies, and intricate index mappings. For startups, developer platforms, and homelab environments, this operational overhead is completely disproportionate to the actual workload. Conversely, running raw SQL LIKE '%query%' statements or basic PostgreSQL full-text search quickly bottlenecks CPU threads and fails to provide instantaneous, human-friendly fuzzy matching.

Meilisearch resolves this dilemma by delivering an ultra-fast, lightweight, open-source search engine engineered in Rust. Capable of returning sub-50-millisecond responses right out of the box, Meilisearch provides out-of-the-box typo tolerance, customizable ranking rules, highlighted snippets, and faceted filtering without requiring deep search engine theory. In this comprehensive guide, you will deploy a production-grade Meilisearch instance using Docker Compose, front it with Caddy for automatic Let’s Encrypt TLS termination and security headers, generate scoped tenant and search API keys, automate snapshots and dumps, and configure production-grade index tuning.

Meilisearch Architecture & Core Engine Mechanics

Unlike traditional search engines built on Apache Lucene, Meilisearch utilizes an embedded key-value storage engine based on Lightning Memory-Mapped Database (LMDB). This architectural choice yields profound operational advantages:

• Zero JVM Overhead: Written in pure Rust, Meilisearch compiles to a lean static binary with minimal memory footprint (often starting at under 150 MB of RAM).
• Memory-Mapped Files (mmap): LMDB maps database files directly into virtual memory. The Linux kernel manages page caching automatically, ensuring read operations hit RAM directly without duplicate application buffers.
• Asynchronous Task Queue: Document indexing, deletion, and settings updates execute sequentially in background worker queues, ensuring search query latency remains completely unaffected during heavy data ingestion.
• Hierarchical Security Hierarchy: Access control operates through a three-tiered key hierarchy: the Master Key, Admin API Keys, and Scoped Public Search Keys.

+-----------------------------------------------------------------------+
|                         APPLICATION CLIENTS                           |
|       Web Frontend (Instant Search UI)  /  Backend Ingestion API       |
+-----------------------------------------------------------------------+
                                    |
                    HTTPS (TLS 1.3) / JSON Payloads
                                    v
+-----------------------------------------------------------------------+
|                    EDGE REVERSE PROXY (Caddy)                         |
|      - Automatic Let's Encrypt TLS                                    |
|      - HSTS, CORS Headers & Rate Limiting                             |
+-----------------------------------------------------------------------+
                                    |
                           Internal Bridge Network
                                    v
+-----------------------------------------------------------------------+
|                      MEILISEARCH CONTAINER                            |
|                    getmeili/meilisearch:v1.10                         |
|   +---------------------------------------------------------------+   |
|   | HTTP REST API Server (Port 7700)                              |   |
|   | - Search Endpoints: /indexes/{uid}/search                     |   |
|   | - Task Execution Queue: /tasks                                |   |
|   | - Key & Tenant Management Engine                              |   |
|   +---------------------------------------------------------------+   |
|                                   |                                   |
|   +---------------------------------------------------------------+   |
|   | LMDB Embedded Storage Engine (Rust)                           |   |
|   | - Inverted Indexes & Roaring Bitmaps                          |   |
|   | - Host Persistent Volume: ./meili_data                        |   |
|   | - Automated Dumps & Snapshots: ./meili_dumps                  |   |
|   +---------------------------------------------------------------+   |
+-----------------------------------------------------------------------+

System Prerequisites & Host Preparation

Verify that your host system satisfies the following baseline requirements before initiating deployment:

• A dedicated Linux host (Ubuntu 24.04 LTS, Debian 12, or AlmaLinux 9) with at least 2 CPU cores and 4 GB of RAM (8 GB recommended for datasets exceeding 1,000,000 documents).
• Docker Engine 26+ and Docker Compose v2 installed on the host.
• A public Fully Qualified Domain Name (FQDN) such as search.yourdomain.com pointed to your server’s public IP address via an A/AAAA DNS record.
• Inbound TCP ports 80 and 443 accessible for automatic Let’s Encrypt ACME challenge negotiation.

Create the directory structure for your Meilisearch stack and enforce strict permissions:

sudo mkdir -p /opt/meilisearch/{meili_data,meili_dumps,meili_snapshots,caddy_data,caddy_config}
cd /opt/meilisearch
sudo chown -R 1000:1000 /opt/meilisearch/meili_data /opt/meilisearch/meili_dumps /opt/meilisearch/meili_snapshots

Generating the Master Key & Environment Configuration (.env)

Meilisearch requires a Master Key with at least 16 bytes of entropy to secure administrative endpoints and generate child API keys. In production, never use predictable phrases. Generate a cryptographically secure 32-byte hex token using OpenSSL:

MEILI_MASTER_KEY=$(openssl rand -hex 32)

cat << EOF > /opt/meilisearch/.env
# Meilisearch Server Configuration
MEILI_ENV=production
MEILI_MASTER_KEY=${MEILI_MASTER_KEY}
MEILI_NO_ANALYTICS=true
MEILI_MAX_INDEXING_MEMORY=2GiB
MEILI_MAX_INDEXING_THREADS=2

# Domain Configuration
DOMAIN_NAME=search.yourdomain.com
EOF

chmod 600 /opt/meilisearch/.env

Security Warning: The MEILI_MASTER_KEY is the root secret of your search engine. If compromised, attackers can read, modify, and purge all indexes. Keep this key stored securely and never expose it to client-side code.

Production Docker Compose Configuration

Create the /opt/meilisearch/docker-compose.yml file. This configuration isolates Meilisearch on an internal network and mounts persistent storage volumes alongside Caddy for automatic SSL termination:

services:
  meilisearch:
    image: getmeili/meilisearch:v1.10
    container_name: meilisearch-core
    restart: unless-stopped
    env_file:
      - .env
    volumes:
      - ./meili_data:/meili_data
      - ./meili_dumps:/dumps
      - ./meili_snapshots:/snapshots
    networks:
      - meili-network
    healthcheck:
      test: ["CMD", "meilisearch", "--version"]
      interval: 15s
      timeout: 5s
      retries: 3
    security_opt:
      - no-new-privileges:true

  caddy:
    image: caddy:2.8-alpine
    container_name: meilisearch-caddy
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    environment:
      - DOMAIN_NAME=${DOMAIN_NAME}
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - ./caddy_data:/data
      - ./caddy_config:/config
    networks:
      - meili-network
    depends_on:
      - meilisearch
    security_opt:
      - no-new-privileges:true

networks:
  meili-network:
    name: meilisearch-internal
    driver: bridge

Configuring Caddy with Security & CORS Headers (Caddyfile)

Create the /opt/meilisearch/Caddyfile. Frontend web clients require Cross-Origin Resource Sharing (CORS) headers to perform asynchronous browser searches. We configure Caddy to terminate TLS, apply compression, handle CORS headers, and reverse-proxy requests to Meilisearch on port 7700:

{$DOMAIN_NAME} {
    encode gzip zstd

    # Strict Transport Security & Defense in Depth
    header {
        Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
        X-Content-Type-Options "nosniff"
        X-Frame-Options "DENY"
        Referrer-Policy "strict-origin-when-cross-origin"
        
        # CORS Headers for Frontend Search Integration
        Access-Control-Allow-Origin "*"
        Access-Control-Allow-Methods "GET, POST, OPTIONS"
        Access-Control-Allow-Headers "Authorization, Content-Type, X-Meilisearch-Client"
    }

    # Respond immediately to preflight OPTIONS requests
    @options method OPTIONS
    handle @options {
        respond "" 204
    }

    # Forward traffic to Meilisearch engine
    reverse_proxy meilisearch:7700 {
        header_up Host {host}
        header_up X-Real-IP {remote_host}
        header_up X-Forwarded-For {remote_host}
        header_up X-Forwarded-Proto {scheme}
    }
}

Deploying the Stack & Inspecting Key Provisioning

Launch the containers in detached mode using Docker Compose:

docker compose up -d
docker compose ps
docker compose logs -f meilisearch

During the initial bootstrap, Meilisearch detects the master key, initializes the LMDB environment, and automatically provisions two default cryptographic keys: a Default Search API Key and a Default Admin API Key. Retrieve these keys using cURL and your master key:

source /opt/meilisearch/.env

curl -s -X GET "https://${DOMAIN_NAME}/keys" \
  -H "Authorization: Bearer ${MEILI_MASTER_KEY}" | jq .

The response returns two key objects. Note down the key string associated with the description Default Search API Key. This key has read-only access restricted solely to /indexes/*/search, making it completely safe to embed into client-side JavaScript or React applications.

Hands-On: Ingesting Data & Running Typo-Tolerant Queries

With Meilisearch running, let us verify full-text indexing, ranking rules, and fuzzy search capabilities using practical cURL examples.

1. Create an Index and Ingest Documents

Create a test index named articles and upload sample JSON documents:

curl -X POST "https://${DOMAIN_NAME}/indexes/articles/documents" \
  -H "Authorization: Bearer ${MEILI_MASTER_KEY}" \
  -H "Content-Type: application/json" \
  --data-binary '[
    {
      "id": 1,
      "title": "Deploying Ollama on K3s with GPU Acceleration",
      "category": "Kubernetes",
      "tags": ["k3s", "nvidia", "ai"],
      "published": true
    },
    {
      "id": 2,
      "title": "Hardening Docker with CrowdSec and Caddy Reverse Proxy",
      "category": "Security",
      "tags": ["docker", "caddy", "crowdsec"],
      "published": true
    },
    {
      "id": 3,
      "title": "Automating ZFS Snapshots and Remote Replication",
      "category": "Storage",
      "tags": ["zfs", "sanoid", "backup"],
      "published": true
    }
  ]'

Meilisearch returns a task ID (e.g. {"taskUid": 0, "status": "enqueued"}). Track task completion:

curl -s -X GET "https://${DOMAIN_NAME}/tasks/0" \
  -H "Authorization: Bearer ${MEILI_MASTER_KEY}" | jq .

2. Configure Filterable and Searchable Attributes

To enable faceted filtering (e.g. filtering by category or tags), declare filterable attributes on the index:

curl -X PUT "https://${DOMAIN_NAME}/indexes/articles/settings/filterable-attributes" \
  -H "Authorization: Bearer ${MEILI_MASTER_KEY}" \
  -H "Content-Type: application/json" \
  --data '["category", "tags", "published"]'

3. Perform a Typo-Tolerant Search Query

Now, test Meilisearch’s typo-tolerant fuzzy matching. Search for "krowdsek" (intentionally misspelled) using the restricted Search API Key:

SEARCH_KEY="YOUR_DEFAULT_SEARCH_KEY_HERE"

curl -s -X POST "https://${DOMAIN_NAME}/indexes/articles/search" \
  -H "Authorization: Bearer ${SEARCH_KEY}" \
  -H "Content-Type: application/json" \
  --data '{
    "q": "krowdsek",
    "filter": "published = true",
    "attributesToHighlight": ["title"],
    "highlightPreTag": "<mark>",
    "highlightPostTag": "</mark>"
  }' | jq .

Even with substantial phonetic misspellings, Meilisearch accurately matches document ID 2 (CrowdSec) in under 5 milliseconds, returning highlighted HTML snippets ready for instant frontend rendering.

Automated Backups: Dissecting Dumps vs. Snapshots

Understanding the distinction between Meilisearch Snapshots and Dumps is essential for effective disaster recovery:

• Snapshots: Raw binary exact copies of the LMDB database. Extremely fast to generate and recover from, but version-dependent (cannot be migrated across major Meilisearch version updates).
• Dumps: Raw metadata and JSON document exports. Slower to generate and import, but fully portable across different operating systems, CPU architectures, and major Meilisearch versions.

Create an automated backup script that generates a portable dump nightly and purges backups older than 14 days:

cat << 'EOF' | sudo tee /usr/local/bin/backup-meilisearch.sh
#!/usr/bin/env bash
set -euo pipefail

source /opt/meilisearch/.env
BACKUP_DIR="/opt/meilisearch/meili_dumps"

echo "[INFO] Triggering Meilisearch database dump..."
RESPONSE=$(curl -s -X POST "http://127.0.0.1:7700/dumps" \
  -H "Authorization: Bearer ${MEILI_MASTER_KEY}")

TASK_UID=$(echo "${RESPONSE}" | jq -r '.taskUid')
echo "[INFO] Dump triggered with Task UID: ${TASK_UID}"

# Retain dumps for 14 days
find "${BACKUP_DIR}" -type f -name "*.dump" -mtime +14 -delete
echo "[SUCCESS] Meilisearch backup routine completed."
EOF

sudo chmod +x /usr/local/bin/backup-meilisearch.sh

Install the backup script in system cron to run every morning at 03:30:

(sudo crontab -l 2>/dev/null; echo "30 3 * * * /usr/local/bin/backup-meilisearch.sh >> /var/log/meili-backup.log 2>&1") | sudo crontab -

Production Hardening & Operational Security Best Practices

To operate Meilisearch reliably in mission-critical environments, implement these security measures:

• Generate Tenant Tokens for Multi-Tenant Isolation: If hosting SaaS applications where multiple organizations share one search cluster, use Meilisearch’s cryptographic Tenant Tokens. Generated via HMAC-SHA256, tenant tokens inject search filter rules directly into the signed JWT token, making data leakage between customers mathematically impossible.
• Constrain Indexing Resources: Large batch updates can exhaust server memory. The environment variables MEILI_MAX_INDEXING_MEMORY=2GiB and MEILI_MAX_INDEXING_THREADS=2 prevent indexing tasks from starving host processes.
• Restrict Administrative Endpoints: Only the search endpoint (/indexes/{uid}/search) should be reachable by public users. If your backend applications communicate internally via Docker networks, remove port 7700 bindings from the public host and restrict management operations to private subnets.
• Implement Zero-Trust Reverse Proxying: For internal admin dashboards, place the instance behind Cloudflare Tunnels or a Tailscale mesh network.

Troubleshooting Common Deployment Issues

Below are three frequently encountered issues when self-hosting Meilisearch, along with their root causes and resolutions:

1. Startup Failure: “Master key must be at least 16 bytes”

Symptom: The meilisearch-core container terminates immediately, logging Error: The provided master key is too short. It must be at least 16 bytes.

Root Cause: The MEILI_MASTER_KEY environment variable in .env contains fewer than 16 characters or was passed as an empty string due to variable interpolation failure.

Resolution: Re-generate a high-entropy 32-byte hex key using openssl rand -hex 32, verify the value in .env, and restart the container stack.

2. Indexing Stalls with “MDB_MAP_FULL: Environment mapsize limit reached”

Symptom: Indexing tasks enter the failed state with LMDB storage exceptions indicating the map size limit has been reached.

Root Cause: The total size of indexed documents and inverted indexes exceeds the virtual memory mapping allocated by LMDB (defaulting to 100 GB on 64-bit systems, but constrained on 32-bit or containerized environments with strict cgroup memory limits).

Resolution: Add MEILI_MAX_INDEXING_MEMORY to your .env file, ensure the host volume has sufficient physical SSD space, and prune obsolete historical documents or compact the database via dump export and re-import.

3. Browser Search Queries Blocked by CORS Errors

Symptom: Web applications fail to execute search requests, throwing Access to fetch at 'https://search.domain.com' has been blocked by CORS policy in the browser developer console.

Root Cause: The reverse proxy failed to return the required HTTP access control headers for preflight HTTP OPTIONS requests.

Resolution: Ensure your Caddyfile includes the @options method OPTIONS handler returning HTTP 204 No Content alongside the Access-Control-Allow-Origin "*" header directive shown in this guide.

Summary & Key Takeaways

Deploying Meilisearch with Docker Compose and Caddy provides your infrastructure with an enterprise-caliber, sub-50ms full-text search engine without the memory consumption or operational complexity of Elasticsearch. With native typo tolerance, LMDB memory mapping, automated Let’s Encrypt TLS encryption, and fine-grained API key hierarchies, you can deliver an instant search experience across modern web applications, homelabs, and internal platforms while retaining complete data privacy and sovereignty.