Hosted Chroma
Chroma Cloud, our fully managed hosted service, is in early access. Fill out the survey to jump the waitlist and get the best retrieval experience. Full access coming Q1 2025.
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:passwordbase64-encodedAuthorizationheader. - Static auth token in
Authorization: Bearer <token>or inX-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#
Security Practices
A good security practice is to store the password securely. In the example below we use bcrypt (currently the only supported hash in Chroma server side auth) to hash the plaintext password. If you'd like to see support for additional hash functions, feel free to contribute new ones!
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):
Install python-dotenv. This will allow us to read the environment variables from .chroma_env easily:
We will use Chroma's Settings object to define the authentication method on the client.
Static API Token Authentication#
Server Set-Up#
Security Note
Current implementation of static API token auth supports only ENV based tokens. Tokens must be alphanumeric ASCII strings. Tokens are case-sensitive.
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#
Install python-dotenv. This will allow us to read the environment variables from .chroma_env easily:
We will use Chroma's Settings object to define the authentication method on the client.
If you are using a custom CHROMA_AUTH_TOKEN_TRANSPORT_HEADER (like X-Chroma-Token), add it to your Settings: