Skip to main content

​
A Simple GCP Deployment

You can deploy Chroma on a long-running server, and connect to it remotely. For convenience, we have provided a very simple Terraform configuration to experiment with deploying Chroma to Google Compute Engine.

​
Step 1: Set up your GCP credentials

In your GCP project, create a service account for deploying Chroma. It will need the following roles:
  • Service Account User
  • Compute Admin
  • Compute Network Admin
  • Storage Admin
Create a JSON key file for this service account, and download it. Set the GOOGLE_APPLICATION_CREDENTIALS environment variable to the path of your JSON key file: 
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/service-account-key.json"

​
Step 2: Install Terraform

Download Terraform and follow the installation instructions for your OS.

​
Step 3: Configure your GCP Settings

Create a chroma.tfvars file. Use it to define the following variables for your GCP project ID, region, and zone: 
project_id="<your project ID>"
region="<your region>"
zone="<your zone>"

​
Step 4: Initialize and deploy with Terraform

Download our GCP Terraform configuration to the same directory as your chroma.tfvars file. Then run the following commands to deploy your Chroma stack. Initialize Terraform: 
terraform init
Plan the deployment, and review it to ensure it matches your expectations: 
terraform plan -var-file chroma.tfvars
If you did not customize our configuration, you should be deploying an e2-small instance. Finally, apply the deployment: 
terraform apply -var-file chroma.tfvars

​
Customize the Stack (optional)

If you want to use a machine type different from the default e2-small, in your chroma.tfvars add the machine_type variable and set it to your desired machine: 
machine_type = "e2-medium"
After a few minutes, you can get the IP address of your instance with 
terraform output -raw chroma_instance_ip

​
Step 5: Chroma Client Set-Up

Once your Compute Engine instance is up and running with Chroma, all you need to do is configure your HttpClient to use the server’s IP address and port 8000. Since you are running a Chroma server on Azure, our thin-client package may be enough for your application.
import chromadb

chroma_client = chromadb.HttpClient(
    host="<Your Chroma instance IP>",
    port=8000
)
chroma_client.heartbeat()

​
Step 5: Clean Up (optional).

To destroy the stack and remove all GCP resources, use the terraform destroy command. 
terraform destroy -var-file chroma.tfvars

​
Observability with GCP

Chroma is instrumented with OpenTelemetry hooks for observability. We currently only export OpenTelemetry traces. These should allow you to understand how requests flow through the system and quickly identify bottlenecks. Check out the observability docs for a full explanation of the available parameters. To enable tracing on your Chroma server, simply define the following variables in your chroma.tfvars: 
chroma_otel_collection_endpoint          = "api.honeycomb.com"
chroma_otel_service_name                 = "chromadb"
chroma_otel_collection_headers           = "{'x-honeycomb-team': 'abc'}"