---
title: "Deploy Typesense Gatsby"
description: "Gatsby site search with Typesense"
category: "Analytics"
url: https://railway.com/deploy/typesense-gatsby
---

# Deploy Typesense Gatsby

Gatsby site search with Typesense

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

Machine-readable deploy manifest (JSON, validated by TemplateCI): https://railway.com/deploy/typesense-gatsby/manifest.json

- **Creator:** onepush
- **Category:** Analytics

## Template content

### typesense-railway

- **Source:** Shinyduo/typesense-railway
- **Public domain:** Yes

## Documentation

# Deploy and Host self hosted Typesense Gatsby (Open-Source Instant Search) on Railway

Gatsby ships static HTML, and gatsby-plugin-typesense turns that into a searchable Typesense collection after each build. The plugin scans `public/` for elements with `data-typesense-field` attributes, creates a timestamped collection, then atomically flips an alias so readers never see a half-built index.

## About Hosting Typesense Gatsby open-source software on Railway (self hosted Typesense template)

This stack is two parts: a Typesense server on Railway and the Gatsby plugin running post-build wherever you build. Railway handles the server side — Docker image, volume, health checks — while your Gatsby build pushes documents over HTTP. The plugin does not need GraphQL or frontmatter.

## Why Deploy Typesense Gatsby, the Algolia alternative on Railway (Railway Free Trial)

Algolia's Gatsby integration locks you into SaaS per-search and per-record billing. Typesense gives the same instant search with a self-hosted GPL-3.0 server, and gatsby-plugin-typesense plugs in cleanly.

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

By deploying Typesense Gatsby on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.

### Railway vs Other Hosting Providers and VPS for Typesense Gatsby self hosting

| Provider | Setup effort for Typesense | Persistent volume | Pricing model | Good for |
|----------|---------------------------|-------------------|---------------|----------|
| Railway | Very low — one Docker service, one volume, one env var | Yes, attached automatically | Pay-as-you-go compute + volume, $5 trial | Fast prototyping, small production sites |
| DigitalOcean | Medium — droplet + Docker + volume setup, firewall, systemd | Manual block storage | Flat droplet pricing, $6–$12/month for basic | Predictable cost, full root control |
| AWS | High — ECS or EC2, EBS volume, security groups, IAM | EBS or EFS | Pay-as-you-go, complex discounts | Large scale, existing AWS footprint |
| Hetzner | Medium — dedicated or cloud server, install Docker, mount volume | Local disk or block storage | Very cheap, €3–€6/month for small VPS | Budget self-hosting with hands-on ops |

## Common Use Cases for hosted Typesense Gatsby

Deploy this when you want search on a static Gatsby site without per-query fees. Documentation sites, engineering blogs, recipe collections, and product catalogs fit. The plugin's `exclude` option takes a regex to skip directories.

## Dependencies for Typesense Gatsby Docker hosted on Railway

You need the Typesense server image and a Gatsby project with the plugin installed. The plugin depends on the `typesense` Node client and expects an admin API key at build time.

### Deployment Dependencies for Managed Typesense Gatsby Service (Static Site Search)

On Railway, create a service from `typesense/typesense:30.2`. Set the start command to `--data-dir /data --api-key=$TYPESENSE_API_KEY --enable-cors`. Attach a volume at `/data`. `TYPESENSE_API_KEY` is required — it's the bootstrap admin key.

### Implementation Details for Typesense Gatsby (Using Typesense official docker image)

Use `typesense/typesense:30.2`, not `latest`. The server loads the dataset into RAM, so size Railway compute to hold the index plus margin. Enable CORS with `--enable-cors` because browser InstantSearch clients make cross-origin requests.

## How does Typesense Gatsby compare against other Static Site Search platforms

Each approach solves the same problem differently. Typesense Gatsby wins on index freshness and control, but not every site needs that.

### Typesense Gatsby vs Algolia (gatsby-plugin-algolia)

gatsby-plugin-algolia is mature and pushes GraphQL query results to Algolia, so setup is fast if you accept usage billing. The Typesense plugin reads finished HTML instead. Algolia's free tier caps records and searches; Typesense has no per-search fee on self-hosted. The catch: you operate the Typesense server.

### Typesense Gatsby vs gatsby-plugin-local-search (Lunr/FlexSearch)

Local search plugins index at build time and ship the whole index to the browser as JSON. That works for a few hundred pages, but every visitor downloads the index and search runs in JavaScript. Typesense keeps the index on the server, scaling to tens of thousands of pages without bloating the bundle.

### Typesense Gatsby vs Meilisearch

Meilisearch is MIT-licensed, has its own Gatsby plugin, and keeps the index on disk through memory-mapped storage, which is friendlier to larger-than-RAM datasets. Typesense keeps everything in RAM for steady low latency, so you size memory up front.

### Typesense Gatsby vs Pagefind

