# Typesense

> Fast open-source search engine optimized for instant search experiences.

- Category: Database Stacks
- Difficulty: beginner
- Components: typesense
- Tags: typesense, search, full-text, instant, algolia-alternative
- Source: https://docker.recipes/databases/typesense

## Overview

Typesense is a modern, open-source search engine built from the ground up to deliver instant, typo-tolerant search experiences. Created as a developer-friendly alternative to complex solutions like Elasticsearch and expensive services like Algolia, Typesense focuses on simplicity without sacrificing performance. It provides sub-10ms search responses while handling common search challenges like typos, synonyms, and result ranking out of the box. This Docker configuration deploys a single Typesense node that exposes a RESTful JSON API for indexing documents and performing searches. The setup includes persistent data storage and configurable API key authentication, making it suitable for both development and production environments. Typesense excels at use cases requiring real-time search with minimal operational overhead. E-commerce platforms benefit from Typesense's instant product search with faceting and filtering capabilities, while content sites can implement fast site-wide search without complex setup. Developers appreciate the straightforward API design and built-in features like geo-search and vector similarity search, making it an excellent choice for teams wanting powerful search functionality without the complexity of managing Elasticsearch clusters.

## Features

- Typo tolerance with intelligent fuzzy matching and ranking
- Sub-10ms search response times with instant-as-you-type results
- Built-in faceting and filtering for complex search refinement
- Geo-spatial search with distance-based sorting and filtering
- Vector search capabilities for semantic similarity matching
- Synonym management and result curation through pinning
- Multi-tenant search with collection-based data isolation
- RESTful JSON API with comprehensive search parameters

## Use cases

- E-commerce product catalogs with instant search and filtering
- Documentation sites requiring fast full-text search
- SaaS applications needing embedded search functionality
- Content management systems with real-time article discovery
- Job boards with location-based and skill-based search
- Real estate platforms combining text and geo-spatial search
- Knowledge bases requiring typo-tolerant search across documents

## Prerequisites

- Docker and Docker Compose installed on the host system
- Minimum 256MB RAM available, 1GB+ recommended for production
- Port 8108 available on the host for API access
- Basic understanding of RESTful APIs for search integration
- Valid TYPESENSE_API_KEY environment variable configured
- JSON data structure knowledge for document indexing

## docker-compose.yml

```yaml
services:
  typesense:
    image: typesense/typesense:latest
    container_name: typesense
    restart: unless-stopped
    command: --data-dir /data --api-key=${TYPESENSE_API_KEY}
    volumes:
      - typesense_data:/data
    ports:
      - "8108:8108"
    networks:
      - typesense-network

volumes:
  typesense_data:

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

## .env

```bash
TYPESENSE_API_KEY=changeme-api-key
```

## Usage notes

- Docs: https://typesense.org/docs/
- API at http://localhost:8108 - RESTful JSON API
- Health check: curl http://localhost:8108/health
- Instant typo-tolerant search with sub-10ms responses
- Built-in geo-search, faceting, and multi-tenant support
- Excellent Algolia alternative - similar DX, self-hosted

## Troubleshooting

- Container fails to start: Ensure TYPESENSE_API_KEY environment variable is set and not empty
- API returns 401 Unauthorized: Verify the X-TYPESENSE-API-KEY header matches your configured API key
- Search returns no results for valid queries: Check if documents are properly indexed and collection schema matches data structure
- High memory usage during indexing: Reduce batch size when importing large datasets or increase container memory limits
- Connection refused on port 8108: Confirm port mapping in docker-compose and check if firewall is blocking access
- Data loss after container restart: Verify typesense_data volume is properly mounted and persistent

