# Typesense Search Cluster

> High-performance search engine with typo tolerance, geo-search, and multi-node clustering.

- Category: Database Stacks
- Difficulty: advanced
- Components: typesense, prometheus, grafana, nginx
- Tags: search, typesense, full-text, geo-search, cluster
- Source: https://docker.recipes/databases/typesense-search-stack

## Overview

Typesense is an open-source, typo-tolerant search engine built for instant search experiences with sub-millisecond response times. Originally created as a developer-friendly alternative to Elasticsearch and commercial solutions like Algolia, Typesense excels at full-text search, faceted filtering, and geo-spatial queries while maintaining simplicity in configuration and operation. Unlike traditional search engines that require complex mapping and tuning, Typesense automatically handles typo tolerance and relevance scoring out of the box.

This clustered deployment combines a three-node Typesense cluster with comprehensive monitoring through Prometheus and Grafana, fronted by NGINX for load balancing and high availability. The multi-node setup ensures zero-downtime operations during maintenance, automatic failover capabilities, and horizontal scaling for high-traffic applications. Prometheus scrapes metrics from all Typesense nodes to track search performance, query latency, and cluster health, while Grafana provides visual dashboards for monitoring search analytics and system performance.

E-commerce platforms, content management systems, and data-driven applications requiring instant search capabilities will benefit most from this stack. Organizations transitioning from Elasticsearch seeking simpler operations, or those evaluating Algolia alternatives for cost optimization, will find this configuration particularly valuable. The clustering approach makes it suitable for production environments serving thousands of concurrent search requests while maintaining sub-50ms query response times.

## Features

- Three-node Typesense cluster with automatic leader election and data replication
- Built-in typo tolerance with configurable fuzzy matching algorithms
- Geo-spatial search capabilities for location-based filtering and sorting
- Vector search support for semantic similarity and recommendation engines
- Real-time search analytics and performance metrics via Prometheus integration
- Dynamic faceting with automatic field detection and filtering options
- NGINX load balancer with health checks and automatic failover routing
- Grafana dashboards for monitoring search query patterns and cluster performance

## Use cases

- E-commerce product catalogs with real-time inventory search and faceted filtering
- Content management systems requiring instant article and document discovery
- SaaS applications needing embedded search functionality with typo tolerance
- Data exploration platforms for large datasets with complex filtering requirements
- Job boards and marketplace platforms with location-based search capabilities
- Documentation sites requiring fast, accurate search across technical content
- Multi-tenant applications where search performance affects user experience

## Prerequisites

- Minimum 4GB RAM available (1GB+ per Typesense node plus monitoring stack)
- Docker Engine 20.10+ with Docker Compose v2 support
- Available ports 3000, 8108, and 9090 for web interfaces
- Understanding of JSON document structure for search data indexing
- Basic knowledge of PromQL for custom Prometheus queries and alerting
- Familiarity with search concepts like facets, filters, and relevance scoring

## docker-compose.yml

```yaml
services:
  typesense-1:
    image: typesense/typesense:latest
    command: --data-dir /data --api-key=${TYPESENSE_API_KEY} --nodes=/etc/typesense/nodes --peering-address=typesense-1
    volumes:
      - ts1_data:/data
      - ./nodes:/etc/typesense/nodes:ro
    networks:
      - typesense-net
    restart: unless-stopped

  typesense-2:
    image: typesense/typesense:latest
    command: --data-dir /data --api-key=${TYPESENSE_API_KEY} --nodes=/etc/typesense/nodes --peering-address=typesense-2
    volumes:
      - ts2_data:/data
      - ./nodes:/etc/typesense/nodes:ro
    networks:
      - typesense-net
    restart: unless-stopped

  typesense-3:
    image: typesense/typesense:latest
    command: --data-dir /data --api-key=${TYPESENSE_API_KEY} --nodes=/etc/typesense/nodes --peering-address=typesense-3
    volumes:
      - ts3_data:/data
      - ./nodes:/etc/typesense/nodes:ro
    networks:
      - typesense-net
    restart: unless-stopped

  nginx:
    image: nginx:alpine
    ports:
      - "8108:8108"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
    depends_on:
      - typesense-1
      - typesense-2
      - typesense-3
    networks:
      - typesense-net
    restart: unless-stopped

  prometheus:
    image: prom/prometheus:latest
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro
      - prometheus_data:/prometheus
    networks:
      - typesense-net
    restart: unless-stopped

  grafana:
    image: grafana/grafana:latest
    ports:
      - "3000:3000"
    environment:
      GF_SECURITY_ADMIN_PASSWORD: ${GRAFANA_PASSWORD}
    volumes:
      - grafana_data:/var/lib/grafana
    networks:
      - typesense-net
    restart: unless-stopped

volumes:
  ts1_data:
  ts2_data:
  ts3_data:
  prometheus_data:
  grafana_data:

networks:
  typesense-net:
    driver: bridge
```

## .env

```bash
# Typesense API Key
TYPESENSE_API_KEY=your_secure_api_key_here

# Grafana
GRAFANA_PASSWORD=secure_grafana_password
```

## Usage notes

- Search API at http://localhost:8108
- 3-node cluster for high availability
- Supports geo-search and vector search
- Import Grafana dashboard for monitoring

## Troubleshooting

- Cluster formation fails with 'peer not found' errors: Verify all nodes can resolve each other's hostnames and check the nodes configuration file contains correct addresses
- Search queries return 'TYPESENSE_API_KEY_INCORRECT' errors: Ensure the TYPESENSE_API_KEY environment variable matches across all cluster nodes and client requests
- High memory usage on Typesense nodes: Reduce the number of indexed fields, implement field-level indexing controls, or increase available memory allocation per container
- NGINX returns 502 Bad Gateway errors: Check Typesense container health status and verify the upstream configuration matches the actual container names and ports
- Prometheus scraping fails with connection refused: Confirm Typesense nodes are exposing metrics on the correct port and Prometheus targets configuration is accurate
- Grafana dashboards show no data: Verify Prometheus data source configuration and ensure metrics retention period covers the query time range

