Deploy and Host self hosted Typesense Hugo (Instant Search for Hugo Sites) on Railway

This template runs a self-hosted Typesense node on Railway to add instant search to Hugo docs, blogs, or knowledge bases.

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

Your search index is the part of a Hugo site nobody notices until a docs reader types a word and gets nothing back.

The service builds from the Shinyduo/typesense-railway repo: Typesense 30 behind a small Caddy proxy on PORT 8080, forwarding to 127.0.0.1:8118.

Why Deploy Typesense Hugo, the Algolia DocSearch alternative on Railway (Railway Free Trial)

DocSearch is hard to beat for free docs search, since its crawler indexes a Hugo site with no infrastructure on your end.

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 Hugo 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 Hugo self hosting

Self-hosting the Typesense Hugo search backend means deciding how much server work you want to own.

Provider	What You Get with Railway	What You Get with the Other Provider
DigitalOcean	A Typesense 30 service with a volume and HTTPS domain, and no droplet to patch.	Root access and predictable droplet pricing, but Docker, TLS, and backups are yours.
AWS	A managed service with a volume and public domain, billed by usage, with no VPC setup first.	Deep networking options, which is overkill for one search node.
Hetzner	Faster setup than a bare server, with Caddy on PORT 8080 already routed to Typesense.	Strong CPU and RAM per euro, if you enjoy managing Linux updates by hand.

Railway trades some low-level control for speed, which suits a docs index well.

Common Use Cases for hosted Typesense Hugo

Documentation sites: A docs theme with a few hundred pages needs search that handles "webhook retry" and lands on the right heading. A Hugo JSON index built at deploy time and imported into Typesense gives typo tolerance and facets without a crawler or a third-party account.
Blogs and changelogs: Titles, tags, and dates become filterable fields, so readers can narrow results to one year or category.
Internal knowledge bases: Private Hugo sites stay private. The admin key lives only in CI, and the browser gets a search-only key scoped to one collection.
Multilingual sites: Each language becomes its own collection, and the browser picks the right one from the page language.
Sites outgrowing client-side search: When Pagefind or Fuse.js gets slow on a growing page count, the same JSON pattern moves to Typesense with little front-end change.

Dependencies for Typesense Hugo Docker hosted on Railway

Typesense Hugo has three parts that must agree. Your Hugo build emits a JSON index of pages. The browser queries Typesense with a search-only key.

Deployment Dependencies for Managed Typesense Hugo Service (Search Engine for Hugo Static Sites)

Create a Railway service from the Shinyduo/typesense-railway repo with a persistent volume and a public HTTPS domain.

Implementation Details for Typesense Hugo (Using Typesense official docker image)

Add a JSON format under outputFormats and list it for the home page with home = ['html', 'json'].

How does Typesense Hugo compare against other search options for Hugo sites platforms

Most Hugo sites start with something lightweight and move to a server-backed engine only when content grows or search needs get picky.

Typesense Hugo vs Algolia DocSearch (Algolia DocSearch Alternative)

Where it wins: You own the index. DocSearch crawls your docs on its own schedule, while your Hugo JSON index lives in a collection on your own Railway volume.
Where it loses: DocSearch is free for qualifying open-source docs and needs almost no setup. Typesense Hugo asks you to write the CI import step and run a service.
Gotcha: Keep the admin key in CI only. Browser code gets a scoped search-only key.

Typesense Hugo vs Pagefind (Static Search Alternative)

Where it wins: Pagefind needs no server. It builds its index during the Hugo build and ships static files.
Where it loses: Typesense Hugo gives you faceting, numeric filters, and a real API that Pagefind's bundle does not expose.
Gotcha: For a small blog, Pagefind is the better default.

Typesense Hugo vs Lunr.js (Client-Side Index Alternative)

Where it wins: Lunr.js runs entirely in the browser with no network calls after page load, which suits a few hundred pages.
Where it loses: Lunr.js ships the whole index to every visitor, so a large docs site gets a heavy download and slow first search.
Gotcha: You maintain the index logic yourself, while Typesense Hugo handles ranking and typo tolerance out of the box.

