vh
e376d0aec9
Captures the full workspace state built up to this point:
- CLAUDE.md + README.md describing conventions and the four-host fleet
(ana-ml2, ana-docker, nh3-docker, esh-docker-vm).
- Per-host notes under servers/<host>/ with ssh-target fallback files
and latest system-details snapshots (two in-compose credential leaks
scrubbed; the upstream compose files still need to move those to .env).
- scripts/: server_inspect.sh (read-only remote diagnostic),
refresh-server-info.sh (dir-driven discovery + snapshot capture with
validation warnings), add-host.sh, sync-stacks.sh (pull
compose/conf trees), deploy-stack.sh (push with per-file diff + prompt).
- stacks/: canonical compose for backrest, beszel, dozzle, llama-swap,
rest-server-ana, rest-server-nh3, vllm-qwen3, plus the retired
infinity reference. All use the .env-driven + traefik-net + homepage
label pattern.
- configs/restic/ana-docker/: first resticprofile config + pre-backup
hook (Synapse pg_dump, Seafile mysqldump, Vaultwarden SQLite); templates
for the other three hosts to come.
- docs/pfi/: general infrastructure reference carried over.
- .gitignore excludes .env, stacks-mirror/, and assorted secret/state
filenames to prevent re-leaks on later commits.
147 lines
5.1 KiB
Markdown
147 lines
5.1 KiB
Markdown
# 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 |
|