---
title: "Deploy Sonic"
description: "Indexes search text and object identifiers, Elasticsearch alternative"
category: "Automation"
url: https://railway.com/deploy/sonic-1
---

# Deploy Sonic

Indexes search text and object identifiers, Elasticsearch alternative

**[Deploy Sonic on Railway](https://railway.com/template/sonic-1)**

- **Creator:** feliperosenek
- **Category:** Automation

## Template content

### sonic https://www.svgrepo.com/show/396635/hedgehog.svg

- **Source:** https://github.com/feliperosenek/sonic-railway

## Documentation

# Deploy and Host Sonic on Railway

Deploy this repository as a Sonic search backend on Railway. Sonic indexes search text and object identifiers over the Sonic Channel protocol (TCP port 1491). Your application pushes data with `PUSH` and queries with `QUERY` — Sonic returns IDs that you resolve in your own database.

## About Hosting

This template runs the official [Sonic](https://github.com/valeriansaliou/sonic) Docker image with a Railway-ready configuration: listens on `0.0.0.0:1491`, stores the index on a persistent volume, and requires an authentication password for all channel connections.

Sonic is **not** an HTTP API. Connect via **TCP** (Railway TCP Proxy or private networking). Use client libraries such as [node-sonic-channel](https://www.npmjs.com/package/sonic-channel) or [pysonic](https://github.com/AlongWY/pysonic).

Each TCP connection uses **one channel mode** — you cannot switch modes mid-session:

| Mode | Commands |
|------|----------|
| `ingest` | `PUSH`, `POP`, `COUNT`, `FLUSHO`, `FLUSHB`, `FLUSHC` |
| `search` | `QUERY`, `SUGGEST`, `LIST`, `PING`, `HELP` |
| `control` | `TRIGGER consolidate`, `INFO`, `PING` |

**Networking:** services inside Railway connect to `${{sonic.RAILWAY_PRIVATE_DOMAIN}}:1491`. External clients use the **TCP Proxy** host and port from Railway settings — the public proxy port is often **not** 1491 (Railway maps it to the internal 1491).

## Why Deploy

- **Lightweight search** — Alternative to Elasticsearch/Meilisearch for ID-based full-text search with minimal RAM (~30MB under load).
- **Fast lookups** — Microsecond-range queries on SSD-backed storage.
- **Simple protocol** — Push text + object ID, query terms, get IDs back.
- **Multi-language** — 80+ languages with stop-word handling.

## Common Use Cases

- Helpdesk or documentation search (Crisp uses Sonic in production)
- In-app search where full documents live in Postgres/API
- Autocomplete (`SUGGEST`) on user input
- Low-cost search index for side projects and staging

## Dependencies for

This template provides a **search index service**. Your web app or API depends on it for `PUSH` (ingest) and `QUERY` (search) over Sonic Channel.

### Deployment Dependencies

- **SONIC_AUTH_PASSWORD** (required) — Password for `START ingest|search|control`. Use `${{secret(32)}}` in the template so Railway generates a random password on first deploy.
- **Volume** — Mount a volume at **`/var/lib/sonic/store`** so index data survives redeploys. Without it, indexed data is lost on restart.
- **TCP Proxy** (optional) — Enable Railway TCP Proxy on port **1491** to connect from outside Railway. Other services in the same project can use `${{sonic.RAILWAY_PRIVATE_DOMAIN}}:1491` over private networking.

### Connecting from Your App

| Variable in your app | Railway reference |
|----------------------|-------------------|
| Sonic host | `${{sonic.RAILWAY_PRIVATE_DOMAIN}}` or TCP proxy host |
| Sonic port | `1491` (private) or TCP proxy port (public) |
| Sonic password | `${{sonic.SONIC_AUTH_PASSWORD}}` |

**Ingest example:**

```
START ingest 
PUSH articles default article:42 "Title and body text to index"
QUIT
```

**Consolidate index (required before new data appears in search):**

After `PUSH`, `POP`, or `FLUSH*`, run consolidate in **control** mode — or wait for the automatic cycle (~180s):

```
START control 
TRIGGER consolidate
QUIT
```

**Search example:**

```
START search 
QUERY articles default "search terms" LIMIT(10)
QUIT
```

**Smoke test after deploy:** `PING` → `PONG`, then `PUSH` a test document, `TRIGGER consolidate`, and `QUERY` the indexed term.

See [PROTOCOL.md](https://github.com/valeriansaliou/sonic/blob/master/PROTOCOL.md) for the full Sonic Channel specification.

## Limitations

- No built-in web UI — integrate from your application code.
- TCP only — not compatible with HTTP health checks; use `PING` over a TCP connection instead.
- Index stores **IDs**, not full documents — enrich results from your database.
- **Consolidation delay** — `QUERY` does not see freshly pushed data until consolidate runs.
- **`POP` requires the exact indexed text** and returns `RESULT N` (tokens removed), not `OK`.
- **`FLUSHO` / `FLUSHB` / `FLUSHC`** remove an object, bucket, or entire collection — use with care.
- SSD-backed volumes recommended for search performance.

## Version

Built from `valeriansaliou/sonic` (default tag `v1.5.1`, overridable via `SONIC_VERSION` build arg).


## Similar templates

- [N8N Main + Worker](https://railway.com/deploy/n8n-main-worker) — Deploy and Host N8N with Inactive worker.
- [Evolution API with n8n](https://railway.com/deploy/evolution-api-with-n8n) — Automate WhatsApp workflows with Evolution API, n8n, and Postgres.
- [Postgres Backup](https://railway.com/deploy/postgres-s3-backups) — Cron-based PostgreSQL backup to bucket storage

Open this page in a browser: https://railway.com/deploy/sonic-1