Deploy Chroma

Deploy and Host Chroma on Railway

Chroma is the open-source, AI-native vector database. It stores embeddings alongside documents and metadata and serves fast similarity search, full-text search, and metadata filtering over a simple HTTP API with first-class Python and JavaScript clients. Chroma is the retrieval layer behind RAG pipelines, semantic search, and AI agent memory.

About Hosting Chroma

Hosting Chroma means running a stateful server that keeps its SQLite metadata database and HNSW index files on persistent disk. This template wraps the official chromadb/chroma:1.5.9 image (the Rust server) so it runs cleanly on Railway: it pins the listen port to Railway's PORT, binds IPv6 dual-stack so your other Railway services can reach it over private networking, mounts a persistent volume at /data so collections survive redeploys, and uses /api/v2/heartbeat for health checks. Chroma 1.x has no built-in authentication, so this template ships private-only (no public domain): your other Railway services reach it at chroma.railway.internal:8000. Chroma is self-contained: no external database, cache, or GPU is required.

Common Use Cases

• RAG pipelines: store document chunks with embeddings and retrieve the most relevant context for an LLM
• Semantic search: natural-language search over docs, tickets, product catalogs, and knowledge bases
• AI agent memory: persist conversation history and tool results as searchable vectors
• Recommendations and deduplication: nearest-neighbor lookups over items, users, or records
• Hybrid search: combine vector similarity with metadata filters and full-text search in one query

Dependencies for Chroma Hosting

• Persistent volume: stores chroma.sqlite3 and index files at /data (provisioned by this template)
• Embedding model (your app side): the Chroma clients can embed locally by default, or you supply vectors from OpenAI, Cohere, or another provider
• No external database required: Chroma single-node is fully self-contained

Deployment Dependencies

• Chroma Docker deployment guide
• Chroma server configuration reference
• Chroma Docker image
• Chroma GitHub repository

Implementation Details

The image starts chroma run /config.yaml, and Chroma overlays any CHROMA_* environment variable onto that config, so no custom start command is needed. This template sets:

PORT=8000
CHROMA_PORT=8000
CHROMA_LISTEN_ADDRESS=::
CHROMA_PERSIST_PATH=/data
CHROMA_ALLOW_RESET=false

PORT and CHROMA_PORT must stay equal because Railway's healthcheck probes $PORT. CHROMA_LISTEN_ADDRESS=:: replaces the upstream 0.0.0.0 default, which is IPv4-only and unreachable from *.railway.internal.

First steps after deploy

1. The service has no public domain by design. From any service in the same Railway project, connect over private networking with Python (pip install chromadb-client):

import chromadb

client = chromadb.HttpClient(host="chroma.railway.internal", port=8000)
client.heartbeat()
collection = client.get_or_create_collection("docs")
collection.add(ids=["1", "2"], documents=["Railway hosts infrastructure", "Chroma stores embeddings"])
print(collection.query(query_texts=["where do embeddings live?"], n_results=1))

Or JavaScript (npm install chromadb):

import { ChromaClient } from "chromadb";

const client = new ChromaClient({ host: "chroma.railway.internal", port: 8000, ssl: false });
const collection = await client.getOrCreateCollection({ name: "docs" });
await collection.add({ ids: ["1"], documents: ["hello from railway"] });

2. Use ${{Chroma.RAILWAY_PRIVATE_DOMAIN}} in your app's variables so the hostname follows the service.
3. Need access from outside Railway? Generate a domain under Settings, Networking (target port 8000) and put an authenticating proxy in front of it. Anyone who can reach the port can read and write every collection.

Key environment variables

Why Deploy Chroma 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 Chroma on Railway, you get a pre-configured vector database with a persistent volume, automatic health checks, managed SSL, and private networking to your application services. Host your servers, databases, AI agents, and more on Railway.