Posted inDatabase

Deploying Typesense with Docker: Building High-Speed Instant Search for Your Application

Database tutorial - IT technology blog
Database tutorial - IT technology blog

Why Choose Typesense Over Elasticsearch or SQL?

If you’ve ever tried searching using the LIKE %query% statement in SQL, you’ve likely seen the system “freeze” when data hits several hundred thousand rows. Elasticsearch is a popular alternative, but it is too RAM-intensive. Typically, Elasticsearch needs at least 2GB of RAM just to start up stably.

Typesense is a much more lightweight alternative. Written in C++ and running entirely in RAM, it keeps response times (latency) consistently under 50ms.

In practice, a Typesense server only needs about 200MB of RAM to smoothly handle 100,000 records. This tool comes with built-in Typo Tolerance and Faceting without complex configuration. It is an ideal choice for building “search-as-you-type” features similar to Algolia but with near-zero self-hosting costs.

Core Concepts

Before getting started, you need to master these 4 basic components:

  • Collections: Equivalent to a Table in SQL. This is where groups of similar data are stored.
  • Documents: Specific records in JSON format.
  • Fields: Data fields (e.g., product name, price).
  • Schema: The blueprint that defines data types and specifies which fields will be indexed.

Deploying Typesense with Docker in 5 Minutes

Using Docker allows you to install Typesense quickly without affecting your existing system. The best way is to use docker-compose for easier environment variable management.

1. Create the docker-compose.yml file

Create a project directory and add a docker-compose.yml file with the following content:

services:
  typesense:
    image: typesense/typesense:26.0
    container_name: typesense
    restart: on-failure
    ports:
      - "8108:8108"
    volumes:
      - ./typesense-data:/data
    command: 
      - '--data-dir' 
      - '/data' 
      - '--api-key=huongdanit_secret_key' 
      - '--enable-cors'

Note on parameters:

  • 8108: The default connection port.
  • --api-key: Security key for interacting with the API. You should change this to a longer random string for production.
  • --enable-cors: Allows browsers to call the API directly, which is crucial for Frontend Search.

2. Start the Container

Run the following command in your terminal:

docker-compose up -d

To check the status, visit http://localhost:8108/health. If the browser displays {"ok":true}, the system is ready.

Hands-on: Creating a Schema and Importing Data

Once the server is running, we need to define the data structure for it.

Step 1: Create a Schema for products

Use curl to create a collection named products:

curl "http://localhost:8108/collections" \
  -X POST \
  -H "X-TYPESENSE-API-KEY: huongdanit_secret_key" \
  -d '{
    "name": "products",
    "fields": [
      {"name": "title", "type": "string" },
      {"name": "category", "type": "string", "facet": true },
      {"name": "price", "type": "float" },
      {"name": "rating", "type": "int32" }
    ],
    "default_sorting_field": "rating"
  }'

Step 2: Bulk Import Data

Typesense requires JSONL format (each line is a JSON object) to achieve the highest import speed. If you have a CSV file from Excel, convert it to JSON first.

Quick Tip: You can use the conversion tool at toolcraft.app to quickly process sample data right in your browser without worrying about data exposure.

Once you have the products.jsonl file, push the data into the system:

curl "http://localhost:8108/collections/products/documents/import?action=create" \
  -X POST \
  -H "X-TYPESENSE-API-KEY: huongdanit_secret_key" \
  --data-binary "@products.jsonl"

Search Querying: The Power of Instant Search

Try searching with a misspelled keyword (e.g., “ipone” instead of “iphone”):

curl "http://localhost:8108/collections/products/documents/search?q=ipone&query_by=title" \
  -H "X-TYPESENSE-API-KEY: huongdanit_secret_key"

Typesense will return approximate results along with highlight information. This feature allows you to bold matching keywords on the interface, creating an extremely smooth search experience for users.

Tips for Optimizing Typesense in Production

Below are important notes for more stable system operation:

  1. API Key Permissions: Never use the Admin Key on the Frontend. Create a “Search Only Key” to limit permissions to only searching data.
  2. RAM Monitoring: Since data resides in RAM, set up alerts when free space drops below 20%. If RAM fills up, the container may crash unexpectedly (OOM).
  3. Use Aliases: You should create an alias products_live pointing to products_v1. When you need to re-index all data into products_v2, you just need to point the alias to the new collection without service interruption.
  4. Backup Strategy: Typesense writes logs to the hard disk in the /data directory. Ensure you have a regular backup schedule for this folder to prevent data loss.

Conclusion

Typesense is an excellent balance between performance and simplicity. With Docker, deployment takes only minutes, allowing you to focus on feature development instead of struggling with server configuration. If your project needs a smart search engine with low infrastructure costs, give Typesense a try.

I hope this article helps you build a search system you’re happy with. If you encounter any errors during installation, feel free to leave a comment below for support!

Share:
Tags: