Typesense Search Cluster

advanced

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

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.

Key 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

Common Use Cases

1E-commerce product catalogs with real-time inventory search and faceted filtering
2Content management systems requiring instant article and document discovery
3SaaS applications needing embedded search functionality with typo tolerance
4Data exploration platforms for large datasets with complex filtering requirements
5Job boards and marketplace platforms with location-based search capabilities
6Documentation sites requiring fast, accurate search across technical content
7Multi-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

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

docker-compose.yml

1services: 
2  typesense-1: 
3    image: typesense/typesense:latest
4    command: --data-dir /data --api-key=${TYPESENSE_API_KEY} --nodes=/etc/typesense/nodes --peering-address=typesense-1
5    volumes: 
6      - ts1_data:/data
7      - ./nodes:/etc/typesense/nodes:ro
8    networks: 
9      - typesense-net
10    restart: unless-stopped
11
12  typesense-2: 
13    image: typesense/typesense:latest
14    command: --data-dir /data --api-key=${TYPESENSE_API_KEY} --nodes=/etc/typesense/nodes --peering-address=typesense-2
15    volumes: 
16      - ts2_data:/data
17      - ./nodes:/etc/typesense/nodes:ro
18    networks: 
19      - typesense-net
20    restart: unless-stopped
21
22  typesense-3: 
23    image: typesense/typesense:latest
24    command: --data-dir /data --api-key=${TYPESENSE_API_KEY} --nodes=/etc/typesense/nodes --peering-address=typesense-3
25    volumes: 
26      - ts3_data:/data
27      - ./nodes:/etc/typesense/nodes:ro
28    networks: 
29      - typesense-net
30    restart: unless-stopped
31
32  nginx: 
33    image: nginx:alpine
34    ports: 
35      - "8108:8108"
36    volumes: 
37      - ./nginx.conf:/etc/nginx/nginx.conf:ro
38    depends_on: 
39      - typesense-1
40      - typesense-2
41      - typesense-3
42    networks: 
43      - typesense-net
44    restart: unless-stopped
45
46  prometheus: 
47    image: prom/prometheus:latest
48    ports: 
49      - "9090:9090"
50    volumes: 
51      - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro
52      - prometheus_data:/prometheus
53    networks: 
54      - typesense-net
55    restart: unless-stopped
56
57  grafana: 
58    image: grafana/grafana:latest
59    ports: 
60      - "3000:3000"
61    environment: 
62      GF_SECURITY_ADMIN_PASSWORD: ${GRAFANA_PASSWORD}
63    volumes: 
64      - grafana_data:/var/lib/grafana
65    networks: 
66      - typesense-net
67    restart: unless-stopped
68
69volumes: 
70  ts1_data: 
71  ts2_data: 
72  ts3_data: 
73  prometheus_data: 
74  grafana_data: 
75
76networks: 
77  typesense-net: 
78    driver: bridge

.env Template

.env

1# Typesense API Key
2TYPESENSE_API_KEY=your_secure_api_key_here
3
4# Grafana
5GRAFANA_PASSWORD=secure_grafana_password

Usage Notes

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

Individual Services(6 services)

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

typesense-1

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

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

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

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

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

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

Quick Start

terminal

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  typesense-1:
5    image: typesense/typesense:latest
6    command: --data-dir /data --api-key=${TYPESENSE_API_KEY} --nodes=/etc/typesense/nodes --peering-address=typesense-1
7    volumes:
8      - ts1_data:/data
9      - ./nodes:/etc/typesense/nodes:ro
10    networks:
11      - typesense-net
12    restart: unless-stopped
13
14  typesense-2:
15    image: typesense/typesense:latest
16    command: --data-dir /data --api-key=${TYPESENSE_API_KEY} --nodes=/etc/typesense/nodes --peering-address=typesense-2
17    volumes:
18      - ts2_data:/data
19      - ./nodes:/etc/typesense/nodes:ro
20    networks:
21      - typesense-net
22    restart: unless-stopped
23
24  typesense-3:
25    image: typesense/typesense:latest
26    command: --data-dir /data --api-key=${TYPESENSE_API_KEY} --nodes=/etc/typesense/nodes --peering-address=typesense-3
27    volumes:
28      - ts3_data:/data
29      - ./nodes:/etc/typesense/nodes:ro
30    networks:
31      - typesense-net
32    restart: unless-stopped
33
34  nginx:
35    image: nginx:alpine
36    ports:
37      - "8108:8108"
38    volumes:
39      - ./nginx.conf:/etc/nginx/nginx.conf:ro
40    depends_on:
41      - typesense-1
42      - typesense-2
43      - typesense-3
44    networks:
45      - typesense-net
46    restart: unless-stopped
47
48  prometheus:
49    image: prom/prometheus:latest
50    ports:
51      - "9090:9090"
52    volumes:
53      - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro
54      - prometheus_data:/prometheus
55    networks:
56      - typesense-net
57    restart: unless-stopped
58
59  grafana:
60    image: grafana/grafana:latest
61    ports:
62      - "3000:3000"
63    environment:
64      GF_SECURITY_ADMIN_PASSWORD: ${GRAFANA_PASSWORD}
65    volumes:
66      - grafana_data:/var/lib/grafana
67    networks:
68      - typesense-net
69    restart: unless-stopped
70
71volumes:
72  ts1_data:
73  ts2_data:
74  ts3_data:
75  prometheus_data:
76  grafana_data:
77
78networks:
79  typesense-net:
80    driver: bridge
81EOF
82
83# 2. Create the .env file
84cat > .env << 'EOF'
85# Typesense API Key
86TYPESENSE_API_KEY=your_secure_api_key_here
87
88# Grafana
89GRAFANA_PASSWORD=secure_grafana_password
90EOF
91
92# 3. Start the services
93docker compose up -d
94
95# 4. View logs
96docker 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-search-stack/run | bash

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

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

typesenseprometheusgrafananginx

Related Recipes

Ad Space

Shortcuts: C CopyF FavoriteD Download