---
title: "Deploy Knowhere"
description: "Self-hosted document parsing and agentic RAG ingestion API"
category: "AI/ML"
url: https://railway.com/deploy/knowhere
---

# Deploy Knowhere

Self-hosted document parsing and agentic RAG ingestion API

**[Deploy Knowhere on Railway](https://railway.com/template/knowhere)**

Machine-readable deploy manifest (JSON, validated by TemplateCI): https://railway.com/deploy/knowhere/manifest.json

- **Creator:** My Projects
- **Category:** AI/ML

## Template content

### Gateway https://raw.githubusercontent.com/caddyserver/website/master/src/resources/images/favicon.png

- **Image:** caddy:2.10-alpine
- **Start command:** `sh -c 'export BASIC_AUTH_HASH="$(caddy hash-password --plaintext "$BASIC_AUTH_PASSWORD")" && printf "%s\n" "$CADDYFILE" > /etc/caddy/Caddyfile && exec caddy run --config /etc/caddy/Caddyfile --adapter caddyfile'`
- **Health check:** /gateway_health
- **Public domain:** Yes

### Postgres https://devicons.railway.app/i/postgresql.svg

- **Image:** ghcr.io/railwayapp-templates/postgres-ssl:18

### Knowhere https://raw.githubusercontent.com/Ontos-AI/knowhere-dashboard/main/public/assets/knowhere-favicon.svg

- **Image:** ghcr.io/ontos-ai/knowhere:latest
- **Start command:** `/usr/bin/tini -- /usr/local/bin/knowhere-self-hosted-entrypoint`
- **Health check:** /login

### Redis https://cdn.sanity.io/images/sy1jschh/production/0ce0bfdcfbdbf69662b1116671f97c2dd788b655-157x157.svg

- **Image:** redis:8.2
- **Start command:** `/bin/sh -c "rm -rf $RAILWAY_VOLUME_MOUNT_PATH/lost+found/ && exec docker-entrypoint.sh redis-server --requirepass $REDIS_PASSWORD --save 60 1 --dir $RAILWAY_VOLUME_MOUNT_PATH"`

## Buckets

- **knowhere-storage**

## Documentation

# Deploy and Host Knowhere on Railway

[Knowhere](https://github.com/Ontos-AI/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](https://github.com/Ontos-AI/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:**

1. 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.
2. 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.
3. 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`.
4. 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](https://github.com/Ontos-AI/knowhere) (Apache-2.0) and [Ontos-AI/knowhere-self-hosted](https://github.com/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

- [DeepSeek API keys](https://platform.deepseek.com/)
- [MinerU API keys](https://mineru.net/)
- [Alibaba Cloud Model Studio (DashScope)](https://bailian.console.aliyun.com/)
- [Vercel AI Gateway](https://vercel.com/ai-gateway)
- [Knowhere Python SDK](https://github.com/Ontos-AI/knowhere-python-sdk) and [Node.js SDK](https://github.com/Ontos-AI/knowhere-node-sdk)

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

## Similar templates

- [Chat Chat](https://railway.com/deploy/-WWW5r) — Chat Chat, your own unified chat and search to AI platform.
- [Weaviate](https://railway.com/deploy/weaviate-1) — Vector database with hybrid search and an API key-protected API
- [Möbius Personal AI OS](https://railway.com/deploy/mobius-v01-personal-ai-os) — Self-hosted AI agent that builds and runs apps for you, with memory.

Open this page in a browser: https://railway.com/deploy/knowhere