Pagefind is a static browser-side index built from your HTML, requiring no server at all — a win for small sites. However, Pagefind has no server-side synonyms or curation, can't rank on fields like `page_priority_score`, and every content change waits for a rebuild.

## How to use Typesense Gatsby (the OSS Static Site Search)?

Install the plugin, configure it in `gatsby-config.js`, and add data attributes to page templates. The plugin runs on `postBuild`, so it needs a running Typesense server reachable from your build environment.

## How to self host Typesense Gatsby on other VPS Services (Typesense Gatsby self hosting guide)

You can run Typesense on any Docker-capable VPS. The Gatsby plugin doesn't care where the server lives, as long as it can reach the API over HTTP. Make sure the VPS firewall allows inbound TCP 8108 from your build environment and, if needed, from browser clients for search-only requests.

### Clone the Repository

Clone your Gatsby site repository (or a fresh starter). For the server, you don't need a repository — just Docker. For the plugin, your site repo already contains the config.

### Install Dependencies

On the VPS, install Docker and Docker Compose. For the Gatsby build, install Node.js 18+ and Gatsby CLI. Run `npm install` in your site directory to pull in `gatsby-plugin-typesense`, `typesense`, and InstantSearch packages.

### Configure Environment Variables

Create a `.env` with `TYPESENSE_API_KEY` (a long random string) for the server. For the build, set `TYPESENSE_ADMIN_API_KEY` to that same key, `TYPESENSE_HOST` to the server's IP or domain, and `TYPESENSE_PORT` to `8108`.

### Start the Typesense Gatsby Application

Start Typesense with `docker run -d -p 8108:8108 -v /var/lib/typesense:/data typesense/typesense:30.2 --data-dir /data --api-key=$TYPESENSE_API_KEY --enable-cors`. Then run `gatsby build`.

## Official Pricing of Typesense Gatsby (Typesense Gatsby pricing)

The Gatsby plugin is free and open-source, same as Typesense. You pay only for the server. Typesense Cloud bills dedicated RAM and vCPU hourly plus bandwidth, no per-search fee. A 0.5 GB burst node is about $21.60/month; 2 GB burst is about $43–$51/month.

## Typesense Gatsby cloud vs self hosted comparison (Pricing, features, costs, and more)

Typesense Cloud removes operational burden: they manage updates, backups, and HA. Self-hosting on Railway or a VPS gives full data control and a lower cost floor, but you handle upgrades and monitoring.

### Monthly cost of self hosting Typesense Gatsby on Railway

A minimal Typesense service on Railway with 512 MB RAM, 0.5 vCPU, and 1 GB volume typically lands in single-digit USD per month, and the $5 trial covers the first experiments. If the index outgrows RAM, scale to 1–2 GB and expect low teens.

### System Requirements for Hosting Typesense Gatsby on a VPS

Typesense holds the whole index in memory, so choose RAM at least 1.5x the on-disk index size. A few thousand marked-up pages usually fit comfortably in 512 MB because only tagged fields get indexed. CPU matters less — a single vCPU handles thousands of searches per minute.

## Frequently Asked Questions (FAQs)

### How do I create a search-only key for the browser?

After the plugin finishes, `POST` to `http://your-typesense-host:8108/keys` with body `{"description":"search-only","actions":["documents:search"],"collections":["your_collection_name"]}`. Use the returned key in your frontend. Never expose the admin key.

### What happens if the Typesense server restarts during a build?

The plugin creates a new timestamped collection before indexing. If the server restarts mid-build, the new collection may be incomplete, but the alias still points to the old one. When the build reruns successfully, it creates another new collection, swaps the alias, and deletes the stale one.

### Can I use gatsby-plugin-typesense with a non-Gatsby static site?

No. The plugin hooks into Gatsby's `postBuild` lifecycle. For other static site generators, write a custom script that scans HTML and pushes to Typesense using the API.

### Does the plugin support faceted search?

Yes, but define facet fields in the collection schema. Any data attribute mapped to a facet field becomes available for filtering in `react-instantsearch`. The plugin extracts text content only, so use separate attributes for tags or categories.

### How do I handle multiple languages?

Add multiple plugin entries in `gatsby-config.js`, each with a different `collectionSchema.name` and a different `exclude` regex to target language-specific paths. The browser uses the search-only key scoped to the active language's collection.

### Can I change the admin API key after the first run?

You can change the `TYPESENSE_API_KEY` startup flag and restart, but that only changes the bootstrap key. Keys created via `/keys` (like search-only) are stored in `/data` and still work. To revoke them, delete via the API before changing the flag.


## Similar templates

- [Typesense PHP](https://railway.com/deploy/typesense-php) — official PHP client against Railway
- [Typesense vs Meilisearch](https://railway.com/deploy/typesense-vs-meilisearch) — self-hosted Typesense vs Meilisearch
- [Matomo Analytics + MariaDB](https://railway.com/deploy/matomo-analytics-mariadb) — Privacy-friendly analytics with MariaDB and persistent volumes.

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