Codakey
Play
← Back to manticoresearch

How to Deploy & Use manticoresearch

Manticore Search Deployment and Usage Guide

1. Prerequisites

System Requirements:

  • Linux (Ubuntu, Debian, CentOS, RHEL, AlmaLinux, Rocky Linux) or macOS
  • For production: Minimum 2GB RAM recommended (more for large datasets)
  • CPU with multiple cores for optimal parallelization
  • Disk space sufficient for your dataset and indexes

Tools & Clients:

  • Any MySQL client (Manticore uses MySQL wire protocol)
  • Docker (optional, for containerized deployment)
  • For building from source: C++ compiler (g++ 7.0+ or clang++), CMake 3.16+, Git

2. Installation

Quick Install (Recommended)

Using Docker:

docker pull manticoresearch/manticore
docker run -e EXTRA=1 --name manticore -p 9306:9306 -p 9308:9308 -d manticoresearch/manticore

Using Package Managers:

Ubuntu/Debian:

wget https://repo.manticoresearch.com/manticore-repo.noarch.deb
sudo dpkg -i manticore-repo.noarch.deb
sudo apt update
sudo apt install manticore manticore-columnar-lib

CentOS/RHEL/AlmaLinux/Rocky Linux:

sudo yum install https://repo.manticoresearch.com/manticore-repo.noarch.rpm
sudo yum install manticore manticore-columnar-lib

macOS (Homebrew):

brew install manticoresearch/tap/manticoresearch

Windows: Use Docker or WSL2 with Linux installation methods.

Build from Source

# Clone repository
git clone https://github.com/manticoresoftware/manticoresearch.git
cd manticoresearch

# Install build dependencies
# Ubuntu/Debian:
sudo apt install git gcc g++ cmake libssl-dev libexpat-dev libicu-dev libpq-dev

# Build
mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo ..
make -j$(nproc)
sudo make install

3. Configuration

Main Configuration File

The primary configuration file is located at:

  • /etc/manticoresearch/manticore.conf (Linux package install)
  • /usr/local/etc/manticore.conf (source install)

Essential Configuration Sections

Basic server setup:

searchd {
    listen = 9306:mysql  # MySQL protocol
    listen = 9308:http   # HTTP/JSON protocol
    log = /var/log/manticore/searchd.log
    query_log = /var/log/manticore/query.log
    pid_file = /var/run/manticore/searchd.pid
    data_dir = /var/lib/manticore
}

Index definition example:

index test {
    type = rt  # Real-time index
    path = /var/lib/manticore/test
    
    rt_field = title
    rt_field = content
    rt_attr_uint = category_id
    rt_attr_timestamp = created_at
    rt_attr_string = author
}

Environment Variables

When using Docker, key environment variables:

  • EXTRA=1: Enables additional features (columnar library, ICU, etc.)
  • CLICKHOUSE=1: Enables ClickHouse protocol support
  • MALLOC_ARENA_MAX=2: Optimizes memory usage in container environments

4. Build & Run

Running as a Service (Linux)

# Start Manticore Search service
sudo systemctl start manticore

# Enable auto-start on boot
sudo systemctl enable manticore

# Check status
sudo systemctl status manticore

Running Manually

# Start searchd daemon
searchd --config /etc/manticoresearch/manticore.conf

# Or with custom config
searchd --config /path/to/your/manticore.conf

Connecting and Testing

Using MySQL client:

mysql -h0 -P9306

Basic SQL operations:

-- Check server status
SHOW STATUS;

-- Create a real-time index
CREATE TABLE products (title text, price float, category_id integer);

-- Insert data
INSERT INTO products (title, price, category_id) VALUES ('Manticore Search Guide', 0.0, 1);

-- Search
SELECT * FROM products WHERE MATCH('search guide');

Using HTTP/JSON API:

curl -s -X POST http://localhost:9308/search -d '{
  "index": "products",
  "query": { "match": { "*": "search guide" } }
}'

5. Deployment

Production Deployment Options

1. Docker Deployment (Simplest):

# docker-compose.yml
version: '3'
services:
  manticore:
    image: manticoresearch/manticore:latest
    container_name: manticore
    ports:
      - "9306:9306"
      - "9308:9308"
    environment:
      - EXTRA=1
    volumes:
      - ./data:/var/lib/manticore
      - ./manticore.conf:/etc/manticoresearch/manticore.conf
    restart: unless-stopped

2. Kubernetes:

# Example deployment with PersistentVolume
apiVersion: apps/v1
kind: Deployment
metadata:
  name: manticore
spec:
  replicas: 1
  selector:
    matchLabels:
      app: manticore
  template:
    metadata:
      labels:
        app: manticore
    spec:
      containers:
      - name: manticore
        image: manticoresearch/manticore:latest
        env:
        - name: EXTRA
          value: "1"
        ports:
        - containerPort: 9306
        - containerPort: 9308
        volumeMounts:
        - name: manticore-data
          mountPath: /var/lib/manticore
      volumes:
      - name: manticore-data
        persistentVolumeClaim:
          claimName: manticore-pvc

3. Bare Metal/VPS:

  • Use package manager installation
  • Configure systemd service
  • Set up monitoring with SHOW STATUS queries
  • Configure firewall (open ports 9306 and 9308)
  • Set up log rotation for /var/log/manticore/*.log

4. Cloud Platforms:

  • AWS: EC2 instance with EBS volumes for data persistence
  • Google Cloud: Compute Engine with persistent disks
  • Azure: Virtual Machine with managed disks
  • Consider using instance types with good I/O performance for search workloads

Scaling Considerations

  • For read scaling: Set up replication between nodes
  • For write scaling: Implement data sharding across multiple nodes
  • Use load balancer (HAProxy, nginx) for distributing client connections
  • Monitor SHOW STATUS metrics for performance tuning

6. Troubleshooting

Common Issues and Solutions

1. Service won't start:

# Check logs
tail -f /var/log/manticore/searchd.log

# Verify config syntax
indexer --checkconfig --config /etc/manticoresearch/manticore.conf

# Check for port conflicts
sudo netstat -tulpn | grep -E '9306|9308'

2. Can't connect to MySQL interface:

# Verify service is running
sudo systemctl status manticore

# Check if MySQL protocol is enabled in config
grep "listen.*mysql" /etc/manticoresearch/manticore.conf

# Test connection locally
mysql -h127.0.0.1 -P9306

3. High memory usage:

  • Enable columnar storage for large datasets: storage_type = columnar
  • Adjust rt_mem_limit in index configuration
  • For Docker: Set MALLOC_ARENA_MAX=2 environment variable
  • Monitor with SHOW STATUS and look at memory_% metrics

4. Slow queries:

-- Enable query logging temporarily
SET GLOBAL query_log=1;

-- Analyze slow queries from log
tail -f /var/log/manticore/query.log

-- Check query execution plan
EXPLAIN SELECT ... FROM ... WHERE ...

5. Index corruption:

# Check index integrity
indexer --check <index_name> --config /etc/manticoresearch/manticore.conf

# Rebuild corrupted index
indexer --rotate <index_name> --config /etc/manticoresearch/manticore.conf

6. Data ingestion performance issues:

  • Use bulk inserts instead of single document inserts
  • Consider increasing max_packet_size in configuration
  • For large datasets, use columnar storage with Manticore Columnar Library
  • Monitor SHOW STATUS for bulk_% metrics

Getting Help

← Project overviewView alternatives to manticoresearch →