---
title: "Deploy Chroma"
description: "Open-source vector database with persistent volume, private-only by default"
category: "Storage"
url: https://railway.com/deploy/chroma-1
---

# Deploy Chroma

Open-source vector database with persistent volume, private-only by default

**[Deploy Chroma on Railway](https://railway.com/template/chroma-1)**

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

- **Creator:** Protemplate
- **Category:** Storage
- **Total deploys:** 2

## Template content

### Chroma https://avatars.githubusercontent.com/u/105881770?v=4

- **Image:** chromadb/chroma:1.5.9
- **Health check:** /api/v2/heartbeat

## Documentation

# 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](https://docs.trychroma.com/guides/deploy/docker)
- [Chroma server configuration reference](https://docs.trychroma.com/reference/server-env-vars)
- [Chroma Docker image](https://hub.docker.com/r/chromadb/chroma)
- [Chroma GitHub repository](https://github.com/chroma-core/chroma)

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

```env
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`):

```python
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`):

```ts
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**

| Variable | Default | Purpose |
|----------|---------|---------|
| `PORT` / `CHROMA_PORT` | `8000` | Listen port; both must match |
| `CHROMA_LISTEN_ADDRESS` | `::` | IPv6 dual-stack bind for private networking |
| `CHROMA_PERSIST_PATH` | `/data` | Volume-backed data directory |
| `CHROMA_ALLOW_RESET` | `false` | Enables `POST /api/v2/reset` when `true` |

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


## Similar templates

- [Garage S3 Storage](https://railway.com/deploy/garage-s3-storage) — Ultra-light S3 server: fast, open-source, plug-and-play.
- [Redis](https://railway.com/deploy/redis-1) — Self Host Latest Redis with Railway
- [EasyImg](https://railway.com/deploy/easyimg) — Simple self-hostable Nuxt.js personal image hosting system.

Open this page in a browser: https://railway.com/deploy/chroma-1