VaultCX Installation

VaultCX — Installation & Deployment Guide

VaultCX is a self-hosted AI Operations & Knowledge Platform that unifies AI monitoring, model governance, and knowledge automation in a single, secure environment.

---

1️⃣ Architecture Overview

[Web (Next.js)] → [API (FastAPI)]
                     │
                     ├─ Models: Ollama / OpenAI / Anthropic / Local
                     ├─ Vector DB: FAISS / Milvus / Chroma
                     ├─ DB: PostgreSQL (primary) + Redis (cache/queue)
                     ├─ Storage: S3 / MinIO / OSS
                     ├─ Telemetry: Prometheus + Grafana
                     └─ Logs/Traces: Loki / ELK / OTLP

• Security: JWT + RBAC/ABAC, org-domain-project isolation, full audit trail.
• Governance: prompt versioning, SLO dashboards, feature flags, tool success-rate monitoring.
• Widgets: embeddable chat widgets via script or iframe with domain whitelist control.

---

2️⃣ Requirements

• Linux x86_64 / ARM64 (Ubuntu 22.04+ / RHEL 9+)
• Docker 24+ / Compose v2 or Kubernetes 1.26+
• PostgreSQL 14+, Redis 6+
• Optional: MinIO / Prometheus / Grafana / Loki
• Ports: 80 / 443 / 8080 / 3000 / 5432 / 6379

---

3️⃣ Quick Start (Docker Compose)

git clone https://github.com/monzotechnology/vaultcx.git
cd vaultcx
cp .env.example .env
docker compose up -d

Initialize admin:

docker compose exec api vxcctl admin create \
  --email admin@example.com --password "ChangeMe!123"

Then visit → https://vaultcx.example.com

---

4️⃣ Reverse Proxy + TLS (Nginx)

server {
  listen 443 ssl http2;
  server_name vaultcx.example.com;
  ssl_certificate /etc/letsencrypt/live/vaultcx/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/vaultcx/privkey.pem;

  location / {
    proxy_pass http://web:3000;
  }
  location /api/ {
    proxy_pass http://api:8080/;
  }
}

---

5️⃣ Configuration Highlights

• Domains & Prompts — define YAML prompt files under /config/prompts.
• Feature Flags & Rate Limits — controlled in /config/app.yaml.
• Access Control — role-based (super-admin, editor, viewer) + ABAC for fine-grained policies.

---

6️⃣ Embed Widget

<script async src="https://vaultcx.example.com/embed/v1.js"
  data-wid="wid_xxxx"
  data-lang="en"
  data-theme="auto"
  data-position="bottom-right"></script>

---

7️⃣ Monitoring & SLO

• Exposes Prometheus metrics (/metrics)
• Grafana dashboard → vaultcx-slo.json
• Key indicators: QPS, Latency P95, Tool Success Rate, Token Usage

---

8️⃣ Backup & Upgrade

# Backup database
docker compose exec db pg_dump -U vaultcx vaultcx > backup.sql
# Pull latest image and apply migrations
docker compose pull && docker compose up -d
docker compose exec api vxcctl migrate db

---

9️⃣ Troubleshooting

Issue	Cause / Fix
401 Unauthorized	Check JWT_SECRET and CORS origin whitelist
Vector load fail	Ensure VECTOR_PATH is mounted and writable
Widget not loading	Confirm domain is in allowed list
Tool failure rate ↑	Re-authenticate API keys or permissions