Run Chroma in a Docker Container#

You can run a Chroma server in a Docker container, and access it using the HttpClient.

If you are using Chroma in production, please fill out this form, and we will add you to a dedicated Slack workspace for supporting production users. We would love to help you think through the design of your system, or if you would be a good fit for our upcoming distributed cloud service.

If you are using a client in a separate container from the one running your Chroma server, you may only need the thin-client package

You can get the Chroma Docker image from Docker Hub, or from the Chroma GitHub Container Registry

You can also build the Docker image yourself from the Dockerfile in the Chroma GitHub repository

The Chroma client can then be configured to connect to the server running in the Docker container.

Authentication with Docker#

By default, the Docker image will run with no authentication. In client/server mode, Chroma supports the following authentication methods:

• RFC 7617 Basic Auth with user:password base64-encoded Authorization header.
• Static auth token in Authorization: Bearer <token> or in X-Chroma-Token: <token> headers.

You can learn more about authentication with Chroma in the Auth Guide.

Encrypted User:Password Authentication#

Server Set-Up#

Generate Server-Side Credentials#

To generate the password hash, run the following command:

This creates the bcrypt password hash for the password admin, for the admin user, and puts it into server.htpasswd in your current working directory. It will look like admin:<password hash>.

Running the Server#

Create a .chroma_env file, and set in it the following environment variables:

Then, run the Chroma container, and pass it your .chroma_env using the --env-file flag:

Client Set-Up#

In your client environment, set the CHROMA_CLIENT_AUTH_CREDENTIALS variable to the user:password combination (admin:admin in this example):

Static API Token Authentication#

Server Set-Up#

If, for example, you want the static API token to be "test-token", add the following environment variables to your .chroma_env. This will set Authorization: Bearer test-token as your authentication header.

If instead of the default Authorization: Bearer <token> header, you want to use a custom one like X-Chroma-Token: test-token, you can set the CHROMA_AUTH_TOKEN_TRANSPORT_HEADER environment variable:

Then, run the Chroma server:

To configure multiple tokens and use them for role-based access control (RBAC), use a file like this and the following environment variables:

In this case, you will have to set up a volume to allow the Chroma Docker container to use your authz.yaml file:

Client Set-Up#

Observability with Docker#

Chroma is instrumented with OpenTelemetry hooks for observability. We currently only exports OpenTelemetry traces. These should allow you to understand how requests flow through the system and quickly identify bottlenecks.

Tracing is configured with four environment variables:

• CHROMA_OTEL_COLLECTION_ENDPOINT: where to send observability data. Example: api.honeycomb.com.
• CHROMA_OTEL_SERVICE_NAME: Service name for OTel traces. Default: chromadb.
• CHROMA_OTEL_COLLECTION_HEADERS: Headers to use when sending observability data. Often used to send API and app keys. For example {"x-honeycomb-team": "abc"}.
• CHROMA_OTEL_GRANULARITY: A value from the OpenTelemetryGranularity enum. Specifies how detailed tracing should be.

Here is an example of how to create an observability stack with Docker-Compose. The stack is composed of a Chroma server, an OpenTelemetry Collector, and Zipkin.

Set the values for the observability and authentication environment variables to suit your needs.

Create the following otel-collector-config.yaml:

This is the configuration file for the OpenTelemetry Collector:

• The recievers section specifies that the OpenTelemetry protocol (OTLP) will be used to receive data over GRPC and HTTP.
• exporters defines that telemetry data is logged to the console (debug), and sent to a zipkin server (defined bellow in docker-compose.yml).
• The service section ties everything together, defining a traces pipeline receiving data through our otlp receiver and exporting data to zipkin and via logging.

Create the following docker-compose.yml:

To start the stack, run from the root of the repo:

Once the stack is running, you can access Zipkin at http://localhost:9411 when running locally to see your traces.