Deploy and Host Knowhere on Railway

Knowhere is an open-source document parsing and agentic RAG ingestion engine by Ontos AI. It turns PDFs, Office files, spreadsheets, images, audio and video into structured, retrieval-ready chunks, and serves them to AI agents through a REST API, official Node.js and Python SDKs, and an MCP endpoint. This template runs the official self-hosted package from Knowhere Self-Hosted.

About Hosting Knowhere

This template runs the official ghcr.io/ontos-ai/knowhere image (API, Celery worker and dashboard in one container) behind a small Caddy gateway that adds authentication.

Knowhere: API (port 5005), parsing worker and Next.js dashboard (port 3000). Private only, no public domain.
Gateway: Caddy reverse proxy, the only public service. The dashboard is protected by HTTP basic auth; the REST API (/v1, /v2) and MCP endpoint (/mcp) are reachable with Knowhere API keys only. The unauthenticated guest-registration and internal storage-event routes are blocked.
Postgres and Redis: Railway's official database templates (accounts, jobs, Celery broker).
Storage bucket: a Railway S3-compatible bucket for uploads and parsing results. Bucket CORS is configured automatically on every deploy.
Volume at /data on the Knowhere service: user data and the model cache.
Generated secrets: gateway password, SECRET_KEY, BETTER_AUTH_SECRET, token secrets and the storage webhook token.

After deploy:

Open the Gateway service, copy BASIC_AUTH_PASSWORD from its Variables tab, then open the Gateway public URL and log in as admin with that password.
Create your Knowhere account on the sign-up page. Anyone who knows the gateway password can create an account, so share it only with your team.
Create an API key in the dashboard and point an SDK at https://YOUR-RAILWAY-DOMAIN (the Gateway URL). The API health check is https://YOUR-RAILWAY-DOMAIN/health.
Model keys live on the Knowhere service: DS_KEY (DeepSeek, used for text, hierarchy and agent retrieval), MINERU_API_KEYS (needed to parse PDFs), and optionally VERCEL_KEY (page-image embeddings) or ALI_API_KEYS (DashScope, also needed for audio/video transcription). Markdown, text and HTML parse without MinerU.

Common Use Cases

Ingest company documents (PDF, DOCX, PPTX, XLSX) into structured chunks for a RAG pipeline
Give AI agents retrieval over a private document corpus via the API or the MCP endpoint
Batch-parse reports and manuals into Markdown with heading hierarchy and tables preserved
Transcribe and index audio and video files alongside documents

Dependencies for Knowhere Hosting

Source: Ontos-AI/knowhere (Apache-2.0) and Ontos-AI/knowhere-self-hosted
Image: ghcr.io/ontos-ai/knowhere:latest, gateway caddy:2.10-alpine
Optional: a DeepSeek API key (DS_KEY) for LLM enrichment; parsing runs without it. Recommended: a MinerU API key for PDF parsing.

Deployment Dependencies

Implementation Details

LocalStack from the upstream compose file is replaced by a Railway bucket. Railway buckets have no S3 event notifications, so the SNS upload-event bootstrap is disabled; the dashboard and SDKs already call the confirm-upload endpoint after uploading, which starts processing.
The bucket is shared by uploads (uploads/) and results (results/) prefixes. A pre-deploy command reuses the image's own storage script to set bucket CORS for the gateway URL, so browser uploads work.
Knowhere's sign-up page is open to anyone, so the dashboard sits behind gateway basic auth; the API keeps its own API-key authentication.
Parsing is CPU and memory heavy (LibreOffice, PyMuPDF, ffmpeg and a gevent worker in one container). Idle usage is about 1 GB RAM; plan for at least 2 vCPU and 4 GB RAM for real workloads.
Anonymous product telemetry is turned off (TELEMETRY_ENABLED=false).

Why Deploy Knowhere on Railway?

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