Skip to main content

Start and Stop Meilisearch

Starting and Stopping Meilisearch

Created: September 22, 2022 7 min read
Table of Contents

Overview

Meilisearch is a fast, open-source search engine written in Rust. Getting it running — and stopping it cleanly — is the first step before you index anything. This guide covers every method: installing from scratch, starting with the right flags, stopping gracefully, running as a systemd service, containerizing with Docker Compose, monitoring health, managing logs, backing up data, upgrading versions, and debugging common startup failures.

Installation Methods

Meilisearch ships as a single binary with no external runtime dependencies. Choose the method that fits your OS and workflow.

Method Command / Steps Ease of Setup Production Ready Best For
Homebrew (macOS) brew install meilisearch Trivial No (dev only) Local development, quick eval
Docker docker run getmeili/meilisearch Easy Yes (with volumes) Containerized stacks, CI/CD
APT (Debian/Ubuntu) curl -fsSL ... | bash Moderate Yes Dedicated Linux servers
Binary download curl -OL + tar -xzf Manual Yes Offline servers, air-gapped
Source compile cargo build --release Hard Yes Custom patches, edge versions

Homebrew

brew update && brew install meilisearch
meilisearch --version

Docker

docker run -d --name meilisearch \
  -p 7700:7700 \
  -v $(pwd)/meili_data:/meili_data \
  getmeili/meilisearch:latest

APT (Debian/Ubuntu)

# Add the Meilisearch repository
curl -fsSL https://get.meilisearch.com | bash
# The script installs the binary to /usr/bin/meilisearch
meilisearch --version

Binary Download (any Linux)

curl -OL https://github.com/meilisearch/meilisearch/releases/latest/download/meilisearch-linux-amd64.tar.gz
tar -xzf meilisearch-linux-amd64.tar.gz
sudo mv meilisearch /usr/local/bin/
meilisearch --version

Starting Meilisearch

The simplest start command uses default settings, but every production deployment should set a master key and bind address explicitly.

Minimal Start

meilisearch --http-addr 0.0.0.0:7700

Start with Master Key and Environment

meilisearch \
  --http-addr 0.0.0.0:7700 \
  --master-key "a0b1c2d3e4f5g6h7i8j9k0l1m2n3o4p5" \
  --env production \
  --dump-dir /var/lib/meilisearch/dumps \
  --snapshot-dir /var/lib/meilisearch/snapshots

Key flags explained:

  • --http-addr: Bind address and port. Default is 127.0.0.1:7700; set to 0.0.0.0:7700 to accept external connections.
  • --master-key: API key that grants full access. Must be at least 16 bytes. Use a secure random string.
  • --env: production disables the web UI and drops certain dev-only endpoints.
  • --dump-dir / --snapshot-dir: Where automatic backups are written.
  • --max-index-size: Limit the size of each index (e.g. 10Gb).
  • --http-payload-size-limit: Maximum request body size (e.g. 100Mb).

Start with Environment Variables

All CLI flags can be set via environment variables, which is the recommended approach for containerized or CI environments.

export MEILI_HTTP_ADDR=0.0.0.0:7700
export MEILI_MASTER_KEY="a0b1c2d3e4f5g6h7i8j9k0l1m2n3o4p5"
export MEILI_ENV=production
export MEILI_DUMP_DIR=/var/lib/meilisearch/dumps
meilisearch

Start in Background with Log Redirection

nohup meilisearch \
  --http-addr 0.0.0.0:7700 \
  --master-key "a0b1c2d3e4f5g6h7i8j9k0l1m2n3o4p5" \
  --env production \
  > /var/log/meilisearch/meilisearch.log 2>&1 &

Stopping Meilisearch Gracefully

Meilisearch handles SIGTERM by flushing pending writes, closing indexes cleanly, and writing a final dump if configured. Always send SIGTERM first — never SIGKILL unless the process is hung.

Stop by PID

pid=$(pgrep -x meilisearch)
if [ -n "$pid" ]; then
    kill -SIGTERM "$pid"
    echo "SIGTERM sent to meilisearch (PID: $pid)"
    # Wait up to 30 seconds for graceful shutdown
    for i in $(seq 1 30); do
        if ! kill -0 "$pid" 2>/dev/null; then
            echo "Meilisearch stopped cleanly"
            break
        fi
        sleep 1
    done
    # Force kill if still running after timeout
    if kill -0 "$pid" 2>/dev/null; then
        echo "Force stopping meilisearch (PID: $pid)"
        kill -SIGKILL "$pid"
    fi
