Deploy XERJ Pro Stack

Deploy and Host XERJ on Railway

XERJ is an open-source search engine written in Rust for full-text retrieval, document search and agent memory. This Railway Pro Stack adds a private web console, generated API credentials and persistent storage to the official XERJ engine. Start importing and searching JSON documents without an LLM API key or GPU.

About Hosting XERJ

One Railway service runs the pinned official XERJ 1.0.0-rc.96 binary and a small authenticated ingress. The browser interface helps you import JSON documents, test a search and copy connection settings. Native REST routes under /v1 and the Elasticsearch-compatible HTTP API share the same HTTPS domain. The engine listeners stay on loopback; only the protected ingress is exposed.

This is an independent deployment template, not an official XERJ service. The pinned version is a release candidate. Test your application's API usage before relying on Elasticsearch compatibility; this template does not claim complete Elasticsearch feature parity.

What this Pro Stack adds

Quick start

1. Deploy this template. No external database or model key is required.
2. Open the generated Railway domain. Find APP_PASSWORD in your service's Railway Variables and use it on the login screen.
3. Import the example JSON documents or replace them with your own. Select the index and search for a term.
4. Copy the API key from the console, or read XERJ_API_KEY in Railway Variables. Keep it private.

Use the API

Replace the domain and key below with your own. The placeholders are not actual credentials.

curl 'https://YOUR-DOMAIN.up.railway.app/_cat/indices?format=json' \
  -H 'Authorization: ApiKey YOUR_XERJ_API_KEY'

curl 'https://YOUR-DOMAIN.up.railway.app/railway-demo/_search' \
  -H 'Authorization: ApiKey YOUR_XERJ_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"query":{"match_all":{}},"size":10}'

The console's JSON importer generates stable document IDs, so importing identical documents twice does not create duplicates. Programmatic clients can also use XERJ's normal indexing API.

Connect Claude Code, Cursor or another MCP client

Install the official XERJ CLI on the machine running your MCP client, then configure:

{
  "mcpServers": {
    "xerj": {
      "command": "xerj",
      "args": ["mcp"],
      "env": {
        "XERJ_URL": "https://YOUR-DOMAIN.up.railway.app",
        "XERJ_AUTH": "ApiKey YOUR_XERJ_API_KEY"
      }
    }
  }
}

The CLI runs the MCP stdio server locally and connects to your Railway engine. This template does not expose a separate HTTP MCP endpoint. Desktop MCP clients may require an absolute path to the installed xerj binary.

Configuration and persistence

/data/xerj contains the engine data and write-ahead log. /data/railway contains private configuration and fallback credentials. Both are on the attached /data volume. Do not delete or detach that volume when redeploying. Use one replica: this is a single-node persistent deployment, not a replicated cluster.

Railway variables take precedence over the saved fallback credentials. Changing APP_PASSWORD invalidates existing browser sessions after the service restarts. Changing XERJ_API_KEY invalidates clients using the old key. Set up Railway volume backups in your project for off-container recovery; a persistent volume alone is not a backup.

Common Use Cases

• A private searchable knowledge base for AI agents and personal tools.
• Full-text search over notes, documentation or structured JSON records.
• An Elasticsearch-style HTTP search backend for prototypes and smaller applications.
• Persistent retrieval for Claude Code, Cursor and other MCP-capable clients.

FAQ

Can I deploy XERJ on Railway without OpenAI? Yes. The included lexical search and JSON import do not need a model API key or GPU. This template does not automatically configure embedding or LLM services.

Does my data survive a restart? Indexes and configuration are stored under /data on the attached Railway volume. Restart and replacement-container persistence are checked during template validation. Volume deletion remains destructive.

Is the UI public? The domain is public, but the console requires your generated password and the APIs require valid authentication. /healthz only exposes a minimal availability status.

Why choose this XERJ Railway template? It combines a usable import/search console, generated credentials, authenticated APIs and a persistent volume in one service. It is useful when you want hosted XERJ without manually wiring those parts together.

Dependencies for XERJ Hosting

Deployment Dependencies

• Railway compute and a Railway persistent volume mounted at /data.
• Official XERJ source and release.
• Python/FastAPI ingress, included in the image.
• XERJ documentation.
• Template source code.

Why Deploy XERJ on Railway?

Railway supplies the HTTPS domain, environment variables, container deployment and persistent volume. This template supplies the private console, engine configuration and process supervision. Resource charges depend on actual usage and index size; no free hosting or benchmark result is implied.