Typesense + HA Cluster

intermediate

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

[i]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.

[*]Key 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

[#]Common Use Cases

[1]E-commerce product search with instant autocomplete and faceted filtering
[2]SaaS application search requiring 99.9% uptime and fast response times
[3]Content management systems with large document repositories
[4]Real estate platforms combining text search with geographical filtering
[5]Job boards requiring complex filtering across multiple job attributes
[6]Knowledge base search for customer support and documentation sites
[7]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

[!]

WARNING: For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

[$]docker-compose.yml

[docker-compose.yml]

1services: 
2  typesense-1: 
3    image: typesense/typesense:latest
4    environment: 
5      - TYPESENSE_API_KEY=${API_KEY}
6      - TYPESENSE_DATA_DIR=/data
7      - TYPESENSE_NODES=typesense-1:8108:8107,typesense-2:8108:8107,typesense-3:8108:8107
8    volumes: 
9      - typesense-1-data:/data
10    ports: 
11      - "8108:8108"
12    networks: 
13      - typesense-network
14    restart: unless-stopped
15
16  typesense-2: 
17    image: typesense/typesense:latest
18    environment: 
19      - TYPESENSE_API_KEY=${API_KEY}
20      - TYPESENSE_DATA_DIR=/data
21      - TYPESENSE_NODES=typesense-1:8108:8107,typesense-2:8108:8107,typesense-3:8108:8107
22    volumes: 
23      - typesense-2-data:/data
24    networks: 
25      - typesense-network
26    restart: unless-stopped
27
28  typesense-3: 
29    image: typesense/typesense:latest
30    environment: 
31      - TYPESENSE_API_KEY=${API_KEY}
32      - TYPESENSE_DATA_DIR=/data
33      - TYPESENSE_NODES=typesense-1:8108:8107,typesense-2:8108:8107,typesense-3:8108:8107
34    volumes: 
35      - typesense-3-data:/data
36    networks: 
37      - typesense-network
38    restart: unless-stopped
39
40volumes: 
41  typesense-1-data: 
42  typesense-2-data: 
43  typesense-3-data: 
44
45networks: 
46  typesense-network: 
47    driver: bridge

[$].env Template

[.env]

1# Typesense Cluster
2API_KEY=your-api-key-here
3
4# 3-node cluster for high availability
5# Raft consensus for leader election

[i]Usage Notes

[1]API at http://localhost:8108
[2]3-node HA cluster
[3]Raft consensus
[4]Sub-millisecond latency
[5]Typo tolerance built-in

Individual Services(3 services)

Copy individual services to mix and match with your existing compose files.

typesense-1

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

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

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

[>]Quick Start

[terminal]

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  typesense-1:
5    image: typesense/typesense:latest
6    environment:
7      - TYPESENSE_API_KEY=${API_KEY}
8      - TYPESENSE_DATA_DIR=/data
9      - TYPESENSE_NODES=typesense-1:8108:8107,typesense-2:8108:8107,typesense-3:8108:8107
10    volumes:
11      - typesense-1-data:/data
12    ports:
13      - "8108:8108"
14    networks:
15      - typesense-network
16    restart: unless-stopped
17
18  typesense-2:
19    image: typesense/typesense:latest
20    environment:
21      - TYPESENSE_API_KEY=${API_KEY}
22      - TYPESENSE_DATA_DIR=/data
23      - TYPESENSE_NODES=typesense-1:8108:8107,typesense-2:8108:8107,typesense-3:8108:8107
24    volumes:
25      - typesense-2-data:/data
26    networks:
27      - typesense-network
28    restart: unless-stopped
29
30  typesense-3:
31    image: typesense/typesense:latest
32    environment:
33      - TYPESENSE_API_KEY=${API_KEY}
34      - TYPESENSE_DATA_DIR=/data
35      - TYPESENSE_NODES=typesense-1:8108:8107,typesense-2:8108:8107,typesense-3:8108:8107
36    volumes:
37      - typesense-3-data:/data
38    networks:
39      - typesense-network
40    restart: unless-stopped
41
42volumes:
43  typesense-1-data:
44  typesense-2-data:
45  typesense-3-data:
46
47networks:
48  typesense-network:
49    driver: bridge
50EOF
51
52# 2. Create the .env file
53cat > .env << 'EOF'
54# Typesense Cluster
55API_KEY=your-api-key-here
56
57# 3-node cluster for high availability
58# Raft consensus for leader election
59EOF
60
61# 3. Start the services
62docker compose up -d
63
64# 4. View logs
65docker compose logs -f

[>]One-Liner

Run this command to download and set up the recipe in one step:

[terminal]

1curl -fsSL https://docker.recipes/api/recipes/typesense-cluster/run | bash

[?]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

Community Notes

Loading notes...

## Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

## Components

typesense-1typesense-2typesense-3

## Tags

#typesense#search#full-text#clustering#high-availability

## Category

Database Stacks

## Related

Shortcuts: C CopyF FavoriteD Download