else
    echo "Meilisearch is not running"
fi

Stop Using systemctl

sudo systemctl stop meilisearch
sudo systemctl status meilisearch

Stop a Docker Container

docker stop meilisearch
docker rm meilisearch   # only if you want to remove the container

Verify Meilisearch Has Stopped

curl -s http://localhost:7700/health
# Expected: curl: (7) Failed to connect — means it's down

Running as a systemd Service

A systemd unit file ensures Meilisearch starts on boot, restarts on failure, and logs to journald.

Unit File

Create /etc/systemd/system/meilisearch.service:

[Unit]
Description=Meilisearch Search Engine
After=network.target

[Service]
Type=simple
User=meilisearch
Group=meilisearch
WorkingDirectory=/var/lib/meilisearch
Environment="MEILI_HTTP_ADDR=0.0.0.0:7700"
Environment="MEILI_MASTER_KEY=a0b1c2d3e4f5g6h7i8j9k0l1m2n3o4p5"
Environment="MEILI_ENV=production"
Environment="MEILI_DUMP_DIR=/var/lib/meilisearch/dumps"
Environment="MEILI_SNAPSHOT_DIR=/var/lib/meilisearch/snapshots"
Environment="MEILI_LOG_LEVEL=INFO"
ExecStart=/usr/bin/meilisearch
Restart=on-failure
RestartSec=5
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target

Create the meilisearch User and Directories

sudo useradd -r -s /bin/false -d /var/lib/meilisearch meilisearch
sudo mkdir -p /var/lib/meilisearch/{dumps,snapshots}
sudo chown -R meilisearch:meilisearch /var/lib/meilisearch

Enable and Start

sudo systemctl daemon-reload
sudo systemctl enable meilisearch
sudo systemctl start meilisearch
sudo systemctl status meilisearch

Docker Compose Setup

For containerized deployments, Docker Compose gives you reproducible configuration with volume mounts and environment variables managed in one file.

version: "3.8"

services:
  meilisearch:
    image: getmeili/meilisearch:latest
    container_name: meilisearch
    restart: unless-stopped
    ports:
      - "7700:7700"
    volumes:
      - ./meili_data:/meili_data
    environment:
      - MEILI_HTTP_ADDR=0.0.0.0:7700
      - MEILI_MASTER_KEY=${MEILI_MASTER_KEY:-a0b1c2d3e4f5g6h7i8j9k0l1m2n3o4p5}
      - MEILI_ENV=production
      - MEILI_DUMP_DIR=/meili_data/dumps
      - MEILI_SNAPSHOT_DIR=/meili_data/snapshots
      - MEILI_LOG_LEVEL=INFO

Start with:

export MEILI_MASTER_KEY="your-secure-key"
docker compose up -d
docker compose logs -f

Health Checks

Meilisearch exposes a health endpoint that returns 200 OK when the server is ready.

curl Health Check

curl -s http://localhost:7700/health
# {"status":"available"}

Health Check with Master Key

curl -s http://localhost:7700/health -H "Authorization: Bearer $MEILI_MASTER_KEY"

Scripted Health Check for Monitoring

#!/bin/bash
if curl -sf http://localhost:7700/health > /dev/null 2>&1; then
    echo "Meilisearch is healthy"
    exit 0
else
    echo "Meilisearch is DOWN"
    exit 1
fi

Docker Health Check (in Compose)

healthcheck:
  test: curl -sf http://localhost:7700/health || exit 1
  interval: 30s
  timeout: 10s
  retries: 3
  start_period: 10s

Log Management

Meilisearch writes logs to stdout by default. For long-running instances, redirect to a file or use journald.

Redirect to a Log File

meilisearch > /var/log/meilisearch/meilisearch.log 2>&1

View Logs with Journald (systemd)

sudo journalctl -u meilisearch -f
sudo journalctl -u meilisearch --since "1 hour ago"

Log Rotation with logrotate

Create /etc/logrotate.d/meilisearch:

