# ChromaDB Setup Documentation

**Project**: Infrastructure-PFI  
**Target Server**: PFI-ANA-Docker (VM 102)  
**IP Address**: 10.250.50.x (VLAN 50)  
**Status**: Ready for deployment  

## Overview

ChromaDB is an embedded vector database optimized for AI/ML applications. This deployment provides:

- Persistent vector storage on `/tank/chromadb/`
- REST API on port 8000 (internal + Traefik-routed)
- Token-based authentication
- Automated backup and health monitoring

## Architecture

```
┌──────────────────────────────────────────────────────────┐
│               PFI-ANA-Docker (VM 102)                    │
│                                                          │
│  ┌──────────────┐    ┌──────────────┐    ┌───────────┐  │
│  │   Traefik    │───▶│   ChromaDB   │    │  Dockge   │  │
│  │   Reverse    │    │  (Port 8000) │    │  Manager  │  │
│  │    Proxy     │    │              │    │           │  │
│  └──────────────┘    └──────┬───────┘    └───────────┘  │
│                             │                            │
│                    ┌────────▼────────┐                   │
│                    │  /tank/chromadb │                   │
│                    │  (bind mount)   │                   │
│                    └─────────────────┘                   │
└──────────────────────────────────────────────────────────┘
```

## File Locations (on VM 102)

| Host Path | Purpose |
|---|---|
| `/opt/docker/conf/chromadb/` | Compose file, auth token, config |
| `/opt/docker/conf/chromadb/docker-compose.yml` | Main compose file |
| `/opt/docker/conf/chromadb/auth_token` | Token for API authentication |
| `/tank/chromadb/` | Persistent vector data (bind mount) |
| `/opt/docker/backups/chromadb/` | Backup archives |

## Authentication

This deployment uses **ChromaDB's native token auth**:

- A random 64-hex-char token is generated during setup (`openssl rand -hex 32`)
- The token is stored at `/opt/docker/conf/chromadb/auth_token` (mode 600)
- Clients must supply the token via `Settings`:

```python
import chromadb
from chromadb.config import Settings

client = chromadb.HttpClient(
    host="10.250.50.x",  # or chromadb.pfi.local via Traefik
    port=8000,
    settings=Settings(
        chroma_client_auth_provider="chromadb.auth.token.TokenAuthClientProvider",
        chroma_client_auth_credentials="YOUR_TOKEN_HERE",
    ),
)
print(client.heartbeat())
```

## Deployment Steps

### 1. Copy compose file to VM 102

```bash
scp configs/pfi-ana/docker/compose-examples/chromadb/docker-compose.yml \
    root@10.250.50.x:/opt/docker/conf/chromadb/docker-compose.yml
```

### 2. Run the setup script (on VM 102)

```bash
# Copy scripts to VM 102
scp scripts/setup-chromadb.sh root@10.250.50.x:/opt/docker/conf/chromadb/
ssh root@10.250.50.x

# Run setup
cd /opt/docker/conf/chromadb
chmod +x setup-chromadb.sh
./setup-chromadb.sh
```

### 3. Verify

```bash
curl http://localhost:8000/api/v1/health
```

### 4. (Optional) Run the demo

```bash
# Copy demo files
scp -r configs/pfi-ana/docker/compose-examples/chromadb/ root@10.250.50.x:/tmp/chromadb-demo/

# On VM 102, edit CHROMA_TOKEN in docker-compose.demo.yml
cd /tmp/chromadb-demo
# Set CHROMA_TOKEN in docker-compose.demo.yml to match auth_token
docker compose -f docker-compose.demo.yml up
```

## Monitoring & Maintenance

| Task | Command |
|---|---|
| Health check | `./scripts/health-check-chromadb.sh` |
| View logs | `docker logs -f chromadb` |
| Backup | `./scripts/backup-chromadb.sh` |
| Restart | `docker compose restart` |
| Stop | `docker compose down` |

### Cron (daily backup at 2 AM)

```cron
0 2 * * * /opt/docker/conf/chromadb/backup-chromadb.sh >> /var/log/chromadb-backup.log 2>&1
```

## Networking

| Aspect | Value |
|---|---|
| Docker network | `traefik-net` (aliased as `tnet`) |
| Internal port | 8000 |
| Traefik host rule | `chromadb.pfi.local` |
| Traefik entrypoint | `websecure` (HTTPS) |
| TLS | Enabled via Traefik |

## Project Files

| File | Purpose |
|---|---|
| `configs/pfi-ana/docker/compose-examples/chromadb/docker-compose.yml` | Production compose (for Dockge) |
| `configs/pfi-ana/docker/compose-examples/chromadb/docker-compose.demo.yml` | Demo client |
| `configs/pfi-ana/docker/compose-examples/chromadb/Dockerfile.demo` | Demo image |
| `configs/pfi-ana/docker/compose-examples/chromadb/scripts/demo.py` | Demo test script |
| `scripts/setup-chromadb.sh` | Deployment script (run on VM 102) |
| `scripts/backup-chromadb.sh` | Backup script (run on VM 102) |
| `scripts/health-check-chromadb.sh` | Health monitoring (run on VM 102) |
| `scripts/quickstart-chromadb.sh` | Convenience wrapper for setup |