docker.recipes

Typesense + HA Cluster

intermediate

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

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

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

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

Usage Notes

  1. 1API at http://localhost:8108
  2. 23-node HA cluster
  3. 3Raft consensus
  4. 4Sub-millisecond latency
  5. 5Typo 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...
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 Recipes

Ad Space