Docker ↗

Documentation Index#

Fetch the complete documentation index at: https://docs.trychroma.com/llms.txt Use this file to discover all available pages before exploring further.

Run Chroma in a Docker Container

export const Callout = ({title, children}) =>

{title && <p className="block mb-2"><strong>{title}</strong></p>}
{children}

;

Chroma Cloud, our fully managed hosted service is here. Sign up for free.

Run Chroma in a Docker Container#

You can run a Chroma server in a Docker container, and access it using the HttpClient. We provide images on both docker.com and ghcr.io.

To start the server, run:

    docker run -v ./chroma-data:/data -p 8000:8000 chromadb/chroma
    ```

This starts the server with the default configuration and stores data in `./chroma-data` (in your current working directory).

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

```python
    import chromadb

    chroma_client = chromadb.HttpClient(host='localhost', port=8000)
    chroma_client.heartbeat()
    ```

<span class="callout-start" data-callout-type="note"></span>
  If you're using Python, you may want to use the [client-only package](./python-thin-client) for a smaller install size.
<span class="callout-end"></span>
  <span class="tab-end"></span>

  <span class="tab-start" data-tab-title="TypeScript"></span>
You can run a Chroma server in a Docker container, and access it using the `ChromaClient`. We provide images on both [docker.com](https://hub.docker.com/r/chromadb/chroma) and [ghcr.io](https://github.com/chroma-core/chroma/pkgs/container/chroma).

To start the server, run:

```terminal
    docker run -v ./chroma-data:/data -p 8000:8000 chromadb/chroma
    ```

This starts the server with the default configuration and stores data in `./chroma-data` (in your current working directory).

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

```typescript
    import { ChromaClient } from "chromadb";

    const chromaClient = new ChromaClient({
      host: "localhost",
      port: 8000,
    });
    chromaClient.heartbeat();
    ```
  <span class="tab-end"></span>

  <span class="tab-start" data-tab-title="Rust"></span>
You can run a Chroma server in a Docker container, and access it using the Rust `ChromaHttpClient`. We provide images on both [docker.com](https://hub.docker.com/r/chromadb/chroma) and [ghcr.io](https://github.com/chroma-core/chroma/pkgs/container/chroma).

To start the server, run:

```terminal
    docker run -v ./chroma-data:/data -p 8000:8000 chromadb/chroma
    ```

This starts the server with the default configuration and stores data in `./chroma-data` (in your current working directory).

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

```rust
    use chroma::ChromaHttpClient;

    let options = ChromaHttpClientOptions {
        endpoint: "http://localhost:8000".parse()?,
        ..Default::default()
    };
    let client = ChromaHttpClient::new(options);
    ```
  <span class="tab-end"></span>
<span class="tab-group-end"></span>

## Configuration

Chroma is configured using a YAML file. Check out [this config file](https://github.com/chroma-core/chroma/blob/main/rust/frontend/sample_configs/single_node_full.yaml) detailing all available options.

To use a custom config file, mount it into the container at `/config.yaml` like so:

```terminal
echo "allow_reset: true" > config.yaml # the server will now allow clients to reset its state
docker run -v ./chroma-data:/data -v ./config.yaml:/config.yaml -p 8000:8000 chromadb/chroma

Observability with Docker#

Chroma is instrumented with OpenTelemetry hooks for observability. OpenTelemetry traces 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.

Here’s an example of how to create an observability stack with Docker Compose. The stack is composed of

• a Chroma server
• OpenTelemetry Collector
• Zipkin

First, paste the following into a new file called otel-collector-config.yaml:

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

exporters:
  debug:
  zipkin:
    endpoint: "http://zipkin:9411/api/v2/spans"

service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [zipkin, debug]

This is the configuration file for the OpenTelemetry Collector:

• The receivers 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 below 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.

Next, paste the following into a new file called docker-compose.yml:

services:
  zipkin:
    image: openzipkin/zipkin
    ports:
      - "9411:9411"
    depends_on: [otel-collector]
    networks:
      - internal
  otel-collector:
    image: otel/opentelemetry-collector-contrib:0.111.0
    command: ["--config=/etc/otel-collector-config.yaml"]
    volumes:
      - ${PWD}/otel-collector-config.yaml:/etc/otel-collector-config.yaml
    networks:
      - internal
  server:
    image: chromadb/chroma
    volumes:
      - chroma_data:/data
    ports:
      - "8000:8000"
    networks:
      - internal
    environment:
      - CHROMA_OPEN_TELEMETRY__ENDPOINT=http://otel-collector:4317/
      - CHROMA_OPEN_TELEMETRY__SERVICE_NAME=chroma
    depends_on:
      - otel-collector
      - zipkin

networks:
  internal:

volumes:
  chroma_data:

To start the stack, run

docker compose up --build -d

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

Zipkin will show an empty view initially as no traces are created during startup. You can call the heartbeat endpoint to quickly create a sample trace:

curl http://localhost:8000/api/v2/heartbeat

Then, click “Run Query” in Zipkin to see the trace.