# Typesense + HA Cluster

> Fast, typo-tolerant search engine built in C++.

- Category: Database Stacks
- Difficulty: intermediate
- Components: typesense-1, typesense-2, typesense-3
- Tags: typesense, search, full-text, clustering, high-availability
- Source: https://docker.recipes/databases/typesense-cluster

## Overview

Typesense is a modern, open-source search engine built in C++ that delivers instant search experiences with built-in typo tolerance. Originally created as a developer-friendly alternative to complex solutions like Elasticsearch, Typesense focuses on simplicity without sacrificing performance, offering sub-millisecond search responses and intuitive APIs that make implementation straightforward for developers.

This three-node high availability cluster configuration leverages Typesense's built-in Raft consensus protocol to ensure search service continuity and data consistency across all nodes. The cluster automatically handles leader election, data replication, and failover scenarios, providing enterprise-grade reliability while maintaining Typesense's signature fast response times. Each node can serve read requests independently, distributing query load effectively.

This setup is ideal for production environments requiring zero-downtime search capabilities, such as e-commerce platforms with high traffic volumes, SaaS applications with critical search functionality, or content-heavy websites where search availability directly impacts user experience. The three-node configuration provides the optimal balance between fault tolerance and resource efficiency, surviving single node failures while maintaining quorum.

## Features

- Typo-tolerant search with automatic error correction for misspelled queries
- Sub-millisecond search response times with in-memory indexing
- Raft consensus protocol for automatic leader election and data consistency
- Real-time faceted search and filtering across multiple attributes
- Geo-search capabilities for location-based queries and radius filtering
- Synonym support and result curation for enhanced search relevance
- Vector search functionality for semantic and AI-powered search experiences
- Automatic cluster healing and node recovery without manual intervention

## Use cases

- E-commerce product search with instant autocomplete and faceted filtering
- SaaS application search requiring 99.9% uptime and fast response times
- Content management systems with large document repositories
- Real estate platforms combining text search with geographical filtering
- Job boards requiring complex filtering across multiple job attributes
- Knowledge base search for customer support and documentation sites
- Multi-tenant applications where search downtime affects multiple customers

## Prerequisites

- Minimum 3GB RAM total (1GB per node) for optimal cluster performance
- Docker and Docker Compose 3.8+ with networking support enabled
- Available ports 8108 (API) and 8107 (peer communication) for cluster coordination
- Understanding of API key management and secure credential storage
- Basic knowledge of search indexing concepts and JSON document structures
- Network connectivity between nodes for Raft consensus communication

## docker-compose.yml

```yaml
services:
  typesense-1:
    image: typesense/typesense:latest
    environment:
      - TYPESENSE_API_KEY=${API_KEY}
      - TYPESENSE_DATA_DIR=/data
      - TYPESENSE_NODES=typesense-1:8108:8107,typesense-2:8108:8107,typesense-3:8108:8107
    volumes:
      - typesense-1-data:/data
    ports:
      - "8108:8108"
    networks:
      - typesense-network
    restart: unless-stopped

  typesense-2:
    image: typesense/typesense:latest
    environment:
      - TYPESENSE_API_KEY=${API_KEY}
      - TYPESENSE_DATA_DIR=/data
      - TYPESENSE_NODES=typesense-1:8108:8107,typesense-2:8108:8107,typesense-3:8108:8107
    volumes:
      - typesense-2-data:/data
    networks:
      - typesense-network
    restart: unless-stopped

  typesense-3:
    image: typesense/typesense:latest
    environment:
      - TYPESENSE_API_KEY=${API_KEY}
      - TYPESENSE_DATA_DIR=/data
      - TYPESENSE_NODES=typesense-1:8108:8107,typesense-2:8108:8107,typesense-3:8108:8107
    volumes:
      - typesense-3-data:/data
    networks:
      - typesense-network
    restart: unless-stopped

volumes:
  typesense-1-data:
  typesense-2-data:
  typesense-3-data:

networks:
  typesense-network:
    driver: bridge
```

## .env

```bash
# Typesense Cluster
API_KEY=your-api-key-here

# 3-node cluster for high availability
# Raft consensus for leader election
```

## Usage notes

- API at http://localhost:8108
- 3-node HA cluster
- Raft consensus
- Sub-millisecond latency
- Typo tolerance built-in

## Troubleshooting

- Cluster shows split-brain behavior: Ensure all three nodes have identical TYPESENSE_NODES configuration and can communicate on port 8107
- Node fails to join cluster with 'peer not found' error: Verify Docker network connectivity and that all containers are on the typesense-network
- Search queries return stale data: Check cluster status endpoint to confirm leader election completed and data replication is current
- High memory usage during indexing: Increase Docker container memory limits and consider batch sizing for large document imports
- API returns 503 service unavailable: Verify cluster quorum exists with at least 2 of 3 nodes healthy and check API_KEY environment variable
- Slow query performance in cluster: Monitor which node is handling requests and consider load balancing across healthy nodes

