Configuration

Compass uses a YAML config file and/or environment variables. The CLI client and server share the same file.

Prerequisites

PostgreSQL 13+ with pgvector and pg_trgm extensions

Initialize Config

compass config init

This creates ~/.config/raystack/compass.yaml. You can override the path with --config.

Server Configuration

log_level: info

db:
  host: localhost
  port: 5432
  name: compass
  user: compass
  password: compass_password
  sslmode: disable

service:
  host: 0.0.0.0
  port: 8080
  identity:
    headerkey_uuid: Compass-User-UUID
    headerkey_email: Compass-User-Email

embedding:
  enabled: false
  provider: ollama        # ollama or openai
  ollama:
    host: http://localhost:11434
    model: nomic-embed-text
  openai:
    api_key: ""           # required when provider is openai
    model: text-embedding-3-small
    base_url: https://api.openai.com
  workers: 2
  queue_size: 1000
  max_tokens: 512
  overlap: 50

Client Configuration

client:
  host: localhost:8080
  serverheaderkey_uuid: Compass-User-UUID
  serverheadervalue_uuid: user@example.com

Environment Variables

All config keys can be set as environment variables using _ as the delimiter:

export DB_HOST=localhost
export DB_PORT=5432
export DB_NAME=compass
export DB_USER=compass
export DB_PASSWORD=compass_password
export SERVICE_PORT=8080
export EMBEDDING_ENABLED=true
export EMBEDDING_PROVIDER=ollama

See Configuration Reference for the complete list.

Start the Server

compass server migrate    # Run database migrations
compass server start      # Start the server

Docker

docker-compose up -d      # Start PostgreSQL with pgvector
compass server migrate
compass server start

Or run everything in Docker:

docker run -d \
  --restart=always \
  -p 8080:8080 \
  -v $(pwd)/compass.yaml:/compass.yaml \
  raystack/compass:latest \
  server start -c /compass.yaml

Helm Chart

For Kubernetes deployments, use the Helm chart from raystack/charts:

helm repo add raystack https://raystack.github.io/charts/
helm install compass -f values.yaml raystack/compass

Reference

Generic

Key	Default	Description
`LOG_LEVEL`	`info`	`trace`, `debug`, `info`, `warning`, `error`, `fatal`, `panic`

Database

Key	Default	Required	Description
`DB_HOST`	--	Yes	PostgreSQL hostname
`DB_PORT`	`5432`	Yes	PostgreSQL port
`DB_NAME`	`postgres`	Yes	Database name
`DB_USER`	`root`	Yes	Database user
`DB_PASSWORD`	--	Yes	Database password
`DB_SSLMODE`	`disable`	No	SSL mode

Service

Key	Default	Description
`SERVICE_HOST`	`0.0.0.0`	Network interface to bind
`SERVICE_PORT`	`8080`	Listen port
`SERVICE_BASEURL`	`localhost:8080`	Base URL
`SERVICE_IDENTITY_HEADERKEY_UUID`	`Compass-User-UUID`	Identity header key
`SERVICE_IDENTITY_HEADERKEY_EMAIL`	`Compass-User-Email`	Email header key
`SERVICE_IDENTITY_PROVIDER_DEFAULT_NAME`	--	Default user provider
`SERVICE_IDENTITY_NAMESPACE_CLAIM_KEY`	`namespace_id`	JWT claim for namespace
`SERVICE_CORS_ALLOWED_ORIGINS`	`*`	Allowed CORS origins
`SERVICE_MAX_RECV_MSG_SIZE`	`33554432`	Max receive message size (bytes)
`SERVICE_MAX_SEND_MSG_SIZE`	`33554432`	Max send message size (bytes)

Embedding

Key	Default	Description
`EMBEDDING_ENABLED`	`false`	Enable embedding pipeline
`EMBEDDING_PROVIDER`	`ollama`	`ollama` or `openai`
`EMBEDDING_WORKERS`	`2`	Worker pool size
`EMBEDDING_QUEUE_SIZE`	`1000`	Embedding queue capacity
`EMBEDDING_MAX_TOKENS`	`512`	Max tokens per chunk
`EMBEDDING_OVERLAP`	`50`	Token overlap between chunks
`EMBEDDING_OLLAMA_HOST`	`http://localhost:11434`	Ollama server URL
`EMBEDDING_OLLAMA_MODEL`	`nomic-embed-text`	Ollama embedding model
`EMBEDDING_OPENAI_API_KEY`	--	OpenAI API key (required for openai provider)
`EMBEDDING_OPENAI_MODEL`	`text-embedding-3-small`	OpenAI embedding model
`EMBEDDING_OPENAI_BASE_URL`	`https://api.openai.com`	OpenAI API base URL

Telemetry

Key	Default	Description
`TELEMETRY_SERVICENAME`	`compass`	OpenTelemetry service name
`TELEMETRY_OPENTELEMETRY_ENABLED`	`false`	Enable traces and metrics
`TELEMETRY_OPENTELEMETRY_COLLECTORADDR`	--	gRPC collector address
`TELEMETRY_OPENTELEMETRY_TRACESAMPLEPROBABILITY`	`1.0`	Trace sampling rate (0.0-1.0)