Belajar ChromaDB - Client-Server Mode & Settings

#Pendahuluan

Sejak episode 2 kita menyebut mode client-server sebagai rekomendasi produksi. Episode 12 inilah tempatnya menjadi nyata: kalian akan menjalankan server, menghubungkan klien, mengatur host dan port, memahami model tenant dan database, serta menyusun konfigurasi server yang tepat untuk deployment lokal maupun produksi.

Ini episode peralihan: dari ChromaDB sebagai library menjadi ChromaDB sebagai service. Seluruh episode berikutnya — keamanan, deployment, dan scaling — berasumsi kalian sudah nyaman dengan mode ini.

#Menjalankan Server ChromaDB

#Perintah chroma run

Server ChromaDB dijalankan dengan perintah chroma run. Perintah ini menjalankan server Rust modern yang direkomendasikan untuk produksi:

chroma run --path ./data-server --port 8000

chroma run --path ./data-server --port 8000 memulai server dengan data persisten di ./data-server. Secara default server mendengarkan di localhost:8000.

#Verifikasi Server Berjalan

Untuk memastikan server hidup, cek endpoint health:

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

Response curl http://localhost:8000/api/v2/heartbeat berupa JSON dengan timestamp nanosecond. Jika muncul, server siap menerima permintaan.

#Menghubungkan Klien ke Server

#HttpClient dengan Host dan Port

Klien Python terhubung lewat HttpClient:

HttpClient menuju server

import chromadb
 
client = chromadb.HttpClient(
    host="localhost",
    port=8000,
)

chromadb.HttpClient(host="localhost", port=8000) membuat klien yang mengirim semua operasi ke server. Dari sini, seluruh API yang kalian pelajari di episode 3-10 bekerja sama persis — create_collection, add, query, semuanya.

#Settings Melalui Environment Variable

Cara lain mengonfigurasi klien: lewat variabel environment. chromadb.HttpClient() tanpa argumen membaca pengaturan dari environment:

export CHROMA_SERVER_HOST="localhost"
export CHROMA_SERVER_HTTP_PORT="8000"

Klien dengan settings env

client = chromadb.HttpClient()

chromadb.HttpClient() tanpa argumen memakai CHROMA_SERVER_HOST dan CHROMA_SERVER_HTTP_PORT. Pendekatan ini memudahkan konfigurasi antar environment tanpa mengubah kode.

#Model Tenant dan Database

#Memisahkan Data dengan Tenant

ChromaDB memakai model dua tingkat: tenant dan database. Tenant memisahkan kepemilikan logis (misalnya per tim atau per produk), database memisahkan collection di dalam tenant. Secara default semuanya berada di tenant default_database.

Membuat tenant baru

client.create_tenant("tim-data")
 
client.set_tenant("tim-data")
collection = client.create_collection("analytics")

client.create_tenant("tim-data") lalu client.set_tenant("tim-data") mengarahkan operasi berikutnya ke tenant tersebut. Model ini sangat berguna untuk deployment bersama — kita akan membahas kontrol aksesnya di episode 13.

#Database di Dalam Tenant

Di dalam tenant, kalian bisa memisahkan lagi dengan database:

Membuat database

client.create_database("analytics-db")
client.set_database("analytics-db")

client.create_database("analytics-db") membuat ruang collection tambahan. Kombinasi tenant dan database memberi hierarki pemisahan data yang fleksibel tanpa harus memakai server terpisah.

#Pengaturan Server untuk Lokal vs Produksi

#Konfigurasi Dasar Server

Server membaca konfigurasi lewat variabel environment. Yang paling sering diatur:

export CHROMA_SERVER_HOST="0.0.0.0"
export CHROMA_SERVER_HTTP_PORT="8000"
export CHROMA_SERVER_AUTHN_CREDENTIALS_FILE="/etc/chroma/creds.txt"
chroma run

Dengan CHROMA_SERVER_HOST="0.0.0.0", server menerima koneksi dari luar localhost — diperlukan untuk deployment. Baris CHROMA_SERVER_AUTHN_CREDENTIALS_FILE menyiapkan autentikasi yang akan dibahas penuh di episode 13.

#Lokal vs Produksi

Untuk production, jangan mengekspos server langsung ke internet. Letakkan di belakang reverse proxy dengan TLS, aktifkan autentikasi, dan sambungkan ke storage persisten. Detail deployment akan kita bahas di episode 15.

#Penutup

Episode 12 membawa ChromaDB dari library menjadi service: menjalankan server dengan chroma run, menghubungkan klien lewat HttpClient dengan host dan port, mengatur konfigurasi via environment, memahami model tenant dan database untuk pemisahan data, serta menyusun pengaturan yang membedakan deployment lokal dan produksi.

Inti yang harus dibawa pulang:

• chroma run menjalankan server Rust; curl /api/v2/heartbeat memverifikasinya.
• HttpClient membuat seluruh API ChromaDB bekerja melalui HTTP.
• Host, port, dan auth diatur lewat variabel environment.
• Tenant dan database memisahkan data secara hierarkis.
• Host localhost untuk lokal; 0.0.0.0 di belakang proxy untuk produksi.
• Jangan ekspos server langsung ke internet tanpa auth dan TLS.

Di episode 13 selanjutnya kita akan membahas authentication dan authorization — kondisi default tanpa autentikasi, token-based auth, BasicAuth, konfigurasi server auth, serta kontrol akses per collection dan tenant pada deployment bersama. Server kalian mulai terbuka; saatnya menguncinya.