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 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 or pysonic.

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

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

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 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).