Typesense Hugo vs Fuse.js (Fuzzy Search Alternative)

Where it wins: Fuse.js is a few kilobytes and searches a plain JSON array with fuzzy matching. It is the fastest way to get something working.
Where it loses: Fuse.js scans the array on every keystroke, so it slows down once the JSON grows. Typesense Hugo indexes up front and stays quick at scale.
Gotcha: Under a few hundred pages with only fuzzy needs, Fuse.js is enough.

How to use Typesense Hugo (the OSS Search Engine for Hugo Static Sites)?

Hugo ships with no search, so day one is about loading one collection of pages into Typesense and keeping the admin key out of the browser.

Swap the placeholder key. Set TYPESENSE_API_KEY to a long random value in Railway, then redeploy.
Add a JSON output for the home page. Define the format under outputFormats, list it for home, and set isPlainText = true so Hugo does not escape values.
Write layouts/index.json.json to emit title, url, and body text for each page.
In CI, after hugo --minify, import that JSON with the typesense JS client using the admin key from CI secrets.
Mint a search-only key through the /keys API, scoped to that collection, and ship only that key to the frontend.
In the browser, install typesense-instantsearch-adapter and instantsearch.js, point the adapter at TYPESENSE_PUBLIC_URL, and set query_by.

Check CORS before you celebrate. It is not enabled by default on this template, so browser calls from your Hugo domain may fail until you configure it.

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

Running this on a VPS means you own the proxy and the volume holding your index.

Clone the Repository

Start from the template repo so the Caddy proxy and Typesense 30 image match the Railway setup.

git clone https://github.com/Shinyduo/typesense-railway.git typesense-hugo
cd typesense-hugo

Install Dependencies

The build step needs the Typesense JS client, and the browser needs the adapter and InstantSearch.js.

npm install --save typesense typesense-instantsearch-adapter instantsearch.js @babel/runtime

Configure Environment Variables

Replace the template key with a long random value first, then set the public domain.

export TYPESENSE_API_KEY="$(openssl rand -hex 32)"
export TYPESENSE_PUBLIC_URL="https://search.your-domain.example"
export TYPESENSE_DATA_DIR="/var/lib/typesense"
export PORT=8080

Start the Typesense Hugo Application

Run the container with the volume mounted, then check health through Caddy.

docker run -d --name typesense-hugo -p 8080:8080 \
  -e TYPESENSE_API_KEY -e TYPESENSE_DATA_DIR -e PORT \
  -v /var/lib/typesense:/var/lib/typesense \
  your-image-here
curl https://search.your-domain.example/health

Railway handles the HTTPS domain, private networking, and the volume for you, which is most of what this section does by hand.

Official Pricing of Typesense Hugo (Typesense Hugo pricing)

Typesense itself is open source under GPL-3.0, so there is no license fee to pay for Typesense Hugo.

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

Hosted Typesense Cloud and a self-hosted node on Railway run the same engine, so the choice comes down to who handles operations and how the bill grows.

Monthly cost of self hosting Typesense Hugo on Railway

On Railway you pay for compute and the volume holding your index, with no per-search fee.

System Requirements for Hosting Typesense Hugo on a VPS

Typesense keeps the index in memory, so size RAM to the dataset, not to traffic. Add a persistent disk for snapshots and a single vCPU for light query load.

Frequently Asked Questions (FAQs)

Do I need a custom Hugo output format for the search index?

Not really. Set isPlainText = true on any custom format or Hugo will HTML-escape values and show & in results.

Can the browser use the Typesense admin key?

No. The admin key can create, delete, and export everything, so keep it in CI only.

Why do my InstantSearch filters only work on first load?

The adapter overrides filter_by set in additionalQueryParameters once InstantSearch takes over.

How often should CI re-import the index?

Re-import on every Hugo build, since the JSON index goes stale as soon as a page changes. For a docs or blog site that's usually a few seconds per deploy.

Why are browser search requests blocked by CORS?

CORS isn't enabled by default on this template, so calls from your Hugo domain can fail even with a valid key.

Why doesn't a new page show up in search right away?

The adapter caches client-side results for 2 minutes by default.