Files

T

vh e376d0aec9 Initial commit: PFI fleet inventory, stacks, tooling, and backup pipeline

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.

2026-04-20 14:29:48 -07:00

5.1 KiB

Raw Blame History

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:

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

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)

# 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

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

4. (Optional) Run the demo

# 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)

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

5.1 KiB Raw Blame History