Install Typesense: Self-Hosted Instant Search on a VPS

Typesense is an open-source, typo-tolerant search engine designed for instant search experiences. It’s similar in spirit to Meilisearch and Algolia: fast, easy to run, and good relevance with little tuning. Typesense uses an explicit schema per collection, keeps the index in RAM for very low latency, and has built-in clustering for high availability.

Install

Docker

TS_KEY=$(openssl rand -hex 32)
echo "$TS_KEY" | sudo tee /root/typesense-admin-key >/dev/null && sudo chmod 600 /root/typesense-admin-key

docker run -d --name typesense --restart unless-stopped \
  -p 127.0.0.1:8108:8108 \
  -v typesense-data:/data \
  typesense/typesense:27.1 \
  --data-dir /data --api-key="$TS_KEY" --enable-cors

(Use the current version.)

Debian/Ubuntu package

Download the .deb from Typesense’s site, then sudo apt install ./typesense-server-*.deb. The config is in /etc/typesense/typesense-server.ini, where you set api-key, data-dir and api-address = 127.0.0.1, and the service is typesense-server.

Check health:

curl http://127.0.0.1:8108/health
# {"ok":true}

Create a collection (schema)

curl -X POST 'http://127.0.0.1:8108/collections' \
  -H "X-TYPESENSE-API-KEY: $TS_KEY" -H 'Content-Type: application/json' \
  -d '{
    "name": "products",
    "fields": [
      {"name": "name", "type": "string"},
      {"name": "brand", "type": "string", "facet": true},
      {"name": "category", "type": "string", "facet": true},
      {"name": "price", "type": "float"},
      {"name": "popularity", "type": "int32"}
    ],
    "default_sorting_field": "popularity"
  }'

Explicit types catch data problems early, and make filtering and sorting efficient. Use "type": "auto" fields for flexible attributes if needed.

Import documents

JSONL (one JSON object per line) is the fastest format:

curl -X POST 'http://127.0.0.1:8108/collections/products/documents/import?action=upsert' \
  -H "X-TYPESENSE-API-KEY: $TS_KEY" -H 'Content-Type: text/plain' \
  --data-binary @products.jsonl

Each document needs an id (string). Use action=upsert to insert or update.

Search

curl -G 'http://127.0.0.1:8108/collections/products/documents/search' \
  -H "X-TYPESENSE-API-KEY: $TS_KEY" \
  --data-urlencode 'q=keybord' \
  --data-urlencode 'query_by=name,brand' \
  --data-urlencode 'filter_by=price:<100 && category:=accessories' \
  --data-urlencode 'facet_by=brand' \
  --data-urlencode 'sort_by=popularity:desc'

Typo tolerance, prefix matching, facets, filters, geo search and synonyms are built in. Typesense also supports vector and hybrid search with embeddings. See vector databases.

API keys and security

The admin key (from startup) can do everything. Keep it on the server side only.
Create a search-only key for frontends:

curl -X POST 'http://127.0.0.1:8108/keys' \
  -H "X-TYPESENSE-API-KEY: $TS_KEY" -H 'Content-Type: application/json' \
  -d '{"description":"frontend","actions":["documents:search"],"collections":["products"]}'

Scoped API keys, generated by your backend, embed filters, such as filter_by: tenant_id:=42, so each user can only search their own records. This is essential in multi-tenant apps.

Expose Typesense through Nginx with HTTPS, rather than opening port 8108 directly:

location / {
    proxy_pass http://127.0.0.1:8108;
    proxy_set_header Host $host;
}

See Nginx server blocks and Let’s Encrypt.

Memory sizing

Typesense keeps the searchable index in RAM. As a rough guide, plan about 2–3× the size of the indexed fields in memory. A 1 GB dataset of searchable text needs roughly 2–3 GB of RAM. Only fields you search, filter or facet on need indexing. Mark others as non-indexed ("index": false) to save memory. See how much RAM a VPS needs.

High availability: clustering

Typesense supports a Raft-based cluster of 3 (or 5) nodes. Each node has the full dataset, writes go through the leader, and any node serves reads. Configure --nodes with all members’ private IPs (peering port 8107, API port 8108). Use a private network between nodes. See vps high availability.

Backups

curl -X POST "http://127.0.0.1:8108/operations/snapshot?snapshot_path=/data/snapshots/$(date +%F)" \
  -H "X-TYPESENSE-API-KEY: $TS_KEY"

Copy snapshots off the server. You can also rebuild indexes from your primary database, which should remain the source of truth. See backup strategy.

Typesense vs Meilisearch

	Typesense	Meilisearch
Schema	Explicit (or auto)	Schemaless
Storage	Index in RAM	Memory-mapped on disk
Clustering / HA	Built in (Raft)	Single node (replication in enterprise or cloud)
Typo tolerance, facets	Yes	Yes
Vector / hybrid search	Yes	Yes
Licence	GPLv3	MIT (core)

Both are excellent. Choose Typesense for built-in HA and RAM-speed, and Meilisearch for simplicity. See Meilisearch.

Quick reference

Task	Endpoint
Health	`GET /health`
Create collection	`POST /collections`
Import	`POST /collections/{name}/documents/import`
Search	`GET /collections/{name}/documents/search`
Create key	`POST /keys`
Snapshot	`POST /operations/snapshot`

Search
Self-Hosting
Databases