---
title: "Deploy Typesense"
description: "Search engine that powers fast, typo-tolerant search boxes"
category: "Storage"
url: https://railway.com/deploy/typesense-search
---

# Deploy Typesense

Search engine that powers fast, typo-tolerant search boxes

**[Deploy Typesense on Railway](https://railway.com/template/typesense-search)**

- **Creator:** A3A
- **Category:** Storage
- **Total deploys:** 1

## Template content

### typesense https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/typesense.svg

- **Image:** typesense/typesense:30.2
- **Start command:** `/bin/sh -c 'C=4; if [ -r /sys/fs/cgroup/cpu.max ]; then read Q P < /sys/fs/cgroup/cpu.max; if [ "$Q" != "max" ] && [ -n "$P" ]; then C=$(( (Q + P - 1) / P )); fi; fi; if [ "$C" -lt 1 ]; then C=1; fi; if [ -z "$TYPESENSE_THREAD_POOL_SIZE" ]; then TYPESENSE_THREAD_POOL_SIZE=$((C * 8)); fi; if [ -z "$TYPESENSE_NUM_COLLECTIONS_PARALLEL_LOAD" ]; then TYPESENSE_NUM_COLLECTIONS_PARALLEL_LOAD=$((C * 4)); fi; export TYPESENSE_THREAD_POOL_SIZE TYPESENSE_NUM_COLLECTIONS_PARALLEL_LOAD; echo "[railway] cgroup cpus=$C thread-pool=$TYPESENSE_THREAD_POOL_SIZE parallel-load=$TYPESENSE_NUM_COLLECTIONS_PARALLEL_LOAD"; exec /opt/typesense-server'`
- **Health check:** /health
- **Public domain:** Yes

### typesense-dashboard https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/typesense.svg

- **Image:** ghcr.io/bfritscher/typesense-dashboard:latest
- **Start command:** `/bin/sh -c 'printf "{\"node\":{\"host\":\"%s\",\"port\":\"443\",\"protocol\":\"https\",\"path\":\"\",\"tls\":true}}\n" "$TYPESENSE_HOST" > /srv/config.json; if [ -n "$TYPESENSE_HOST" ]; then P=0; for f in /srv/assets/node-*.js; do if grep -q "host:\`localhost\`,port:8108,protocol:\`http\`" "$f" 2>/dev/null; then sed -i "s|host:\`localhost\`,port:8108,protocol:\`http\`|host:\`$TYPESENSE_HOST\`,port:443,protocol:\`https\`|g" "$f"; P=1; fi; done; if [ "$P" = 1 ]; then echo "[railway] login form defaults patched to https://$TYPESENSE_HOST"; else echo "[railway] default node literal not found - enter host $TYPESENSE_HOST port 443 protocol https at the login screen"; fi; fi; printf "{\n\tservers {\n\t\ttrusted_proxies static 100.64.0.0/10 fd00::/8\n\t}\n}\n:%s {\n\troot * /srv\n\tencode gzip\n\theader {\n\t\tX-Frame-Options \"SAMEORIGIN\"\n\t\tX-Content-Type-Options \"nosniff\"\n\t\tReferrer-Policy \"strict-origin-when-cross-origin\"\n\t}\n\ttry_files {path} /index.html\n\tfile_server\n}\n" "${PORT:-8080}" > /etc/caddy/Caddyfile; caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile; exec caddy run --config /etc/caddy/Caddyfile --adapter caddyfile'`
- **Health check:** /
- **Public domain:** Yes

## Documentation

# Deploy and Host Typesense on Railway

Typesense is an open-source, typo-tolerant search engine built for instant search-as-you-type experiences. It keeps its index in memory and answers queries over a plain REST/JSON API, so a search box backed by Typesense returns results in single-digit milliseconds without the weight of an Elasticsearch cluster. Teams use it for storefront product search, documentation search, in-app search over records, and — since it stores vectors too — semantic and hybrid search. It is the open-source answer to Algolia, with the same ergonomics and no per-search billing.

Deploy Typesense on Railway and you get two services wired together: the `typesense` search server, holding its index on a persistent volume at `/data` and reachable over HTTPS with an API key, and `typesense-dashboard`, a browser admin interface for creating collections, importing documents, running searches and minting scoped keys. The dashboard is a static single-page app that talks to the server from your browser, which is why cross-origin requests are enabled. Both services come up with working defaults, so you can self-host Typesense and be indexing minutes after the deploy finishes.

![Diagram of the Typesense and dashboard services on Railway](https://res.cloudinary.com/rroe4rtk/image/upload/v1787424278/typesense-architecture.png)

## Getting Started with Typesense on Railway

Once the deploy is green, open the `typesense` service's public URL with `/health` appended — a healthy node answers `{"ok":true}`, the one route needing no authentication. Everything else needs the admin API key Railway generated, stored as `TYPESENSE_API_KEY` on the `typesense` service; copy it from the Variables tab. Now open the `typesense-dashboard` URL: protocol, host and port already point at your search server, so paste the key into the Api Key field and press Login. You land on Server Status, reporting the node's version, role and memory use — proof the dashboard reaches your server. Use Collections to create a collection with its fields and a default sorting field, then Add Document or Import to load records. Open Search to query it with facets and filters, and misspell a word to watch typo tolerance work. Before wiring a public site to it, create a `documents:search` key scoped to that collection on the API Keys page — the admin key can delete data, so it must never reach a browser.

![Typesense Dashboard browsing a books collection with author facets](https://res.cloudinary.com/rroe4rtk/image/upload/v1787424281/typesense-faceted-book-browse.png)

![Typo-tolerant Typesense search matching two Murakami novels](https://res.cloudinary.com/rroe4rtk/image/upload/v1787424283/typesense-typo-tolerant-search.png)

![Typesense server status showing a healthy leader node](https://res.cloudinary.com/rroe4rtk/image/upload/v1787424288/typesense-node-server-status.png)

## About Hosting Typesense

Typesense is a single C++ binary that loads collections into RAM and persists them to an on-disk store, which is what makes its latency predictable: no JVM to tune, no shard planning, no query DSL. You define a schema, POST JSON documents, and search with query parameters. Self-host it when search is core to your product and you would rather own the data and the cost curve than pay per search.

- Typo tolerance, prefix search and configurable ranking by default
- Faceting, filtering, grouping and sorting in one query
- Vector and hybrid search, so semantic results sit beside keyword results
- Synonyms, curated pins, stopwords and stemming for editorial control
- Scoped API keys, including keys carrying a filter for multi-tenant search
- Clients for JavaScript, Python, Ruby, PHP, Go and Java, plus InstantSearch.js

The Railway architecture is deliberately small. The `typesense` service is the entire data layer — no database, cache or object storage, because the volume at `/data` holds the index and write-ahead log. The `typesense-dashboard` service holds no state; it serves static files behind Caddy, and its requests to the search server all happen in your browser.

## Why Deploy Typesense on Railway

Railway removes the server work from running a search engine:

- The persistent volume at `/data` survives redeploys and restarts
- HTTPS and a public domain for both the API and the dashboard
- A health check on `/health` catches a node that stops answering
- Thread-pool sizing follows the container's quota, not the host's core count
- Vertical scaling is a slider, which is how Typesense wants to grow

## Common Use Cases

- Storefront product search with facets for brand, price and category
- Documentation or knowledge-base search embedded with InstantSearch.js
- In-app search across users, tickets or orders, with a scoped key per tenant
- Semantic and hybrid retrieval for RAG, vectors and keywords in one engine

## Dependencies for Typesense

- `typesense/typesense:30.2` — the search server ([Docker Hub](https://hub.docker.com/r/typesense/typesense), [github.com/typesense/typesense](https://github.com/typesense/typesense))
- `ghcr.io/bfritscher/typesense-dashboard:latest` — the admin interface ([github.com/bfritscher/typesense-dashboard](https://github.com/bfritscher/typesense-dashboard))
- A 5 GB Railway volume mounted at `/data` on the search server

The server version is pinned because Typesense publishes no floating stable tag, and its data directory belongs to a major version — a surprise upgrade would leave an index unreadable. The dashboard is stateless, so it tracks its latest release.

### Environment Variables Reference

| Variable | Service | Purpose |
|---|---|---|
| `TYPESENSE_API_KEY` | typesense | Bootstrap admin key sent as `X-TYPESENSE-API-KEY` |
| `TYPESENSE_DATA_DIR` | typesense | Index location; must be the volume mount |
| `TYPESENSE_API_PORT` | typesense | Port the search API listens on |
| `TYPESENSE_ENABLE_CORS` | typesense | Allows browser clients, including the dashboard |
| `TYPESENSE_HOST` | typesense-dashboard | Search server host the login form points at |

### Deployment Dependencies

- Documentation and API reference: [typesense.org/docs](https://typesense.org/docs/)
- Client libraries and the InstantSearch adapter: [github.com/typesense](https://github.com/typesense)

## Hardware Requirements for Self-Hosting Typesense

Typesense holds its index in RAM, so memory — not CPU — is the number that matters. Size it to two or three times the documents you index, and keep usage under 85% of the container's memory.

| Resource | Minimum | Recommended |
|---|---|---|
| CPU | 1 vCPU | 2–4 vCPU |
| RAM | 512 MB | 2 GB+, scaled to index size |
| Storage | 5 GB volume | 2× the size of your indexed data |
| Runtime | Docker | Docker, one node per volume |

This template ships a single node. Typesense's clustering addresses peers by private IPv4, which Railway's IPv6-only private network does not provide, so scale vertically rather than adding peer services.

## Self-Hosting Typesense

Locally the engine is one container plus a data directory. The following runs the same image this template deploys:

```
docker run -d --name typesense -p 8108:8108 \
  -v "$(pwd)/typesense-data:/data" \
  typesense/typesense:30.2 \
  --data-dir /data --api-key=CHANGE_ME --enable-cors
```

Create a collection and search it with any HTTP client. The following uses curl:

```
curl -X POST "http://localhost:8108/collections" \
  -H "X-TYPESENSE-API-KEY: CHANGE_ME" \
  -d '{"name":"books","fields":[{"name":"title","type":"string"},
       {"name":"year","type":"int32"}],"default_sorting_field":"year"}'

curl "http://localhost:8108/collections/books/documents/search?q=hitchhikr&query_by=title" \
  -H "X-TYPESENSE-API-KEY: CHANGE_ME"
```

On Railway, replace `http://localhost:8108` with your public URL and the key with `TYPESENSE_API_KEY`. Every server flag has an environment variable equivalent, so anything in the configuration reference can be set from the Variables tab of the service.

## How Much Does Typesense Cost to Self-Host?

The Typesense server is free and open source under GPL-3.0, with no feature gating against the paid product — clustering, vector search and scoped keys are all in the open-source binary. Typesense Cloud, from the same team, starts around $7 per month for a small single-region node and rises with RAM, vCPU and high availability. Self-hosting on Railway costs only the compute, memory and volume the two services use, with no per-search charge.

## FAQ

**What is Typesense?**

Typesense is an open-source search engine that returns typo-tolerant, ranked results over a REST/JSON API — a simpler, self-hostable alternative to Algolia and Elasticsearch for search-as-you-type.

**What does this Railway template deploy?**

The Typesense search server on a persistent volume, plus the Typesense Dashboard admin interface pre-pointed at it. Both get public HTTPS URLs; the server needs an API key on every route but its health check.

**Why does the search server need a volume instead of a database?**

Typesense is its own datastore. The volume at `/data` holds the index and write-ahead log, so collections and API keys survive redeploys.

**How do I connect my website or app to self-hosted Typesense?**

Create a search-only key on the dashboard's API Keys page, then point an official client, or the InstantSearch.js adapter, at your public URL on port 443 with `protocol: 'https'`. Never ship the admin key to a browser.

**Can I run a highly available Typesense cluster on Railway?**

Not as a multi-node Raft cluster: peers address each other over private IPv4, which Railway's private network does not route. Scale the node's CPU and memory instead, and snapshot through the `/operations/snapshot` endpoint.


## Similar templates

- [Garage S3 Storage](https://railway.com/deploy/garage-s3-storage) — Ultra-light S3 server: fast, open-source, plug-and-play.
- [Redis](https://railway.com/deploy/redis-1) — Self Host Latest Redis with Railway
- [EasyImg](https://railway.com/deploy/easyimg) — Simple self-hostable Nuxt.js personal image hosting system.

Open this page in a browser: https://railway.com/deploy/typesense-search