curated_compose/docker/chroma/compose.yaml

name: chroma

services:
    # ===========================================================================
    # Chroma Server (vector database)
    # ===========================================================================
    # Chroma is the open-source embedding database. It provides a REST API for
    # storing and querying vector embeddings with metadata filtering, full-text
    # search, and hybrid search capabilities.
    #
    # VoyageAI integration: The Chroma SERVER does not need VOYAGE_API_KEY.
    # VoyageAI embeddings are configured on the CLIENT side when creating
    # collections and adding documents. Set VOYAGE_API_KEY in the environment
    # where client tools run (e.g., the agent host, not this container).
    #
    # Docs: https://docs.trychroma.com
    # ===========================================================================
    chroma:
        image: ghcr.io/chroma-core/chroma:${CHROMA_VERSION:-latest}
        restart: unless-stopped
        volumes:
            - ./data:/chroma/chroma/
        environment:
            # Persistence — hardcoded to prevent accidental data loss from .env overrides
            IS_PERSISTENT: TRUE
            PERSIST_DIRECTORY: /chroma/chroma/

            # Server
            CHROMA_SERVER_CORS_ALLOW_ORIGINS: ${CHROMA_SERVER_CORS_ALLOW_ORIGINS:-}
            CHROMA_SERVER_THREAD_POOL_SIZE: ${CHROMA_SERVER_THREAD_POOL_SIZE:-40}
            CHROMA_SERVER_HTTP_PORT: ${CHROMA_SERVER_HTTP_PORT:-8000}
            # WARNING: setting ALLOW_RESET=true in .env will wipe all data on restart
            ALLOW_RESET: false

            # Authentication
            CHROMA_SERVER_AUTHN_PROVIDER: ${CHROMA_SERVER_AUTHN_PROVIDER:-}
            CHROMA_SERVER_AUTHN_CREDENTIALS: ${CHROMA_SERVER_AUTHN_CREDENTIALS:-}
            CHROMA_SERVER_AUTHZ_PROVIDER: ${CHROMA_SERVER_AUTHZ_PROVIDER:-}
            CHROMA_SERVER_AUTHZ_CONFIG: ${CHROMA_SERVER_AUTHZ_CONFIG:-}
            CHROMA_AUTH_TOKEN_TRANSPORT_HEADER: ${CHROMA_AUTH_TOKEN_TRANSPORT_HEADER:-}

            # Telemetry
            ANONYMIZED_TELEMETRY: ${ANONYMIZED_TELEMETRY:-false}
            CHROMA_OPEN_TELEMETRY__ENDPOINT: ${CHROMA_OPEN_TELEMETRY__ENDPOINT:-http://lgtm:4318}
            CHROMA_OPEN_TELEMETRY__SERVICE_NAME: ${CHROMA_OPEN_TELEMETRY__SERVICE_NAME:-chromadb}
            OTEL_EXPORTER_OTLP_HEADERS: ${OTEL_EXPORTER_OTLP_HEADERS:-}

            # Migrations
            MIGRATIONS: ${MIGRATIONS:-apply}

            # Memory / Performance — sensible default for homelab (~1 GB)
            # Set to 0 for unlimited (Docker memory limit still applies)
            CHROMA_MEMORY_LIMIT_BYTES: ${CHROMA_MEMORY_LIMIT_BYTES:-1073741824}
        ports:
            - "${CHROMA_PORT:-8000}:8000"
        # healthcheck:
        #     test:
        #         [
        #             "CMD",
        #             "python",
        #             "-c",
        #             "import sys, urllib.request; r = urllib.request.urlopen('http://localhost:8000/api/v2/heartbeat'); sys.exit(0 if r.status == 200 else 1)",
        #         ]
        #     interval: 30s
        #     timeout: 10s
        #     retries: 3
        #     start_period: 15s
        deploy:
            resources:
                limits:
                    memory: 8G
                    cpus: "4"
                reservations:
                    memory: 2G
                    cpus: "1"
        networks:
            chroma:
                aliases:
                    - chroma
            pipeline:
                aliases:
                    - chroma

networks:
    chroma:
        name: chroma
        driver: bridge
    pipeline:
        name: pipeline
        external: true
    # swag:
    #     name: swag
    #     external: true

# Data is persisted via bind mount at ./data/ on the host filesystem.
# This survives docker compose down -v and container recreation.
volumes: {}