From 58fcb04ce42b8df37966117769df455968868ea5 Mon Sep 17 00:00:00 2001 From: Vuong Hoang Date: Fri, 24 Apr 2026 21:57:07 -0700 Subject: [PATCH] docs: drop stale chromadb-setup.md; strip broken VM-102 frontmatter MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Second pass on docs/ cleanup (item #15 in STATUS.md): - pfi/chromadb-setup.md: deleted. References configs/pfi-ana/... and scripts/setup-chromadb.sh, neither of which exist in this repo (artifacts of an earlier project layout). ChromaDB is already live per docker-stack.md; the operational truth lives there. - pfi/docker-stack.md: removed the cross-link to the deleted file and pulled the bit of useful content from it (auth-token generation + client Settings example) into the inline ChromaDB section. - pfi/vm-102-matrix-{synapse,appservice}.md: stripped the YAML frontmatter. The `path:` values pointed at docs/pfi-ana/... which doesn't exist in this repo; no toolchain consumed the metadata. - README.md: tree updated to reflect the deletion. VM-102 docs kept separate by design — each is right-sized; merging would push past the ~500-line guideline. --- docs/README.md | 1 - docs/pfi/chromadb-setup.md | 146 --------------------------- docs/pfi/docker-stack.md | 9 +- docs/pfi/vm-102-matrix-appservice.md | 15 --- docs/pfi/vm-102-matrix-synapse.md | 15 --- 5 files changed, 1 insertion(+), 185 deletions(-) delete mode 100644 docs/pfi/chromadb-setup.md diff --git a/docs/README.md b/docs/README.md index 75802e7..0a480bd 100644 --- a/docs/README.md +++ b/docs/README.md @@ -14,7 +14,6 @@ docs/ │ ├── disaster-recovery.md │ └── pbs-deployment.md └── pfi/ # PFI-specific reference (services, models, VMs) - ├── chromadb-setup.md ├── docker-stack.md ├── model-list.md ├── proxmox-vms.md diff --git a/docs/pfi/chromadb-setup.md b/docs/pfi/chromadb-setup.md deleted file mode 100644 index 4ed12e1..0000000 --- a/docs/pfi/chromadb-setup.md +++ /dev/null @@ -1,146 +0,0 @@ -# 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 | diff --git a/docs/pfi/docker-stack.md b/docs/pfi/docker-stack.md index 35765d9..283900e 100644 --- a/docs/pfi/docker-stack.md +++ b/docs/pfi/docker-stack.md @@ -272,7 +272,7 @@ Dockge expects compose files under `/opt/docker/compose/` on the Docker host. Th **Authentication**: Token-based. The auth token is stored at `/opt/docker/conf/chromadb/auth_token` on the host (mode 600), generated with `openssl rand -hex 32`. Clients must supply this token to access the API. -**Notes**: CPU-only service (no GPU). The compose-examples directory contains a reference compose file with Traefik labels and a demo app — see [chromadb-setup.md](chromadb-setup.md) for full deployment instructions and the demo. +**Notes**: CPU-only service (no GPU). Token is generated once at deploy with `openssl rand -hex 32` into `/opt/docker/conf/chromadb/auth_token` (mode 600); clients pass it via the chromadb client `Settings(chroma_client_auth_provider="...TokenAuthClientProvider", chroma_client_auth_credentials="...")`. --- @@ -324,10 +324,3 @@ Dockge expects compose files under `/opt/docker/compose/` on the Docker host. Th | 8745 | VibeVoice | HTTP | | 9292 | llama-swap | HTTP (→ container 8080) | -## Example Configurations - -Reference/example compose files (not live) are stored in `configs/pfi-ana/docker/compose-examples/`: -- `compose-examples/llama-swap/docker-compose.yml` — earlier llama-swap reference -- `compose-examples/chromadb/` — ChromaDB with Traefik labels, auth, health checks, and demo app - -Full ChromaDB setup instructions: [chromadb-setup.md](chromadb-setup.md) diff --git a/docs/pfi/vm-102-matrix-appservice.md b/docs/pfi/vm-102-matrix-appservice.md index b97c3cf..c93b370 100644 --- a/docs/pfi/vm-102-matrix-appservice.md +++ b/docs/pfi/vm-102-matrix-appservice.md @@ -1,18 +1,3 @@ ---- -id: vm-102-matrix-appservice -title: "VM 102 — Matrix Appservice Configuration" -summary: "AIPA Matrix Application Service bridge setup for VM 102. Covers appservice registration, agent virtual users, room routing, env vars, operational notes, and troubleshooting." -tags: ["infrastructure", "pfi", "pfi-ana", "matrix", "docker", "vm-102", "appservice", "bridge", "aipa", "deployment", "integration"] -keywords: ["matrix.pfi.local", "appservice", "as_token", "hs_token", "aipa-bridge", "matrix_bridge.py", "8009", "send_notification", "virtual-users", "room-routing", "element"] -links: - - "[VM 102 — Matrix Synapse Deployment](vm-102-matrix-synapse.md)" - - "[Matrix Bridge — Application Service Integration](../../../KB/projects/aipa/matrix-bridge.md)" - - "[Docker Stack Conventions](docker-stack.md)" -created: 2026-04-11T00:00:00+00:00 -modified: 2026-04-11T00:00:00+00:00 -path: docs/pfi-ana/vm-102-matrix-appservice.md ---- - # VM 102 — Matrix Appservice Configuration ## Overview diff --git a/docs/pfi/vm-102-matrix-synapse.md b/docs/pfi/vm-102-matrix-synapse.md index f715cb5..9529d6a 100644 --- a/docs/pfi/vm-102-matrix-synapse.md +++ b/docs/pfi/vm-102-matrix-synapse.md @@ -1,18 +1,3 @@ ---- -id: vm-102-matrix-synapse -title: "VM 102 — Matrix Synapse Deployment" -summary: "Docker deployment of Synapse homeserver with PostgreSQL and Element Web on VM 102 (PFI-ANA-Docker). Covers compose file, configuration, storage paths, and admin setup." -tags: ["infrastructure", "pfi", "pfi-ana", "matrix", "docker", "vm-102", "synapse", "self-hosted", "deployment"] -keywords: ["matrix.pfi.local", "synapse", "element-web", "10.250.50.70", "VM-102", "PFI-ANA-Docker", "postgres:16", "appservice", "AIPA"] -links: - - "[Matrix Protocol Reference](../Infrastructure-PFI-Project-Index.md)" - - "[VM-102 Proxmox Config](../../../configs/pfi-ana/proxmox/vm-102.conf)" - - "[Docker Stack Conventions](docker-stack.md)" -created: 2026-04-11T00:00:00+00:00 -modified: 2026-04-11T00:00:00+00:00 -path: docs/pfi-ana/vm-102-matrix-synapse.md ---- - # VM 102 — Matrix Synapse Deployment ## Overview