--- title: "Deploy Typesense Synonyms" description: "merchandising synonyms and overrides" category: "Analytics" url: https://railway.com/deploy/typesense-synonyms --- # Deploy Typesense Synonyms merchandising synonyms and overrides **[Deploy Typesense Synonyms on Railway](https://railway.com/template/typesense-synonyms)** Machine-readable deploy manifest (JSON, validated by TemplateCI): https://railway.com/deploy/typesense-synonyms/manifest.json - **Creator:** onepush - **Category:** Analytics ## Template content ### typesense-railway - **Source:** Shinyduo/typesense-railway - **Public domain:** Yes ## Documentation # Deploy and Host self hosted Typesense Synonyms (Open-Source Instant Search) on Railway Deploy Typesense on Railway for merchandising synonyms, aliases, and search overrides — steer queries without Algolia per-search billing. ## About Hosting Typesense Synonyms open-source software on Railway (self hosted Typesense template) Typesense Synonyms is a self-hosted instant search deployment focused on merchandising synonyms, aliases, and search overrides. It runs the official Typesense Docker image on Railway, giving you a dedicated search node you control end to end. You define multi-way synonym groups, one-way aliases, and overrides that pin, hide, or boost products. All configuration lives in a Typesense collection schema and is queryable through the REST API on port 8108. Railway handles container orchestration, health checks, log streaming, and volume persistence. You bring the Typesense image, set the API key, mount a volume at /data, and Railway keeps the node running. Typesense is in-memory, so RAM allocation directly determines how much of your catalog you can index. A small catalog fits in 512 MB; a large catalog with rich synonym sets needs 2 GB or more. Railway lets you resize the service vertically without re-provisioning infrastructure. This is not a managed Typesense Cloud account. It is the open-source Typesense server, GPL-3.0 licensed, running as a single Docker container with a persistent volume. You own the data, API key, schemas, and synonym configuration. You also own backups and key rotation. ## Why Deploy Typesense Synonyms, the Algolia alternative on Railway (Railway Free Trial) Algolia is SaaS-only. You cannot self-host Algolia. Every search request, synonym rule, and override lives on Algolia's infrastructure, billed by search requests and records stored. Typesense flips that model: it is open-source software you can run anywhere, including Railway, with no per-search fee and no record-count billing. You pay for compute and storage, not for how many times customers type "hoodie" and expect "sweatshirt" to match. Synonyms and overrides are business logic. A merchandiser who wants "chinos" to match "khakis" should not negotiate with a SaaS rate card. With Typesense on Railway, the synonym dictionary is a JSON payload you send to the collections endpoint. You can version it in Git and roll it back instantly. Algolia Grow bills on search requests and records stored. Typesense Cloud bills dedicated RAM/vCPU hourly plus bandwidth, with no per-search fee. A 0.5 GB burst node is about $21.60/month; a 2 GB burst node is about $43-$51/month. Self-hosting on Railway is typically single-digit to low-teens USD per month for a small node. 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 Synonyms 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 Synonyms self hosting | Provider | Setup Model | Synonym/Override Workflow | Cost Profile | Best For | |---|---|---|---|---| | DigitalOcean | Droplet or App Platform | Manual Docker run or DO Apps with volume | Predictable monthly droplet cost | Teams already on DO | | AWS | EC2, ECS, or Lightsail | IAM, security groups, EBS volumes | Metered, complex billing | Enterprise with AWS expertise | | Hetzner | Dedicated or cloud VPS | Manual Docker or Docker Compose | Very low per-GB RAM cost | Cost-sensitive EU hosting | | Railway | One-click template, managed volume | Deploy from GitHub, env vars, volume mount | Usage-based, $5 GitHub trial | Fastest path to production | ## Common Use Cases for hosted Typesense Synonyms - **E-commerce synonym groups:** Map "tee," "t-shirt," "tshirt," and "top" into one group so all queries return the same products. - **One-way brand aliases:** Map "iPhone" to "Apple iPhone" without reverse expansion, keeping brand queries precise. - **Promotional overrides:** Pin a specific cereal brand to the top for "breakfast cereal" during a promotion. - **Typo-tolerant fallback:** Bridge "aluminum" and "aluminium" or "catalog" and "catalogue" with synonyms. - **Multi-language aliases:** Map "hotel" to "hôtel," "hostel," and "lodging" in one group. - **Facet-aware overrides:** Boost "sofa" only when the user filters by "living room," not "office." ## Dependencies for Typesense Synonyms Docker hosted on Railway Typesense Synonyms needs a pinned Docker image, a persistent `/data` volume for the index, and `TYPESENSE_API_KEY`. Synonyms and overrides are collection API features; no extra Railway services beyond the Typesense node. ### Deployment Dependencies for Managed Typesense Synonyms Service (Instant Search) The Railway deployment requires a Docker image, an environment variable for the API key, a persistent volume, and a health check. Use the official image `typesense/typesense:30.2`; do not use `latest`. The container listens on port 8108. Railway's health check should hit `http://localhost:8108/health` and expect 200. The only required environment variable is `TYPESENSE_API_KEY`. This key authenticates all write operations: creating collections, upserting documents, and modifying synonyms and overrides. Never lose it. If lost, you cannot authenticate to the running node and must recreate the data directory or start a new node with a known key and re-import data. CORS must be enabled for browser-based InstantSearch clients. The start command includes `--enable-cors`. Without it, browser requests are blocked by same-origin policy. The /data directory must be mounted on a Railway volume. Typesense writes on-disk state to /data, including schemas, synonym dictionaries, and override rules. Without a volume, all configuration is lost on restart. ### Implementation Details for Typesense Synonyms (Using Typesense official docker image) The container start command is: ``` --data-dir /data --api-key=$TYPESENSE_API_KEY --enable-cors ``` Railway passes this as the command override. `--data-dir` tells Typesense where to persist state. `--api-key` reads from the environment variable. `--enable-cors` opens cross-origin requests for browser clients. The image exposes port 8108. For a frontend that queries Typesense directly from the browser, you need a public URL. For a backend-only integration, a private URL is sufficient and more secure. RAM sizing is the most important operational decision. Typesense is in-memory. A dataset of 10,000 small product documents with moderate synonyms fits in 512 MB. A dataset of 100,000 documents with rich merchandising rules needs 2 GB or more. Railway lets you resize RAM from the dashboard. ## How does Typesense Synonyms compare against other Search Merchandising Platforms ### Typesense Synonyms vs Algolia (Algolia Alternative) Algolia is closed-source SaaS; you cannot self-host it. Typesense is GPL-3.0 open source that runs on Railway, a VPS, or bare metal. Algolia's pricing scales with search requests and records stored. Typesense Cloud bills dedicated RAM/vCPU hourly plus bandwidth, with no per-search fee. A 0.5 GB burst node is about $21.60/month; a 2 GB burst node is about $43-$51/month. Self-hosted on Railway, a small node is typically single-digit to low-teens USD per month. Algolia has a polished dashboard; Typesense requires API-driven configuration but gives full data ownership. ### Typesense Synonyms vs Elasticsearch (Elasticsearch Alternative) Elasticsearch can do synonyms and overrides, but it is heavyweight, designed for log analytics and massive scale. Running Elasticsearch for a product catalog means managing JVM heap, shard allocation, and cluster health. Typesense is a single binary with no JVM and a much smaller memory footprint. Elasticsearch synonym changes often require reindexing; Typesense applies synonyms at query time from the collection schema, so you can update the dictionary without reindexing documents. ### Typesense Synonyms vs Meilisearch (Meilisearch Alternative) Meilisearch is another open-source instant search engine with strong developer experience. Both support synonyms and typo tolerance. Meilisearch's synonym model is simpler: pairs or groups apply bidirectionally. Typesense supports both multi-way synonyms and one-way aliases, giving merchandisers directional control. Meilisearch has a built-in admin dashboard; Typesense relies on API-driven configuration. Typesense's one-way alias feature and search overrides make it a better fit for e-commerce merchandising. ### Typesense Synonyms vs Solr (Solr Alternative) Apache Solr is mature and powerful, built on Lucene. It supports synonyms through managed files and overrides through query elevation. Solr is operationally heavy: you manage ZooKeeper for SolrCloud, XML/JSON configs, and JVM tuning. Typesense is a single Go binary with a REST API and no external coordination service. Solr synonym management often requires editing files and reloading cores. Typesense accepts synonym updates through a simple API call that takes effect immediately. ## How to use Typesense Synonyms (the OSS Instant Search)? Create a collection with a schema that includes the fields you want to search and facet. Upsert your product documents. Then define synonyms. A multi-way synonym group is `{"synonyms": ["sneakers", "trainers", "athletic shoes"]}`. A one-way alias uses `{"root": "apple iphone", "synonyms": ["iphone"]}`. Send these to the collection's synonyms endpoint with your API key. Search overrides are defined per collection with a rule object that includes the query, action (pin, hide, or boost), and document IDs or filter conditions. You can scope overrides to facet values and set time windows. ## Similar templates - [Typesense vs Meilisearch](https://railway.com/deploy/typesense-vs-meilisearch) — self-hosted Typesense vs Meilisearch - [Betterlytics](https://railway.com/deploy/betterlytics) — Betterlytics is a cookieless analytics platform GDPR-compliant. - [Finance Tracker](https://railway.com/deploy/finance-tracker-1) — Private multi-user household finance ledger with budgets and CSV import. Open this page in a browser: https://railway.com/deploy/typesense-synonyms