SSL/TLS Certificates in Chroma

Chroma uses uvicorn as an ASGI server, which can be configured to use SSL/TLS certificates.

CLI not supported

Using certificates with Chroma CLI is not yet supported.

Performance Impact

Using certificates within Chroma will have a performance impact as uvicorn will need to hnadle the encryption and decryption of the data. If performance is of concern, consider using a reverse proxy like nginx or envoy to handle the SSL/TLS termination.

Self-Signed Certificates

Creating a self-signed certificate

You will also need to create a openssl.cnf file in the same directory with the following content:

```ini
[req]
distinguished_name = req_distinguished_name
x509_extensions = usr_cert
[req_distinguished_name]
CN = $ENV::CHROMA_DOMAIN
[usr_cert]
subjectAltName = DNS:$ENV::CHROMA_DOMAIN
```

Certificate Domain - CHROMA_DOMAIN

You can set the CHROMA_DOMAIN environment variable to the domain you want to use for the certificate.

OpenSSLDocker

To run the following you will need to have openssl installed on your system.

export CHROMA_DOMAIN=${CHROMA_DOMAIN:-"localhost"}
openssl req -new -newkey rsa:2048 -sha256 -days 365 -nodes -x509 \
  -keyout certs/serverkey.pem \
  -subj '/O=Chroma/C=US' \
  -out certs/servercert.pem \
  -config openssl.cnf

This will create a self-signed certificate and key in the certs directory.

If you are using Docker, you can use the following command to generate the certificates:

docker run --rm -v $(pwd)/certs:/certs \
  -v $(pwd)/openssl.cnf:/etc/ssl/openssl.cnf \
  -e CHROMA_DOMAIN=localhost \
  openquantumsafe/openssl3 \
  openssl req -new -newkey rsa:2048 -sha256 -days 365 -nodes -x509 \
  -keyout /certs/serverkey.pem \
  -subj '/O=Chroma/C=US' \
  -out /certs/servercert.pem \
  -config /etc/ssl/openssl.cnf

Security Warning

Self-signed certificates are not recommended for production use. They are only suitable for testing and development purposes. Additionally in the above example the keyfile is not password protected, which is also not recommended for production use.

Configuring and running Chroma

You can run Chroma with the SSL/TLS certificate generate above or any other certificate you have.

DockerDocker Compose

To run Chroma with the self-signed certificate, you can use the following command:

docker run --rm -it -p 8000:8000 \
  -v $(pwd)/certs:/chroma/certs \
  chromadb/chroma:0.5.0 \
  --workers 1 \
  --host 0.0.0.0 \
  --port 8000 \
  --proxy-headers \
  --log-config chromadb/log_config.yml \
  --timeout-keep-alive 30 \
  --ssl-keyfile /chroma/certs/serverkey.pem \
  --ssl-certfile /chroma/certs/servercert.pem

To run Chroma with the self-signed certificate using Docker Compose, you can use the following docker-compose.yml file:

version: '3.9'
networks:
  net:
    driver: bridge
services:
  server:
    image: chromadb/chroma:0.5.0
    volumes:
      # Be aware that indexed data are located in "/chroma/chroma/"
      # Default configuration for persist_directory in chromadb/config.py
      # Read more about deployments: https://docs.trychroma.com/deployment
      - chroma-data:/chroma/chroma
    command: "--workers 1 --host 0.0.0.0 --port 8000 --proxy-headers --log-config chromadb/log_config.yml --timeout-keep-alive 30 --ssl-keyfile /chroma/certs/serverkey.pem --ssl-certfile /chroma/certs/servercert.pem"
    environment:
      - IS_PERSISTENT=TRUE
      - CHROMA_SERVER_AUTHN_PROVIDER=${CHROMA_SERVER_AUTHN_PROVIDER}
      - CHROMA_SERVER_AUTHN_CREDENTIALS_FILE=${CHROMA_SERVER_AUTHN_CREDENTIALS_FILE}
      - CHROMA_SERVER_AUTHN_CREDENTIALS=${CHROMA_SERVER_AUTHN_CREDENTIALS}
      - CHROMA_AUTH_TOKEN_TRANSPORT_HEADER=${CHROMA_AUTH_TOKEN_TRANSPORT_HEADER}
      - PERSIST_DIRECTORY=${PERSIST_DIRECTORY:-/chroma/chroma}
      - CHROMA_OTEL_EXPORTER_ENDPOINT=${CHROMA_OTEL_EXPORTER_ENDPOINT}
      - CHROMA_OTEL_EXPORTER_HEADERS=${CHROMA_OTEL_EXPORTER_HEADERS}
      - CHROMA_OTEL_SERVICE_NAME=${CHROMA_OTEL_SERVICE_NAME}
      - CHROMA_OTEL_GRANULARITY=${CHROMA_OTEL_GRANULARITY}
      - CHROMA_SERVER_NOFILE=${CHROMA_SERVER_NOFILE}
    restart: unless-stopped
    ports:
      - "8000:8000"
    healthcheck:
      # Adjust below to match your container port
      test: [ "CMD", "curl", "-f", "http://localhost:8000/api/v1/heartbeat" ]
      interval: 30s
      timeout: 10s
      retries: 3
    networks:
      - net
volumes:
  chroma-data:
    driver: local

Using a Certificate Authority

Examples below will demonstrate how to use certbot to generate a certificate with a given certificate authority.

Let’s Encrypt

Coming soon!

AWS Certificate Manager

Coming soon!

June 26, 2024