/var/log/meilisearch/*.log {
    daily
    rotate 7
    compress
    delaycompress
    missingok
    notifempty
    copytruncate
}

Backup and Restore

Meilisearch supports two backup mechanisms: dumps (human-readable, can be imported across versions) and snapshots (binary, faster, version-specific).

Create a Dump (Manual)

curl -s -X POST http://localhost:7700/dumps \
  -H "Authorization: Bearer $MEILI_MASTER_KEY"
# Response: {"uid":"20260426-123456789","status":"processing"}

Dumps are written to the --dump-dir directory as .dump files.

Create a Snapshot (Requires Config)

Enable automatic snapshots by passing --schedule-snapshot and --snapshot-interval-sec on startup, then trigger one manually:

# Snapshots are created automatically based on the interval.
# Find the latest snapshot:
ls -t /var/lib/meilisearch/snapshots/*.snapshot | head -1

Restore from a Dump

meilisearch --import-dump /var/lib/meilisearch/dumps/20260426-123456789.dump

Restore from a Snapshot

meilisearch --import-snapshot /var/lib/meilisearch/snapshots/latest.snapshot

Automated Backup Script

#!/bin/bash
DUMP_DIR="/var/lib/meilisearch/dumps"
BACKUP_DIR="/backups/meilisearch"
mkdir -p "$BACKUP_DIR"
curl -s -X POST http://localhost:7700/dumps \
  -H "Authorization: Bearer $MEILI_MASTER_KEY" > /dev/null
sleep 5
cp "$DUMP_DIR"/latest.dump "$BACKUP_DIR/meilisearch-$(date +%F).dump"
echo "Backup saved to $BACKUP_DIR"

Upgrading Meilisearch

Upgrading between minor versions is straightforward. Patch versions are fully compatible.

Using systemd

sudo systemctl stop meilisearch
# Replace the binary
curl -OL https://github.com/meilisearch/meilisearch/releases/latest/download/meilisearch-linux-amd64.tar.gz
tar -xzf meilisearch-linux-amd64.tar.gz
sudo mv meilisearch /usr/bin/
sudo systemctl start meilisearch

Using Docker

docker compose pull
docker compose up -d

Migration Between Major Versions

Major versions may change the index format. Always:

  1. Take a dump before upgrading.
  2. Read the changelog for breaking changes.
  3. Start the new binary with --import-dump — Meilisearch migrates the dump automatically on first start.
meilisearch --import-dump /backups/pre-upgrade.dump

Common Startup Issues and Troubleshooting

Issue Symptom Fix
Port already in use Address already in use sudo lsof -i :7700 then kill the process or change --http-addr
Master key too short master key length is too short Use a key with at least 16 characters
Permission denied Permission denied writing to dump dir Ensure the meilisearch user owns the directory
Out of memory Killed or OOM in logs Reduce --max-index-size or increase system RAM
Index corruption could not load indexes Restore from the latest dump
Docker volume permissions can't create database: permission denied Set MEILI_DB_PATH inside the container to /meili_data
Snapshot format mismatch snapshot version mismatch Re-import from a dump (snapshots are version-specific)
DNS / network bind bind: cannot assign requested address Use 0.0.0.0 instead of a specific IP, or check network interfaces

Verbose Logging for Debugging

meilisearch --log-level DEBUG

Checking Resource Usage

ps aux | grep meilisearch
top -p $(pgrep -x meilisearch)

Production Configuration Best Practices

  • Always set a master key: Without it, Meilisearch accepts all requests unauthenticated. Use a 32+ byte random string stored in a secret manager or environment file.
  • Run as a dedicated user: Never run Meilisearch as root. Use the meilisearch system user.
  • Bind to a private network: If Meilisearch sits behind a reverse proxy (Nginx, Caddy), bind to 127.0.0.1:7700 so it’s not exposed directly.
  • Enable snapshots: Set --schedule-snapshot with --snapshot-interval-sec 86400 for daily automatic backups.
  • Set --env production: This disables the debug web UI and other development-only features.
  • Configure LimitNOFILE: Meilisearch may hold many open file descriptors. Set LimitNOFILE=65536 in the systemd unit.
  • Monitor health: Integrate the /health endpoint with your monitoring stack (Prometheus, Datadog, etc.).
  • Keep the binary updated: Watch the releases page for security patches and performance improvements.

Resources

Comments

Share this article

Twitter Bluesky Mastodon LinkedIn Facebook Reddit

Scan to read on mobile