How to Deploy ChromaDB in Client-Server Mode

What this does

ChromaDB's client-server mode runs the database as a separate HTTP service, allowing multiple clients to connect simultaneously. This guide covers starting the server via Docker, connecting from Python clients, configuring authentication, and handling network access securely.

Steps

1. Start the ChromaDB server container.

   docker run -d \
     --name chroma-server \
     -p 8000:8000 \
     -v /opt/chromadb/server_data:/data \
     chromadb/chroma:latest
   

   Expected output: Container ID printed, container running.

2. Verify the server is responding.

   curl http://localhost:8000/api/v1/heartbeat
   # Expected: {"success": true}
   

3. Install the ChromaDB client package on the client machine.

   pip install chromadb
   

4. Connect from Python using the HTTP client.

   import chromadb
   
   client = chromadb.HttpClient(host="http://localhost:8000")
   col = client.get_or_create_collection(name="server_docs")
   col.add(
       ids=["srv-1"],
       documents=["Data served over HTTP from the ChromaDB server."],
       metadatas=[{"deployed": "docker"}]
   )
   print("Server collection count:", col.count())
   

5. Query the remote collection.

   results = col.query(query_texts=["ChromaDB server deployment"], n_results=1)
   print(results["documents"][0][0] if results["documents"][0] else "No results")
   

6. Stop and remove the container gracefully.

   docker stop chroma-server && docker rm chroma-server
   

Verification

curl http://localhost:8000/api/v1/collections
# Expected: {"ids": ["server_docs"], ...}

Common failures

• Server not binding to correct port. If the container exits immediately, check logs with docker logs chroma-server. Port 8000 may already be in use - try -p 8001:8000 and update the client host accordingly.
• Connection refused from remote client. By default, Docker containers bind to localhost. Pass --host 0.0.0.0 or use -p 0.0.0.0:8000:8000 to allow external connections.
• Firewall blocking port 8000. On cloud instances, open the port with sudo ufw allow 8000 or equivalent cloud security group rules.
• Docker volume permissions. If the host directory is owned by root, the container may fail to write. Change ownership with sudo chown -R 10001:10001 /opt/chromadb/server_data.
• Client and server version mismatch. Using a newer Python client against an older server can cause API incompatibility. Pin both to the same release version (e.g., 0.5.x) to avoid unexpected errors.
• Version mismatch - The installed package or runtime differs from the command shown; check the version first and rerun the smallest verification command.
• Local environment drift - Another service, virtual environment, model, or path is being used; print the active binary path and configuration before changing the guide steps.

Related guides

• enable-chromadb-persistence-production
• setup-chromadb-scratch