From 4cbbf3f864dc1bf6b5bec65e6b02321b85696629 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jesu=CC=81s=20Pe=CC=81rez?= Date: Mon, 12 Jan 2026 03:17:04 +0000 Subject: [PATCH] chore: add setup md files --- CHANGELOG.md | 43 ++ README.md | 6 +- docs/setup/deployment-quickstart.html | 389 ++++++++++ docs/setup/deployment-quickstart.md | 6 +- docs/setup/deployment.html | 873 +++++++++++++++++++++ docs/setup/index.html | 242 ++++++ docs/setup/secretumvault-integration.html | 379 +++++++++ docs/setup/setup-guide.html | 890 ++++++++++++++++++++++ docs/setup/setup-guide.md | 2 +- docs/setup/tracking-quickstart.html | 435 +++++++++++ docs/setup/tracking-quickstart.md | 2 +- docs/setup/tracking-setup.html | 774 +++++++++++++++++++ docs/setup/tracking-setup.md | 6 +- 13 files changed, 4036 insertions(+), 11 deletions(-) create mode 100644 docs/setup/deployment-quickstart.html create mode 100644 docs/setup/deployment.html create mode 100644 docs/setup/index.html create mode 100644 docs/setup/secretumvault-integration.html create mode 100644 docs/setup/setup-guide.html create mode 100644 docs/setup/tracking-quickstart.html create mode 100644 docs/setup/tracking-setup.html diff --git a/CHANGELOG.md b/CHANGELOG.md index 717bf33..abcf722 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,49 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added +- **Comprehensive Examples System**: 26+ executable examples demonstrating all VAPORA capabilities + - **Basic Examples (6)**: Foundation for each core crate + - `crates/vapora-agents/examples/01-simple-agent.rs` - Agent registry & metadata + - `crates/vapora-llm-router/examples/01-provider-selection.rs` - Multi-provider routing + - `crates/vapora-swarm/examples/01-agent-registration.rs` - Swarm coordination basics + - `crates/vapora-knowledge-graph/examples/01-execution-tracking.rs` - Temporal KG persistence + - `crates/vapora-backend/examples/01-health-check.rs` - Backend verification + - `crates/vapora-shared/examples/01-error-handling.rs` - Error type patterns + - **Intermediate Examples (9)**: System integration scenarios + - Learning profiles with recency bias weighting + - Budget enforcement with 3-tier fallback strategy + - Cost tracking and ROI analysis per provider/task type + - Swarm load distribution and capability-based filtering + - Knowledge graph learning curves and similarity search + - Full-stack agent + routing integration + - Multi-agent swarm with expertise-based assignment + - **Advanced Examples (2)**: Complete end-to-end workflows + - Full system integration (API → Swarm → Agents → Router → KG) + - REST API integration with real-time WebSocket updates + - **Real-World Use Cases (3)**: Production scenarios with business value + - Code review workflow: 3-stage pipeline with cost optimization ($488/month savings) + - Documentation generation: Automated sync with quality checks ($989/month savings) + - Issue triage: Intelligent classification with selective escalation ($997/month savings) + - **Interactive Notebooks (4)**: Marimo-based exploration + - Agent basics with role configuration + - Budget playground with cost projections + - Learning curves visualization with confidence intervals + - Cost analysis with provider comparison charts + +- **Examples Documentation**: 600+ line comprehensive guide + - `docs/examples-guide.md` - Master reference for all examples + - Example-by-example breakdown with learning objectives and run instructions + - Three learning paths: Quick Overview (30min), System Integration (90min), Production Ready (2-3hrs) + - Common tasks mapped to relevant examples + - Business value analysis for real-world scenarios + - Troubleshooting section and quick reference commands + +- **Examples Organization**: + - Per-crate examples following `crates/*/examples/` Cargo convention + - Root-level examples in `examples/full-stack/` and `examples/real-world/` + - Master README catalog at `examples/README.md` with navigation + - Python requirements for Marimo notebooks: `examples/notebooks/requirements.txt` + - **Web Assets Optimization**: Restructured landing page with minification pipeline - Separated source (`assets/web/src/index.html`) from minified production version - Automated minification script (`assets/web/minify.sh`) for version synchronization diff --git a/README.md b/README.md index 4abe4f2..f7a345d 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ [![Istio](https://img.shields.io/badge/istio-service%20mesh-466BB0.svg)](https://istio.io) [![Tests](https://img.shields.io/badge/tests-218%2B%20passing-green.svg)](crates/) -[Features](#-features) • [Quick Start](#-quick-start) • [Architecture](#-architecture) • [Docs](docs/) • [Contributing](#-contributing) +[Features](#features) • [Quick Start](#quick-start) • [Architecture](#architecture) • [Docs](docs/) • [Contributing](#contributing) @@ -239,7 +239,7 @@ provisioning workflow run workflows/deploy-full-stack.yaml **See full deployment guide**: [`Deployment Guide`](docs/setup/deployment.md) --- - 🏗️ Architecture + ## 🏗️ Architecture ``` ┌─────────────────────────────────────────────────────┐ @@ -540,7 +540,7 @@ provisioning workflow run workflows/deploy-full-stack.yaml - guides/archive/v1-single-agent/: Legacy v1.0 specifications for historical reference --- - 🤝 Contributing + ## 🤝 Contributing We welcome contributions! Please see CONTRIBUTING.md. diff --git a/docs/setup/deployment-quickstart.html b/docs/setup/deployment-quickstart.html new file mode 100644 index 0000000..bb55d1e --- /dev/null +++ b/docs/setup/deployment-quickstart.html @@ -0,0 +1,389 @@ + + + + + + Deployment Quickstart - VAPORA Platform Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+

Keyboard shortcuts

+
+

Press ← or → to navigate between chapters

+

Press S or / to search in the book

+

Press ? to show this help

+

Press Esc to hide this help

+
+
+
+
+ + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+
+

VAPORA v1.0 - Quick Start Deployment

+

5-Minute Production Deployment Guide

+
+

Prerequisites Check

+
# Verify you have these tools
+kubectl version --client  # Kubernetes CLI
+docker --version          # Docker for building images
+nu --version              # Nushell for scripts
+
+
+

Step 1: Build Docker Images (5 minutes)

+
# From project root
+
+# Build all images and push to Docker Hub
+nu scripts/build-docker.nu --registry docker.io --tag v0.1.0 --push
+
+# Or build locally (no push)
+nu scripts/build-docker.nu
+
+

Output: 4 Docker images built (~175MB total)

+
+

Step 2: Configure Secrets (2 minutes)

+
# Edit secrets file
+nano kubernetes/03-secrets.yaml
+
+# Replace these values:
+# - jwt-secret: $(openssl rand -base64 32)
+# - anthropic-api-key: sk-ant-xxxxx
+# - openai-api-key: sk-xxxxx
+# - surrealdb-pass: $(openssl rand -base64 32)
+
+

NEVER commit this file with real secrets!

+
+

Step 3: Configure Ingress (1 minute)

+
# Edit ingress file
+nano kubernetes/08-ingress.yaml
+
+# Update this line:
+# - host: vapora.yourdomain.com  # Change to your domain
+
+
+

Step 4: Deploy to Kubernetes (3 minutes)

+
# Dry run to validate
+nu scripts/deploy-k8s.nu --dry-run
+
+# Deploy for real
+nu scripts/deploy-k8s.nu
+
+# Wait for all pods to be ready
+kubectl wait --for=condition=ready pod -l app -n vapora --timeout=300s
+
+

Output: 11 pods running (2 backend, 2 frontend, 3 agents, 1 mcp, 1 db, 1 nats)

+
+

Step 5: Verify Deployment (2 minutes)

+
# Check all pods are running
+kubectl get pods -n vapora
+
+# Check services
+kubectl get svc -n vapora
+
+# Get ingress IP/hostname
+kubectl get ingress -n vapora
+
+# Test health endpoints
+kubectl exec -n vapora deploy/vapora-backend -- curl -s http://localhost:8080/health
+
+
+

Step 6: Access VAPORA

+
    +
  1. Configure DNS: Point your domain to ingress IP
    2. +
  2. Access UI: https://vapora.yourdomain.com
    3. +
  3. Check health: https://vapora.yourdomain.com/api/v1/health
    4. +
+
+

Troubleshooting

+

Pods not starting?

+
kubectl describe pod -n vapora <pod-name>
+kubectl logs -n vapora <pod-name>
+
+

Can't connect to database?

+
kubectl logs -n vapora surrealdb-0
+kubectl exec -n vapora deploy/vapora-backend -- curl http://surrealdb:8000/health
+
+

Image pull errors?

+
# Check if images exist
+docker images | grep vapora
+
+# Create registry secret
+kubectl create secret docker-registry regcred \
+  -n vapora \
+  --docker-server=docker.io \
+  --docker-username=<user> \
+  --docker-password=<pass>
+
+
+

Alternative: Provisioning Deployment

+

For advanced deployment with service mesh and auto-scaling:

+
cd provisioning/vapora-wrksp
+
+# Validate configuration
+nu scripts/validate-provisioning.nu
+
+# Deploy full stack
+provisioning workflow run workflows/deploy-full-stack.yaml
+
+

See: provisioning-integration/README.md

+
+

Next Steps

+
    +
  • +Set up monitoring (Prometheus + Grafana)
    • +
  • +Configure TLS certificates (cert-manager)
    • +
  • +Set up backups for SurrealDB
    • +
  • +Configure HPA (Horizontal Pod Autoscaler)
    • +
  • +Enable log aggregation
    • +
  • +Test agent workflows
    • +
+
+

Full Documentation

+ +
+

Quick Commands Reference

+
# Build images
+nu scripts/build-docker.nu --push
+
+# Deploy
+nu scripts/deploy-k8s.nu
+
+# Validate
+nu scripts/validate-deployment.nu
+
+# Validate Provisioning
+nu scripts/validate-provisioning.nu
+
+# Check status
+kubectl get all -n vapora
+
+# View logs
+kubectl logs -n vapora -l app=vapora-backend -f
+
+# Scale agents
+kubectl scale deployment vapora-agents -n vapora --replicas=5
+
+# Rollback
+kubectl rollout undo deployment/vapora-backend -n vapora
+
+# Uninstall
+kubectl delete namespace vapora
+
+
+

VAPORA v1.0 - Production Ready ✅ +Total Deployment Time: ~15 minutes +Status: All 5 phases completed

+ +
+ + +
+
+ + + +
+ + + + + + + + + + + + + + + + + + +
+ + diff --git a/docs/setup/deployment-quickstart.md b/docs/setup/deployment-quickstart.md index f620ec9..25be1fc 100644 --- a/docs/setup/deployment-quickstart.md +++ b/docs/setup/deployment-quickstart.md @@ -105,21 +105,21 @@ kubectl exec -n vapora deploy/vapora-backend -- curl -s http://localhost:8080/he ## Troubleshooting -### Pods not starting? +### Pods not starting ```bash kubectl describe pod -n vapora kubectl logs -n vapora ``` -### Can't connect to database? +### Can't connect to database ```bash kubectl logs -n vapora surrealdb-0 kubectl exec -n vapora deploy/vapora-backend -- curl http://surrealdb:8000/health ``` -### Image pull errors? +### Image pull errors ```bash # Check if images exist diff --git a/docs/setup/deployment.html b/docs/setup/deployment.html new file mode 100644 index 0000000..c72050f --- /dev/null +++ b/docs/setup/deployment.html @@ -0,0 +1,873 @@ + + + + + + Deployment Guide - VAPORA Platform Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+

Keyboard shortcuts

+
+

Press ← or → to navigate between chapters

+

Press S or / to search in the book

+

Press ? to show this help

+

Press Esc to hide this help

+
+
+
+
+ + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+
+

VAPORA v1.0 Deployment Guide

+

Complete guide for deploying VAPORA v1.0 to Kubernetes (self-hosted).

+

Version: 0.1.0 +Status: Production Ready +Last Updated: 2025-11-10

+
+

Table of Contents

+
    +
  1. Overview
    2. +
  2. Prerequisites
    3. +
  3. Architecture
    4. +
  4. Deployment Methods
    5. +
  5. Building Docker Images
    6. +
  6. Kubernetes Deployment
    7. +
  7. Provisioning Deployment
    8. +
  8. Configuration
    9. +
  9. Monitoring & Health Checks
    10. +
  10. Scaling
    11. +
  11. Troubleshooting
    12. +
  12. Rollback
    13. +
  13. Security
    14. +
+
+

Overview

+

VAPORA v1.0 is a cloud-native multi-agent software development platform that runs on Kubernetes. It consists of:

+
    +
  • 6 Rust services: Backend API, Frontend UI, Agents, MCP Server, LLM Router (embedded), Shared library
    • +
  • 2 Infrastructure services: SurrealDB (database), NATS JetStream (messaging)
    • +
  • Multi-IA routing: Claude, OpenAI, Gemini, Ollama support
    • +
  • 12 specialized agents: Architect, Developer, Reviewer, Tester, Documenter, etc.
    • +
+

All services are containerized and deployed as Kubernetes workloads.

+
+

Prerequisites

+

Required Tools

+
    +
  • Kubernetes 1.25+ (K3s, RKE2, or managed Kubernetes)
    • +
  • kubectl (configured and connected to cluster)
    • +
  • Docker or Podman (for building images)
    • +
  • Nushell (for deployment scripts)
    • +
+

Optional Tools

+
    +
  • Provisioning CLI (for advanced deployment)
    • +
  • Helm (if using Helm charts)
    • +
  • cert-manager (for automatic TLS certificates)
    • +
  • Prometheus/Grafana (for monitoring)
    • +
+

Cluster Requirements

+
    +
  • Minimum: 4 CPU, 8GB RAM, 50GB storage
    • +
  • Recommended: 8 CPU, 16GB RAM, 100GB storage
    • +
  • Production: 16+ CPU, 32GB+ RAM, 200GB+ storage
    • +
+

Storage

+
    +
  • Storage Class: Required for SurrealDB PersistentVolumeClaim
    • +
  • Options: local-path, nfs-client, rook-ceph, or cloud provider storage
    • +
  • Minimum: 20Gi for database
    • +
+

Ingress

+
    +
  • nginx-ingress controller installed
    • +
  • Domain name pointing to cluster ingress IP
    • +
  • TLS certificate (optional, recommended for production)
    • +
+
+

Architecture

+
┌─────────────────────────────────────────────────────┐
+│                  Internet / Users                   │
+└───────────────────────┬─────────────────────────────┘
+                        │
+┌───────────────────────▼─────────────────────────────┐
+│  Ingress (nginx)                                    │
+│  - vapora.example.com                               │
+│  - TLS termination                                  │
+└────┬────────┬─────────┬─────────┬──────────────────┘
+     │        │         │         │
+     │        │         │         │
+┌────▼────┐ ┌▼─────┐ ┌▼─────┐  ┌▼──────────┐
+│Frontend │ │Backend│ │ MCP  │  │           │
+│(Leptos) │ │(Axum) │ │Server│  │           │
+│ 2 pods  │ │2 pods │ │1 pod │  │           │
+└─────────┘ └───┬───┘ └──────┘  │           │
+                │                 │           │
+         ┌──────┴──────┬──────────┤           │
+         │             │          │           │
+    ┌────▼────┐   ┌───▼─────┐  ┌▼───────┐   │
+    │SurrealDB│   │  NATS   │  │ Agents │   │
+    │StatefulS│   │JetStream│  │ 3 pods │   │
+    │  1 pod  │   │  1 pod  │  └────────┘   │
+    └─────────┘   └─────────┘                │
+         │                                   │
+    ┌────▼────────────────────────────────┐  │
+    │  Persistent Volume (20Gi)           │  │
+    │  - SurrealDB data                   │  │
+    └─────────────────────────────────────┘  │
+                                              │
+┌─────────────────────────────────────────────▼──┐
+│  External LLM APIs                            │
+│  - Anthropic Claude API                       │
+│  - OpenAI API                                 │
+│  - Google Gemini API                          │
+│  - (Optional) Ollama local                    │
+└───────────────────────────────────────────────┘
+
+
+

Deployment Methods

+

VAPORA supports two deployment methods:

+ +

Pros:

+
    +
  • Simple, well-documented
    • +
  • Standard K8s manifests
    • +
  • Easy to understand and modify
    • +
  • No additional tools required
    • +
+

Cons:

+
    +
  • Manual cluster management
    • +
  • Manual service ordering
    • +
  • No built-in rollback
    • +
+

Use when: Learning, testing, or simple deployments

+ +

Pros:

+
    +
  • Automated cluster creation
    • +
  • Declarative workflows
    • +
  • Built-in rollback
    • +
  • Service mesh integration
    • +
  • Secret management
    • +
+

Cons:

+
    +
  • Requires Provisioning CLI
    • +
  • More complex configuration
    • +
  • Steeper learning curve
    • +
+

Use when: Production deployments, complex environments

+
+

Building Docker Images

+ +
# Build all images (local registry)
+nu scripts/build-docker.nu
+
+# Build and push to Docker Hub
+nu scripts/build-docker.nu --registry docker.io --push
+
+# Build with specific tag
+nu scripts/build-docker.nu --tag v0.1.0
+
+# Build without cache
+nu scripts/build-docker.nu --no-cache
+
+

Option 2: Manual Docker Build

+
# From project root
+
+# Backend
+docker build -f crates/vapora-backend/Dockerfile -t vapora/backend:latest .
+
+# Frontend
+docker build -f crates/vapora-frontend/Dockerfile -t vapora/frontend:latest .
+
+# Agents
+docker build -f crates/vapora-agents/Dockerfile -t vapora/agents:latest .
+
+# MCP Server
+docker build -f crates/vapora-mcp-server/Dockerfile -t vapora/mcp-server:latest .
+
+

Image Sizes (Approximate)

+
    +
  • vapora/backend: ~50MB (Alpine + Rust binary)
    • +
  • vapora/frontend: ~30MB (nginx + WASM)
    • +
  • vapora/agents: ~50MB (Alpine + Rust binary)
    • +
  • vapora/mcp-server: ~45MB (Alpine + Rust binary)
    • +
+
+

Kubernetes Deployment

+

Step 1: Configure Secrets

+

Edit kubernetes/03-secrets.yaml:

+
stringData:
+  # Generate strong JWT secret
+  jwt-secret: "$(openssl rand -base64 32)"
+
+  # Add your LLM API keys
+  anthropic-api-key: "sk-ant-xxxxx"
+  openai-api-key: "sk-xxxxx"
+  gemini-api-key: "xxxxx"  # Optional
+
+  # Database credentials
+  surrealdb-user: "root"
+  surrealdb-pass: "$(openssl rand -base64 32)"
+
+

IMPORTANT: Never commit real secrets to version control!

+

Step 2: Configure Ingress

+

Edit kubernetes/08-ingress.yaml:

+
spec:
+  rules:
+  - host: vapora.yourdomain.com  # Change this!
+
+ +
# Dry run to validate
+nu scripts/deploy-k8s.nu --dry-run
+
+# Deploy to default namespace (vapora)
+nu scripts/deploy-k8s.nu
+
+# Deploy to custom namespace
+nu scripts/deploy-k8s.nu --namespace my-vapora
+
+# Skip secrets (if already created)
+nu scripts/deploy-k8s.nu --skip-secrets
+
+

Step 4: Manual Deploy (Alternative)

+
# Apply manifests in order
+kubectl apply -f kubernetes/00-namespace.yaml
+kubectl apply -f kubernetes/01-surrealdb.yaml
+kubectl apply -f kubernetes/02-nats.yaml
+kubectl apply -f kubernetes/03-secrets.yaml
+kubectl apply -f kubernetes/04-backend.yaml
+kubectl apply -f kubernetes/05-frontend.yaml
+kubectl apply -f kubernetes/06-agents.yaml
+kubectl apply -f kubernetes/07-mcp-server.yaml
+kubectl apply -f kubernetes/08-ingress.yaml
+
+# Wait for rollout
+kubectl rollout status deployment/vapora-backend -n vapora
+kubectl rollout status deployment/vapora-frontend -n vapora
+
+

Step 5: Verify Deployment

+
# Check all pods are running
+kubectl get pods -n vapora
+
+# Expected output:
+# NAME                                READY   STATUS    RESTARTS
+# surrealdb-0                         1/1     Running   0
+# nats-xxx                            1/1     Running   0
+# vapora-backend-xxx                  1/1     Running   0
+# vapora-backend-yyy                  1/1     Running   0
+# vapora-frontend-xxx                 1/1     Running   0
+# vapora-frontend-yyy                 1/1     Running   0
+# vapora-agents-xxx                   1/1     Running   0
+# vapora-agents-yyy                   1/1     Running   0
+# vapora-agents-zzz                   1/1     Running   0
+# vapora-mcp-server-xxx               1/1     Running   0
+
+# Check services
+kubectl get svc -n vapora
+
+# Check ingress
+kubectl get ingress -n vapora
+
+

Step 6: Access VAPORA

+
# Get ingress IP/hostname
+kubectl get ingress vapora -n vapora
+
+# Configure DNS
+# Point vapora.yourdomain.com to ingress IP
+
+# Access UI
+open https://vapora.yourdomain.com
+
+
+

Provisioning Deployment

+

Step 1: Validate Configuration

+
# Validate Provisioning workspace
+nu scripts/validate-provisioning.nu
+
+

Step 2: Create Cluster

+
cd provisioning/vapora-wrksp
+
+# Validate configuration
+provisioning validate --all
+
+# Create cluster
+provisioning cluster create --config workspace.toml
+
+

Step 3: Deploy Services

+
# Deploy infrastructure (database, messaging)
+provisioning workflow run workflows/deploy-infra.yaml
+
+# Deploy services (backend, frontend, agents)
+provisioning workflow run workflows/deploy-services.yaml
+
+# Or deploy full stack at once
+provisioning workflow run workflows/deploy-full-stack.yaml
+
+

Step 4: Health Check

+
provisioning workflow run workflows/health-check.yaml
+
+

See provisioning-integration/README.md for details.

+
+

Configuration

+

Environment Variables

+

Backend (vapora-backend)

+
RUST_LOG=info,vapora=debug
+SURREALDB_URL=http://surrealdb:8000
+SURREALDB_USER=root
+SURREALDB_PASS=<secret>
+NATS_URL=nats://nats:4222
+JWT_SECRET=<secret>
+BIND_ADDR=0.0.0.0:8080
+
+

Agents (vapora-agents)

+
RUST_LOG=info,vapora_agents=debug
+NATS_URL=nats://nats:4222
+BIND_ADDR=0.0.0.0:9000
+ANTHROPIC_API_KEY=<secret>
+OPENAI_API_KEY=<secret>
+GEMINI_API_KEY=<secret>
+VAPORA_AGENT_CONFIG=/etc/vapora/agents.toml  # Optional
+
+

MCP Server (vapora-mcp-server)

+
RUST_LOG=info,vapora_mcp_server=debug
+# Port configured via --port flag
+
+

ConfigMaps

+

Create custom configuration:

+
kubectl create configmap agent-config -n vapora \
+  --from-file=agents.toml
+
+

Mount in deployment:

+
volumeMounts:
+- name: config
+  mountPath: /etc/vapora
+volumes:
+- name: config
+  configMap:
+    name: agent-config
+
+
+

Monitoring & Health Checks

+

Health Endpoints

+

All services expose health check endpoints:

+
    +
  • Backend: GET /health
    • +
  • Frontend: GET /health.html
    • +
  • Agents: GET /health, GET /ready
    • +
  • MCP Server: GET /health
    • +
  • SurrealDB: GET /health
    • +
  • NATS: GET /healthz (port 8222)
    • +
+

Manual Health Checks

+
# Backend health
+kubectl exec -n vapora deploy/vapora-backend -- \
+  curl -s http://localhost:8080/health
+
+# Database health
+kubectl exec -n vapora deploy/vapora-backend -- \
+  curl -s http://surrealdb:8000/health
+
+# NATS health
+kubectl exec -n vapora deploy/vapora-backend -- \
+  curl -s http://nats:8222/healthz
+
+

Kubernetes Probes

+

All deployments have:

+
    +
  • Liveness Probe: Restarts unhealthy pods
    • +
  • Readiness Probe: Removes pod from service until ready
    • +
+

Logs

+
# View backend logs
+kubectl logs -n vapora -l app=vapora-backend -f
+
+# View agent logs
+kubectl logs -n vapora -l app=vapora-agents -f
+
+# View all logs
+kubectl logs -n vapora -l app --all-containers=true -f
+
+

Metrics (Optional)

+

Deploy Prometheus + Grafana:

+
# Install Prometheus Operator
+helm install prometheus prometheus-community/kube-prometheus-stack \
+  -n monitoring --create-namespace
+
+# Access Grafana
+kubectl port-forward -n monitoring svc/prometheus-grafana 3000:80
+
+

VAPORA services expose metrics on /metrics endpoint (future enhancement).

+
+

Scaling

+

Manual Scaling

+
# Scale backend
+kubectl scale deployment vapora-backend -n vapora --replicas=4
+
+# Scale frontend
+kubectl scale deployment vapora-frontend -n vapora --replicas=3
+
+# Scale agents (for higher workload)
+kubectl scale deployment vapora-agents -n vapora --replicas=10
+
+

Horizontal Pod Autoscaler (HPA)

+
apiVersion: autoscaling/v2
+kind: HorizontalPodAutoscaler
+metadata:
+  name: vapora-backend-hpa
+  namespace: vapora
+spec:
+  scaleTargetRef:
+    apiVersion: apps/v1
+    kind: Deployment
+    name: vapora-backend
+  minReplicas: 2
+  maxReplicas: 10
+  metrics:
+  - type: Resource
+    resource:
+      name: cpu
+      target:
+        type: Utilization
+        averageUtilization: 70
+
+

Apply:

+
kubectl apply -f hpa.yaml
+
+

Resource Limits

+

Adjust in deployment YAML:

+
resources:
+  requests:
+    cpu: 200m
+    memory: 256Mi
+  limits:
+    cpu: 1000m
+    memory: 1Gi
+
+
+

Troubleshooting

+

Pods Not Starting

+
# Check pod status
+kubectl get pods -n vapora
+
+# Describe pod for events
+kubectl describe pod -n vapora <pod-name>
+
+# Check logs
+kubectl logs -n vapora <pod-name>
+
+# Check previous logs (if crashed)
+kubectl logs -n vapora <pod-name> --previous
+
+

Database Connection Issues

+
# Check SurrealDB is running
+kubectl get pod -n vapora -l app=surrealdb
+
+# Test connection from backend
+kubectl exec -n vapora deploy/vapora-backend -- \
+  curl -v http://surrealdb:8000/health
+
+# Check SurrealDB logs
+kubectl logs -n vapora surrealdb-0
+
+

NATS Connection Issues

+
# Check NATS is running
+kubectl get pod -n vapora -l app=nats
+
+# Test connection
+kubectl exec -n vapora deploy/vapora-backend -- \
+  curl http://nats:8222/varz
+
+# Check NATS logs
+kubectl logs -n vapora -l app=nats
+
+

Image Pull Errors

+
# Check image pull secrets
+kubectl get secrets -n vapora
+
+# Create Docker registry secret
+kubectl create secret docker-registry regcred \
+  -n vapora \
+  --docker-server=<registry> \
+  --docker-username=<username> \
+  --docker-password=<password>
+
+# Add to deployment
+spec:
+  imagePullSecrets:
+  - name: regcred
+
+

Ingress Not Working

+
# Check ingress controller is installed
+kubectl get pods -n ingress-nginx
+
+# Check ingress resource
+kubectl describe ingress vapora -n vapora
+
+# Check ingress logs
+kubectl logs -n ingress-nginx -l app.kubernetes.io/name=ingress-nginx
+
+
+

Rollback

+

Kubernetes Rollback

+
# View rollout history
+kubectl rollout history deployment/vapora-backend -n vapora
+
+# Rollback to previous version
+kubectl rollout undo deployment/vapora-backend -n vapora
+
+# Rollback to specific revision
+kubectl rollout undo deployment/vapora-backend -n vapora --to-revision=2
+
+

Provisioning Rollback

+
cd provisioning/vapora-wrksp
+
+# List versions
+provisioning version list
+
+# Rollback to previous version
+provisioning rollback --to-version <version-id>
+
+
+

Security

+

Secrets Management

+
    +
  • Kubernetes Secrets: Encrypted at rest (if configured in K8s)
    • +
  • External Secrets Operator: Sync from Vault, AWS Secrets Manager, etc.
    • +
  • RustyVault: Integrated with Provisioning
    • +
+

Network Policies

+

Apply network policies to restrict pod-to-pod communication:

+
apiVersion: networking.k8s.io/v1
+kind: NetworkPolicy
+metadata:
+  name: vapora-backend
+  namespace: vapora
+spec:
+  podSelector:
+    matchLabels:
+      app: vapora-backend
+  ingress:
+  - from:
+    - podSelector:
+        matchLabels:
+          app: vapora-frontend
+    ports:
+    - protocol: TCP
+      port: 8080
+
+

TLS Certificates

+

Use cert-manager for automatic TLS:

+
# Install cert-manager
+kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.12.0/cert-manager.yaml
+
+# Create ClusterIssuer
+kubectl apply -f - <<EOF
+apiVersion: cert-manager.io/v1
+kind: ClusterIssuer
+metadata:
+  name: letsencrypt-prod
+spec:
+  acme:
+    server: https://acme-v02.api.letsencrypt.org/directory
+    email: admin@yourdomain.com
+    privateKeySecretRef:
+      name: letsencrypt-prod
+    solvers:
+    - http01:
+        ingress:
+          class: nginx
+EOF
+
+

Update ingress:

+
metadata:
+  annotations:
+    cert-manager.io/cluster-issuer: "letsencrypt-prod"
+spec:
+  tls:
+  - hosts:
+    - vapora.yourdomain.com
+    secretName: vapora-tls
+
+
+

Backup & Restore

+

SurrealDB Backup

+
# Create backup
+kubectl exec -n vapora surrealdb-0 -- \
+  surreal export --conn http://localhost:8000 \
+  --user root --pass <password> \
+  --ns vapora --db main backup.surql
+
+# Copy backup locally
+kubectl cp vapora/surrealdb-0:/backup.surql ./backup-$(date +%Y%m%d).surql
+
+

SurrealDB Restore

+
# Copy backup to pod
+kubectl cp ./backup.surql vapora/surrealdb-0:/restore.surql
+
+# Restore
+kubectl exec -n vapora surrealdb-0 -- \
+  surreal import --conn http://localhost:8000 \
+  --user root --pass <password> \
+  --ns vapora --db main /restore.surql
+
+

PVC Backup

+
# Snapshot PVC (if supported by storage class)
+kubectl apply -f - <<EOF
+apiVersion: snapshot.storage.k8s.io/v1
+kind: VolumeSnapshot
+metadata:
+  name: surrealdb-snapshot
+  namespace: vapora
+spec:
+  source:
+    persistentVolumeClaimName: data-surrealdb-0
+EOF
+
+
+

Uninstall

+

Delete All Resources

+
# Delete namespace (deletes all resources)
+kubectl delete namespace vapora
+
+# Or delete manifests individually
+kubectl delete -f kubernetes/
+
+

Delete PVCs

+
# List PVCs
+kubectl get pvc -n vapora
+
+# Delete PVC (data will be lost!)
+kubectl delete pvc data-surrealdb-0 -n vapora
+
+
+

Next Steps

+

After successful deployment:

+
    +
  1. Configure DNS: Point domain to ingress IP
    2. +
  2. Set up TLS: Configure cert-manager for HTTPS
    3. +
  3. Enable monitoring: Deploy Prometheus/Grafana
    4. +
  4. Configure backups: Schedule SurrealDB backups
    5. +
  5. Set up CI/CD: Automate deployments
    6. +
  6. Configure HPA: Enable autoscaling
    7. +
  7. Test disaster recovery: Practice rollback procedures
    8. +
+
+

Support

+
    +
  • Deployment Issues: Check kubernetes/README.md
    • +
  • Provisioning Issues: Check provisioning-integration/README.md
    • +
  • Scripts Help: Run nu scripts/<script-name>.nu --help
    • +
  • Kubernetes Docs: https://kubernetes.io/docs/
    • +
+
+

VAPORA v1.0 - Cloud-Native Multi-Agent Platform +Status: Production Ready ✅

+ +
+ + +
+
+ + + +
+ + + + + + + + + + + + + + + + + + +
+ + diff --git a/docs/setup/index.html b/docs/setup/index.html new file mode 100644 index 0000000..e8ffa8b --- /dev/null +++ b/docs/setup/index.html @@ -0,0 +1,242 @@ + + + + + + Setup Overview - VAPORA Platform Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+

Keyboard shortcuts

+
+

Press ← or → to navigate between chapters

+

Press S or / to search in the book

+

Press ? to show this help

+

Press Esc to hide this help

+
+
+
+
+ + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+
+

Setup & Deployment

+

Installation, configuration, and deployment guides for VAPORA.

+

Contents

+ +

Quick Start

+
    +
  1. Read Deployment Quickstart for fast setup
    2. +
  2. Refer to Setup Guide for detailed configuration
    3. +
  3. Use Deployment Guide for production deployments
    4. +
+ +
+ + +
+
+ + + +
+ + + + + + + + + + + + + + + + + + +
+ + diff --git a/docs/setup/secretumvault-integration.html b/docs/setup/secretumvault-integration.html new file mode 100644 index 0000000..6769454 --- /dev/null +++ b/docs/setup/secretumvault-integration.html @@ -0,0 +1,379 @@ + + + + + + SecretumVault Integration - VAPORA Platform Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+

Keyboard shortcuts

+
+

Press ← or → to navigate between chapters

+

Press S or / to search in the book

+

Press ? to show this help

+

Press Esc to hide this help

+
+
+
+
+ + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+
+

SecretumVault Integration

+

VAPORA integrates with SecretumVault, a post-quantum ready secrets management system, for secure credential and API key management across all microservices.

+

Overview

+

SecretumVault provides:

+
    +
  • Post-quantum cryptography ready for future-proof security
    • +
  • Multi-backend storage (filesystem, SurrealDB, PostgreSQL, etcd)
    • +
  • Fine-grained access control with Cedar policy engine
    • +
  • Secrets server for centralized credential management
    • +
  • CLI tools for operations and development
    • +
+

Integration Points

+

SecretumVault is integrated into these VAPORA services:

+
+ + + +
ServicePurposeFeatures
vapora-backendREST API credentials, database secrets, JWT keysCentral secrets management
vapora-agentsAgent authentication, service credentialsSecure agent-to-service auth
vapora-llm-routerLLM provider API keys (Claude, OpenAI, Gemini, Ollama)Cost tracking + credential rotation
+
+

Architecture

+
┌─────────────────────────────────────────────────────────────┐
+│                    VAPORA Services                          │
+├─────────────┬──────────────────┬────────────────────────────┤
+│ Backend API │ Agent Orchestration │ LLM Router              │
+└──────┬──────┴────────┬─────────┴──────────┬─────────────────┘
+       │               │                    │
+       └───────────────┼────────────────────┘
+                       │
+                       ▼
+         ┌─────────────────────────────┐
+         │   SecretumVault Server      │
+         ├─────────────────────────────┤
+         │ • Credential storage        │
+         │ • Policy enforcement        │
+         │ • Audit logging             │
+         │ • Key rotation              │
+         └──────────┬──────────────────┘
+                    │
+        ┌───────────┴────────────┐
+        ▼                        ▼
+    Storage Layer          Policy Engine
+    (SurrealDB)            (Cedar)
+
+

Configuration

+

Environment Variables

+
# SecretumVault server connection
+SECRETUMVAULT_URL=http://secretumvault:3030
+SECRETUMVAULT_TOKEN=<identity-token>
+
+# Storage backend
+SECRETUMVAULT_STORAGE=surrealdb
+SURREAL_URL=ws://surrealdb:8000
+SURREAL_DB=secretumvault
+
+# Crypto backend
+SECRETUMVAULT_CRYPTO=openssl  # or aws-lc for post-quantum
+
+

Cargo Features

+

SecretumVault is integrated with these features enabled:

+
secretumvault = { workspace = true }
+# Automatically uses: "server", "surrealdb-storage"
+
+

Usage Examples

+

In vapora-backend

+
#![allow(unused)]
+fn main() {
+use secretumvault::SecretClient;
+
+// Initialize client
+let client = SecretClient::new(
+    &env::var("SECRETUMVAULT_URL")?,
+    &env::var("SECRETUMVAULT_TOKEN")?,
+).await?;
+
+// Retrieve API key
+let api_key = client.get_secret("llm/claude-api-key").await?;
+
+// Store credential securely
+client.store_secret(
+    "database/postgres-password",
+    &password,
+    Some("postgres-creds"),
+).await?;
+}
+

In vapora-llm-router

+
#![allow(unused)]
+fn main() {
+use secretumvault::SecretClient;
+
+// Get LLM provider credentials
+let openai_key = client.get_secret("llm/openai-api-key").await?;
+let claude_key = client.get_secret("llm/claude-api-key").await?;
+let gemini_key = client.get_secret("llm/gemini-api-key").await?;
+
+// Fallback to Ollama (local, no key needed)
+}
+

Running SecretumVault

+

Local Development

+
# Terminal 1: Start SecretumVault server
+cd /Users/Akasha/Development/secretumvault
+cargo run --bin secretumvault-server --features server,surrealdb-storage
+
+# Terminal 2: Initialize with default policies
+cargo run --bin secretumvault-cli -- init-policies
+
+

Production (Kubernetes)

+
# Will be added to kubernetes/
+kubectl apply -f kubernetes/secretumvault/
+
+

Security Best Practices

+
    +
  1. +

    Token Management

    +
      +
    • Use identity-based tokens (not basic auth)
      • +
    • Rotate tokens regularly
      • +
    • Store token in .env.local (not in git)
      • +
    +
    2. +
  2. +

    Secret Storage

    +
      +
    • Never commit credentials to git
      • +
    • Use SecretumVault for all sensitive data
      • +
    • Enable audit logging for compliance
      • +
    +
    3. +
  3. +

    Policy Enforcement

    +
      +
    • Define Cedar policies per role/service
      • +
    • Restrict access by principle of least privilege
      • +
    • Review policies during security audits
      • +
    +
    4. +
  4. +

    Crypto Backend

    +
      +
    • Use aws-lc for post-quantum readiness
      • +
    • Plan migration as quantum threats evolve
      • +
    +
    5. +
+ + +
+

Integration Status: ✅ Active +Services: Backend, Agents, LLM Router +Features: server, surrealdb-storage, cedar-policies

+ +
+ + +
+
+ + + +
+ + + + + + + + + + + + + + + + + + +
+ + diff --git a/docs/setup/setup-guide.html b/docs/setup/setup-guide.html new file mode 100644 index 0000000..9c5af68 --- /dev/null +++ b/docs/setup/setup-guide.html @@ -0,0 +1,890 @@ + + + + + + Setup Guide - VAPORA Platform Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+

Keyboard shortcuts

+
+

Press ← or → to navigate between chapters

+

Press S or / to search in the book

+

Press ? to show this help

+

Press Esc to hide this help

+
+
+
+
+ + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+
+
+

title: Vapora Project - Complete Setup Guide +date: 2025-11-10 +version: 1.0 +status: READY

+

🛠️ Vapora - Complete Setup Guide

+

Complete step-by-step guide for setting up the entire Vapora project from scratch.

+
+

📋 Table of Contents

+
    +
  1. Prerequisites & Environment
    2. +
  2. Installation
    3. +
  3. Configuration
    4. +
  4. Building & Testing
    5. +
  5. Development Setup
    6. +
  6. First Run
    7. +
  7. Troubleshooting
    8. +
+
+

Prerequisites & Environment

+

System Requirements

+
+ + + + + +
RequirementMinimumRecommended
OSmacOS 10.15+macOS 12+ (M1/M2 optimized)
CPU2-core4+ cores
RAM4GB8GB+
Disk2GB5GB+
InternetRequiredRequired
+
+

Software Requirements

+

Required:

+
    +
  • Rust 1.75+ (install from https://rustup.rs)
    • +
  • Cargo (comes with Rust)
    • +
  • Git 2.20+
    • +
  • NuShell 0.95+ (for scripts)
    • +
+

Optional but Recommended:

+
    +
  • Node.js 18+ (for frontend tooling)
    • +
  • Docker (for containerization)
    • +
  • Kubernetes tools (kubectl, k3s for deployment)
    • +
+

Prerequisite Check Script

+
#!/bin/bash
+echo "🔍 Checking Vapora prerequisites..."
+echo "=================================="
+
+# Check Rust
+if ! command -v rustc &> /dev/null; then
+    echo "❌ Rust not found. Install from https://rustup.rs"
+    exit 1
+fi
+echo "✅ Rust $(rustc --version | awk '{print $2}')"
+
+# Check Cargo
+if ! command -v cargo &> /dev/null; then
+    echo "❌ Cargo not found"
+    exit 1
+fi
+echo "✅ Cargo $(cargo --version | awk '{print $2}')"
+
+# Check Git
+if ! command -v git &> /dev/null; then
+    echo "❌ Git not found. Install from https://git-scm.com"
+    exit 1
+fi
+echo "✅ Git $(git --version | awk '{print $3}')"
+
+# Check NuShell (optional)
+if command -v nu &> /dev/null; then
+    echo "✅ NuShell $(nu --version)"
+else
+    echo "⚠️  NuShell not found (optional, needed for scripts)"
+fi
+
+echo "=================================="
+echo "✅ All prerequisites satisfied!"
+
+

Save as check-prerequisites.sh and run:

+
chmod +x check-prerequisites.sh
+./check-prerequisites.sh
+
+
+

Installation

+

Step 1: Prepare Your Environment

+
# Update Rust (if already installed)
+rustup update stable
+rustup component add rustfmt clippy
+
+# Clone or verify Vapora repo
+if [ ! -d vapora ]; then
+    git clone https://github.com/vapora/vapora.git
+fi
+
+cd vapora
+
+

Step 2: Install NuShell (if needed)

+
# macOS with Homebrew
+brew install nu
+
+# Or from source (if on other OS)
+# See https://www.nushell.sh/book/installation.html
+
+

Verify:

+
nu --version  # Should be 0.95+
+
+

Step 3: Install Frontend Tools (if building frontend)

+
# Install trunk for Leptos WASM building
+cargo install trunk
+
+# Install wasm-pack for WASM compilation
+rustup target add wasm32-unknown-unknown
+
+

Step 4: Download Workspace Dependencies

+
# Download all dependencies (no compilation yet)
+cargo fetch
+
+# This may take 2-3 minutes depending on internet speed
+
+

Step 5: Verify Workspace Structure

+
# Verify all crates are present
+ls -la crates/
+
+# Expected output (8 crates):
+# vapora-agents/
+# vapora-backend/
+# vapora-doc-lifecycle/
+# vapora-frontend/
+# vapora-llm-router/
+# vapora-mcp-server/
+# vapora-shared/
+# vapora-tracking/
+
+
+

Configuration

+ +

The project works out of the box with sensible defaults:

+
# Default Settings
+Backend:
+  port: 3000
+  host: 127.0.0.1
+  env: development
+
+Database:
+  type: SQLite (local)
+  path: ~/.vapora/data.db
+
+Tracking:
+  database: ~/.tracking/database.sqlite
+  watch_dirs:
+    - .coder/
+    - ~/.claude/todos/
+  debounce_ms: 500
+
+LLM Router:
+  default_providers:
+    - claude3-opus
+    - gpt-4
+    - gemini-2-pro
+  fallback_enabled: true
+
+Frontend:
+  port: 8080
+  hot_reload: true
+
+

No configuration needed to start developing! Skip to Building & Testing.

+

Option 2: Environment Variables

+

Create .env file in project root:

+
# Backend Configuration
+VAPORA_PORT=3000
+VAPORA_HOST=127.0.0.1
+RUST_ENV=development
+RUST_LOG=debug
+
+# Database
+VAPORA_DATABASE_URL=sqlite:///Users/Akasha/.vapora/data.db
+DATABASE_MAX_CONNECTIONS=5
+
+# Tracking System
+TRACKING_DATABASE_URL=sqlite:///Users/Akasha/.tracking/database.sqlite
+TRACKING_API_PORT=3000
+TRACKING_WATCH_DIRS=/Users/Akasha/.coder,/Users/Akasha/.claude/todos
+TRACKING_DEBOUNCE_MS=500
+
+# LLM Configuration
+LLM_DEFAULT_PROVIDER=claude-opus
+LLM_FALLBACK_ENABLED=true
+OPENAI_API_KEY=your_key_here
+ANTHROPIC_API_KEY=your_key_here
+GOOGLE_API_KEY=your_key_here
+
+# Frontend
+FRONTEND_PORT=8080
+FRONTEND_HOT_RELOAD=true
+
+# Logging
+LOG_LEVEL=debug
+LOG_FORMAT=json
+
+

Load with:

+
export $(cat .env | xargs)
+
+

Option 3: Configuration File

+

Create ~/.vapora/config.toml:

+
[server]
+port = 3000
+host = "127.0.0.1"
+environment = "development"
+
+[database]
+url = "sqlite:///Users/Akasha/.vapora/data.db"
+max_connections = 5
+timeout_seconds = 5
+
+[tracking]
+database_url = "sqlite:///Users/Akasha/.tracking/database.sqlite"
+api_port = 3000
+watch_dirs = [
+    "/Users/Akasha/.coder",
+    "/Users/Akasha/.claude/todos"
+]
+debounce_ms = 500
+
+[llm_router]
+default_provider = "claude-opus"
+fallback_enabled = true
+
+[frontend]
+port = 8080
+hot_reload = true
+
+[logging]
+level = "debug"
+format = "json"
+file = "/tmp/vapora.log"
+
+
+

Building & Testing

+

Phase 1: Build All Crates

+
# Build all crates in workspace (dev mode)
+cargo build
+
+# Build time: 3-8 minutes (first time)
+# Subsequent builds: 10-30 seconds
+
+# For optimized release build (slower to build, faster runtime)
+cargo build --release
+
+# Build time: 5-15 minutes (first time)
+
+

Phase 2: Run Full Test Suite

+
# Run all tests
+cargo test --lib
+
+# Expected output:
+# test result: ok. XXX passed; 0 failed; 0 ignored; 0 measured
+
+# Run tests for specific crate
+cargo test -p vapora-tracking --lib
+cargo test -p vapora-backend --lib
+cargo test -p vapora-agents --lib
+
+# Run tests with output
+cargo test --lib -- --nocapture --test-threads=1
+
+# Run specific test
+cargo test test_health_endpoint -- --exact
+
+

Phase 3: Code Quality Checks

+
# Format code
+cargo fmt
+
+# Check formatting without modifying
+cargo fmt -- --check
+
+# Lint with clippy
+cargo clippy --all-targets --all-features -- -W clippy::all
+
+# Run both format and clippy
+cargo fmt && cargo clippy --all-targets --all-features -- -W clippy::all
+
+

Phase 4: Documentation

+
# Generate documentation for all crates
+cargo doc --no-deps --open
+
+# Generate for specific crate
+cargo doc -p vapora-tracking --no-deps --open
+
+# Check documentation coverage
+cargo doc --document-private-items
+
+

Verification Checklist

+
#!/bin/bash
+set -e
+
+echo "🔍 Running Vapora verification..."
+echo "=================================="
+
+# Build
+echo "1. Building workspace..."
+cargo build 2>&1 | tail -3
+echo "✅ Build successful"
+
+# Tests
+echo "2. Running tests..."
+cargo test --lib 2>&1 | grep "test result"
+echo "✅ Tests passed"
+
+# Clippy
+echo "3. Running clippy..."
+cargo clippy --all-targets --all-features 2>&1 | grep -v "warning:" | tail -1
+echo "✅ Code quality checks passed"
+
+# Format
+echo "4. Checking format..."
+cargo fmt -- --check 2>&1 && echo "✅ Code is properly formatted" || echo "⚠️ Code needs formatting"
+
+echo "=================================="
+echo "✅ Verification complete!"
+
+
+

Development Setup

+

IDE Setup

+

VS Code (Recommended)

+
# Install recommended extensions
+# 1. rust-analyzer (rust-lang.rust-analyzer)
+# 2. CodeLLDB (vadimcn.vscode-lldb)
+# 3. Even Better TOML (tamasfe.even-better-toml)
+# 4. Leptos (Leptos)
+
+# .vscode/settings.json
+{
+  "[rust]": {
+    "editor.formatOnSave": true,
+    "editor.defaultFormatter": "rust-lang.rust-analyzer"
+  },
+  "rust-analyzer.inlayHints.enable": true,
+  "rust-analyzer.lens.enable": true
+}
+
+

IntelliJ IDEA / CLion

+
# Install Rust plugin
+# Settings → Plugins → Rust → Install
+
+# Recommended settings:
+# Rust → Clippy → Use Clippy instead of Cargo check
+# Rust → Macro Expansion → Expand experimental attribute macros
+
+

Git Setup

+
# Clone pre-commit hooks (if available)
+git clone https://github.com/vapora/hooks .git/hooks
+
+# Or create basic hook:
+cat > .git/hooks/pre-commit << 'EOF'
+#!/bin/bash
+cargo fmt --check && cargo clippy --all -- -W clippy::all
+EOF
+
+chmod +x .git/hooks/pre-commit
+
+

Development Workflow

+
# 1. Create feature branch
+git checkout -b feat/my-feature
+
+# 2. Make changes and build
+cargo build
+
+# 3. Run tests
+cargo test --lib
+
+# 4. Check code quality
+cargo fmt
+cargo clippy --all -- -W clippy::all
+
+# 5. Commit and push
+git add .
+git commit -m "feat: implement my-feature"
+git push origin feat/my-feature
+
+# 6. Create pull request
+
+
+

First Run

+

Run Backend Server

+

Terminal 1: Backend

+
# Run backend
+cargo run -p vapora-backend
+
+# With debug logging
+RUST_LOG=debug cargo run -p vapora-backend
+
+# Expected output:
+# 🚀 Vapora Backend Server
+# Listening on http://127.0.0.1:3000
+# Available endpoints:
+#   GET    /api/v1/health
+#   GET    /api/v1/tracking/summary
+#   POST   /api/v1/agents/orchestrate
+
+

Run Frontend (Optional)

+

Terminal 2: Frontend

+
cd crates/vapora-frontend
+
+# Install trunk (if not already)
+cargo install trunk
+
+# Run frontend with hot-reload
+trunk serve
+
+# Expected output:
+# 🦕 Listening on http://127.0.0.1:8080
+
+

Test Endpoints

+

Terminal 3: Test

+
# Health check
+curl http://localhost:3000/api/v1/health
+# Response: {"status":"ok","service":"vapora-backend",...}
+
+# Tracking summary
+curl http://localhost:3000/api/v1/tracking/summary
+# Response: {"total_entries":0,"changes":0,"todos":0}
+
+# Create tracking entry
+curl -X POST http://localhost:3000/api/v1/tracking/entries \
+  -H "Content-Type: application/json" \
+  -d '{"summary":"First entry","impact":"backend"}'
+
+

Using CLI Commands

+
# Start tracking service (if using local service)
+./scripts/start-tracking-service.nu --verbose
+
+# Log a change
+/log-change "Completed setup" --impact infrastructure --files 1
+
+# Create a TODO
+/add-todo "Review tracking system" --priority H --estimate M
+
+# Check status
+/track-status --limit 10
+
+# Export data
+./scripts/export-tracking.nu json --output setup-report.json
+
+
+

Troubleshooting

+

Build Issues

+

Error: "error[E0433]: failed to resolve: use of undeclared type"

+

Solution:

+
# Update Rust
+rustup update stable
+
+# Clean cache
+cargo clean
+
+# Rebuild
+cargo build
+
+

Error: "could not compile ... due to X previous errors"

+

Solution:

+
# Check Rust version (must be 1.75+)
+rustc --version
+
+# Update if needed
+rustup install 1.75
+rustup default 1.75
+
+

Error: "linker 'cc' not found"

+

Solution (macOS):

+
# Install Xcode command line tools
+xcode-select --install
+
+

Test Issues

+

Tests fail with timeout

+

Solution:

+
# Run with single thread
+cargo test --lib -- --test-threads=1
+
+# Increase timeout
+RUST_TEST_TIME_UNIT=60000 cargo test --lib
+
+

Tests panic with "thread 'main' panicked"

+

Solution:

+
# Run with backtrace
+RUST_BACKTRACE=1 cargo test --lib -- --nocapture
+
+# Check logs for actual error
+RUST_LOG=trace cargo test --lib -- --nocapture
+
+

Database Issues

+

Error: "database file not found"

+

Solution:

+
# Create database directory
+mkdir -p ~/.tracking
+mkdir -p ~/.vapora
+
+# Initialize databases
+./scripts/start-tracking-service.nu
+
+# Wait for init and stop with Ctrl+C
+
+

Error: "Failed to acquire database lock"

+

Solution:

+
# Ensure only one instance is running
+lsof | grep database.sqlite
+
+# Kill any lingering processes
+pkill -f "vapora-backend"
+pkill -f "tracking-service"
+
+# Restart
+cargo run -p vapora-backend
+
+

Port Already in Use

+

Error: "Address already in use"

+

Solution:

+
# Find process using port 3000
+lsof -i :3000
+
+# Kill process
+kill -9 <PID>
+
+# Or use different port
+VAPORA_PORT=3001 cargo run -p vapora-backend
+
+

NuShell Script Issues

+

Error: "command not found: nu"

+

Solution:

+
# Install NuShell
+brew install nu
+
+# Or add to PATH
+export PATH="/usr/local/bin:$PATH"
+
+

Scripts not executable

+

Solution:

+
# Make scripts executable
+chmod +x scripts/*.nu
+
+# Run with nu explicitly
+nu scripts/start-tracking-service.nu
+
+

Frontend Issues

+

Error: "trunk: command not found"

+

Solution:

+
# Install trunk
+cargo install trunk
+
+# Install WASM target
+rustup target add wasm32-unknown-unknown
+
+

Frontend won't load styles

+

Solution:

+
# Clear build cache
+rm -rf crates/vapora-frontend/target
+rm -rf crates/vapora-frontend/dist
+
+# Rebuild
+cd crates/vapora-frontend && trunk serve
+
+

Quick Troubleshooting Reference

+
+ + + + + + + + +
ProblemQuick Fix
Build failscargo clean && cargo build
Tests failrustup update && cargo test --lib
Port in uselsof -i :3000 && kill -9 <PID>
DB errorsrm ~/.vapora/data.db && cargo run
NuShell missingbrew install nu
Clippy warningscargo clippy -- -W clippy::all
Format issuescargo fmt
Slow buildexport CARGO_INCREMENTAL=1
+
+
+

Verification Steps

+

Post-Installation Verification

+
#!/bin/bash
+
+echo "🔍 Post-installation verification..."
+echo "===================================="
+
+# 1. Check Rust
+echo "1. Checking Rust..."
+rustc --version | grep -q "1\.[0-9]\+\.[0-9]\+" && echo "✅ Rust OK" || echo "❌ Rust issue"
+
+# 2. Check build
+echo "2. Building..."
+cargo build 2>&1 | grep -q "Finished" && echo "✅ Build OK" || echo "❌ Build failed"
+
+# 3. Check tests
+echo "3. Testing..."
+cargo test --lib 2>&1 | grep -q "test result: ok" && echo "✅ Tests OK" || echo "❌ Tests failed"
+
+# 4. Check code quality
+echo "4. Code quality..."
+cargo clippy --all 2>&1 | grep -v "warning:" | tail -1 | grep -q "error" && echo "❌ Clippy issues" || echo "✅ Code quality OK"
+
+# 5. Check structure
+echo "5. Project structure..."
+[ -f "Cargo.toml" ] && [ -d "crates" ] && echo "✅ Structure OK" || echo "❌ Structure issue"
+
+echo "===================================="
+echo "✅ Verification complete!"
+
+
+

What's Next?

+

Immediate Next Steps

+
    +
  1. Read QUICKSTART.md for 15-minute quick start
    2. +
  2. Run backend: cargo run -p vapora-backend
    3. +
  3. Visit frontend: http://localhost:8080
    4. +
  4. Create first tracking entry: /log-change "Setup complete"
    5. +
+

Learning Resources

+ +

Development Tips

+
    +
  • Use cargo watch for continuous building
    • +
  • Set RUST_LOG=debug for detailed logs
    • +
  • Use IDE debugging (VS Code + CodeLLDB)
    • +
  • Join community for help
    • +
+
+

Getting Help

+

Issues not listed above?

+
    +
  1. Check crate-specific documentation: cargo doc --open
    2. +
  2. Review .coder/ documentation for architecture
    3. +
  3. Check inline code comments
    4. +
  4. Run with RUST_LOG=trace for detailed logs
    5. +
  5. See QUICKSTART.md for quick reference
    6. +
+
+

✅ Setup Completion Checklist

+
    +
  • +Rust 1.75+ installed
    • +
  • +All prerequisites verified
    • +
  • +Repository cloned
    • +
  • +Dependencies downloaded (cargo fetch)
    • +
  • +Workspace builds successfully (cargo build)
    • +
  • +All tests pass (cargo test --lib)
    • +
  • +Code quality checks pass (cargo clippy)
    • +
  • +Backend runs (cargo run -p vapora-backend)
    • +
  • +Frontend loads (optional)
    • +
  • +Tracking system works (/track-status)
    • +
+

All checked? ✅ Vapora is ready for development!

+
+

For quick 15-minute setup: See QUICKSTART.md

+

For tracking system setup: See SETUP_TRACKING.md

+ +
+ + +
+
+ + + +
+ + + + + + + + + + + + + + + + + + +
+ + diff --git a/docs/setup/setup-guide.md b/docs/setup/setup-guide.md index 61cebd3..ce6519f 100644 --- a/docs/setup/setup-guide.md +++ b/docs/setup/setup-guide.md @@ -745,7 +745,7 @@ echo "✅ Verification complete!" --- -## What's Next? +## What's Next ### Immediate Next Steps 1. Read [`QUICKSTART.md`](./QUICKSTART.md) for 15-minute quick start diff --git a/docs/setup/tracking-quickstart.html b/docs/setup/tracking-quickstart.html new file mode 100644 index 0000000..4b1899e --- /dev/null +++ b/docs/setup/tracking-quickstart.html @@ -0,0 +1,435 @@ + + + + + + Tracking Quickstart - VAPORA Platform Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+

Keyboard shortcuts

+
+

Press ← or → to navigate between chapters

+

Press S or / to search in the book

+

Press ? to show this help

+

Press Esc to hide this help

+
+
+
+
+ + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+
+
+

title: Vapora Tracking System - Quick Start Guide +date: 2025-11-10 +status: READY +type: tracking-quickstart

+

🚀 Vapora Tracking System - Quick Start Guide

+

⏱️ Time to get running: 5-10 minutes

+

This guide walks you through installing and getting started with the Vapora tracking system component in the simplest way possible.

+

Note: This guide is for the tracking system only. For complete Vapora project setup, see QUICKSTART.md.

+
+

📋 Prerequisites

+

You need:

+
    +
  • ✅ Rust 1.70+ (install from https://rustup.rs)
    • +
  • ✅ Cargo (comes with Rust)
    • +
  • ✅ Git
    • +
  • ✅ 500MB free disk space
    • +
  • ✅ Bash or Zsh shell
    • +
+

Check if you have everything:

+
rustc --version    # Should show Rust 1.70+
+cargo --version    # Should show Cargo 1.70+
+which git          # Should show /usr/bin/git or similar
+
+
+

🎯 5-Minute Quick Start

+

Step 1: Build the Tracking System

+
# Build the tracking crate
+cargo build -p vapora-tracking
+
+# Or with backend integration
+cargo build -p vapora-backend
+
+

Expected output:

+
    Finished `dev` profile [unoptimized + debuginfo] target(s) in X.XXs
+
+

Step 3: Run Tests

+
# Verify everything works
+cargo test -p vapora-tracking --lib
+
+# Should show: test result: ok. 20 passed
+
+

Step 4: Start Using It

+

Option A: Using Slash Commands (Easiest)

+
# In Claude Code, use the commands:
+/log-change "Fixed bug in parser" --impact backend --files 3
+/add-todo "Refactor database" --priority H --estimate M
+/track-status --project vapora --limit 10
+
+

Option B: Using Scripts (Manual Sync)

+
# Start the tracking service
+./scripts/start-tracking-service.nu --verbose
+
+# In another terminal, sync projects (replace with your development directory)
+./scripts/sync-tracking.nu --projects-dir ~ --verbose
+
+# Check status
+/track-status
+
+

Option C: Using API (Integration)

+
# Query the API
+curl http://localhost:3000/api/v1/tracking/summary
+curl http://localhost:3000/api/v1/tracking/entries?limit=10
+
+
+

✅ Verify Installation

+

After building, verify everything works:

+

Test 1: Build Success

+
cargo build -p vapora-tracking 2>&1 | tail -3
+# Should show: Finished `dev` profile [unoptimized + debuginfo]
+
+

Test 2: Tests Pass

+
cargo test -p vapora-tracking --lib 2>&1 | grep "test result"
+# Should show: test result: ok. 20 passed; 0 failed
+
+

Test 3: Clippy Clean

+
cargo clippy -p vapora-tracking --lib 2>&1 | grep "warning:" | wc -l
+# Should show: 1 (profile warning only, which is expected)
+
+

Test 4: Commands Available

+
ls ~/.claude/commands/ | grep -E "log-change|add-todo|track-status"
+# Should show all 3 commands
+
+

Test 5: Skill Available

+
ls ~/.claude/skills/tracking.md
+# Should show the file exists
+
+

If all 5 tests pass: ✅ Installation Complete!

+
+

🎬 First Time Usage

+

Scenario 1: Log Your First Change

+

Using Slash Command (Easiest):

+
/log-change "Implemented user authentication" \
+  --impact backend \
+  --files 5
+
+

What happens:

+
    +
  1. ✅ Change is logged to database
    2. +
  2. ✅ Timestamp added automatically
    3. +
  3. ✅ Can be queried with /track-status
    4. +
+

Scenario 2: Create Your First TODO

+

Using Slash Command:

+
/add-todo "Review code changes" \
+  --priority H \
+  --estimate M \
+  --due 2025-11-15
+
+

What happens:

+
    +
  1. ✅ TODO created in database
    2. +
  2. ✅ Can be tracked with /track-status
    3. +
  3. ✅ Shows up in exports
    4. +
+

Scenario 3: Check Your Status

+

Using Slash Command:

+
/track-status --limit 5
+
+

Output:

+
✅ Summary
+Total entries: 3
+Changes: 1
+TODOs: 2
+
+🔄 Changes
+[2025-11-10T14:30:00Z] - Implemented user authentication
+Impact: backend | Breaking: no | Files: 5
+
+📋 TODOs
+[HIGH] Review code changes (Medium) - Due: 2025-11-15
+[HIGH] Write documentation (Small) - Due: 2025-11-12
+
+
+

📚 Next Steps After Installation

+

Short Term (Today)

+
    +
  1. ✅ Log 2-3 changes you've made
    2. +
  2. ✅ Create 2-3 TODOs for upcoming work
    3. +
  3. ✅ Run /track-status to see results
    4. +
+

Medium Term (This Week)

+
    +
  1. 📝 Set up daily tracking in your workflow
    2. +
  2. 🔄 Sync multiple projects with sync-tracking.nu
    3. +
  3. 📊 Export your tracking data with export-tracking.nu
    4. +
+

Long Term (Ongoing)

+
    +
  1. 📈 Monitor project progress via /track-status
    2. +
  2. 🎯 Use for sprint planning and retrospectives
    3. +
  3. 📉 Generate reports from exported data
    4. +
  4. 🔗 Integrate with other Vapora services
    5. +
+
+

🆘 Need More Help?

+
+ + + + + +
QuestionAnswer Location
How do I use the tracking system?TRACKING_SYSTEM_STATUS.md (How to use section)
What are all the features?crates/vapora-tracking/README.md (Features section)
How do I deploy it?crates/vapora-tracking/INTEGRATION.md (Deployment section)
How do I fix an issue?SETUP_TRACKING.md (Troubleshooting section)
What's the architecture?TRACKING_DOCUMENTATION_INDEX.md
+
+
+

⚡ Super Quick Reference

+
# Build
+cargo build -p vapora-tracking
+
+# Test
+cargo test -p vapora-tracking --lib
+
+# Use commands
+/log-change "Summary" --impact backend
+/add-todo "Task" --priority H --estimate M
+/track-status --limit 10
+
+# Use scripts
+./scripts/sync-tracking.nu --verbose
+./scripts/export-tracking.nu json --output report
+./scripts/start-tracking-service.nu
+
+# Query API
+curl http://localhost:3000/api/v1/tracking/summary
+
+
+

✅ Installation Checklist

+
    +
  • +Rust 1.75+ installed
    • +
  • +Vapora repo available
    • +
  • +cargo build -p vapora-tracking succeeds
    • +
  • +cargo test -p vapora-tracking --lib shows 20 passed
    • +
  • +Slash commands copied to ~/.claude/commands/
    • +
  • +Skill copied to ~/.claude/skills/
    • +
  • +/log-change command works
    • +
  • +/track-status shows results
    • +
+

All checked? ✅ You're ready to go!

+
+

For complete Vapora project setup: See QUICKSTART.md

+

For tracking system deep dive: See SETUP_TRACKING.md

+ +
+ + +
+
+ + + +
+ + + + + + + + + + + + + + + + + + +
+ + diff --git a/docs/setup/tracking-quickstart.md b/docs/setup/tracking-quickstart.md index 03beb7f..c589f0c 100644 --- a/docs/setup/tracking-quickstart.md +++ b/docs/setup/tracking-quickstart.md @@ -202,7 +202,7 @@ Impact: backend | Breaking: no | Files: 5 --- -## 🆘 Need More Help? +## 🆘 Need More Help | Question | Answer Location | |----------|-----------------| diff --git a/docs/setup/tracking-setup.html b/docs/setup/tracking-setup.html new file mode 100644 index 0000000..97ea8f9 --- /dev/null +++ b/docs/setup/tracking-setup.html @@ -0,0 +1,774 @@ + + + + + + Tracking Setup - VAPORA Platform Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+

Keyboard shortcuts

+
+

Press ← or → to navigate between chapters

+

Press S or / to search in the book

+

Press ? to show this help

+

Press Esc to hide this help

+
+
+
+
+ + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+
+
+

title: Vapora Tracking System - Complete Setup Guide +date: 2025-11-10 +version: 1.0

+

🛠️ Vapora Tracking System - Complete Setup Guide

+

This guide covers everything from zero to fully operational tracking system.

+
+

📋 Table of Contents

+
    +
  1. Prerequisites
    2. +
  2. Installation
    3. +
  3. Configuration
    4. +
  4. Verification
    5. +
  5. First Use
    6. +
  6. Troubleshooting
    7. +
+
+

Prerequisites

+

System Requirements

+
+ + + + +
RequirementMinimumRecommended
OSmacOS 10.15+macOS 12+
RAM2GB4GB+
Disk1GB2GB+
InternetRequired for installRequired
+
+

Software Requirements

+
# Check if installed
+rustc --version    # Need 1.70+
+cargo --version    # Comes with Rust
+git --version      # Need 2.20+
+
+

Installation Check

+
#!/bin/bash
+echo "Checking prerequisites..."
+
+# Check Rust
+if ! command -v rustc &> /dev/null; then
+    echo "❌ Rust not found. Install from https://rustup.rs"
+    exit 1
+fi
+
+# Check Cargo
+if ! command -v cargo &> /dev/null; then
+    echo "❌ Cargo not found. Install Rust from https://rustup.rs"
+    exit 1
+fi
+
+# Check Rust version
+RUST_VERSION=$(rustc --version | awk '{print $2}')
+echo "✅ Rust $RUST_VERSION found"
+echo "✅ All prerequisites met!"
+
+
+

Installation

+

Step 1: Install Rust (if needed)

+
# Download and install Rust
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+
+# Follow the prompts (default options are fine)
+
+# Add Rust to PATH
+source $HOME/.cargo/env
+
+# Verify installation
+rustc --version
+cargo --version
+
+

Expected output:

+
rustc 1.XX.X (XXXXXXXXXXXX YYYY-MM-DD)
+cargo 1.XX.X (XXXXXXXXXXXX YYYY-MM-DD)
+
+

Step 2: Clone or Navigate to Vapora

+
# Option A: Clone (if you don't have it)
+git clone https://github.com/yourusername/vapora.git
+cd vapora
+
+# Option B: Navigate (if you already have it)
+cd vapora
+
+# Verify structure
+ls crates/vapora-tracking/
+# Should show: Cargo.toml, README.md, src/, benches/
+
+

Step 3: Build the Tracking System

+
# Build tracking crate
+cargo build -p vapora-tracking
+
+# Output should show:
+# Compiling vapora-tracking v0.1.0
+# Finished `dev` profile [unoptimized + debuginfo]
+
+# For faster runtime (slower build):
+cargo build -p vapora-tracking --release
+
+# Output should show:
+# Finished `release` profile [optimized]
+
+

Build time:

+
    +
  • Debug: 30-60 seconds (first time)
    • +
  • Release: 2-5 minutes (first time)
    • +
  • Subsequent: 1-10 seconds (incremental)
    • +
+

Step 4: Verify Build

+
# List build artifacts
+ls -lh target/debug/deps/ | grep vapora_tracking
+
+# Should show several .rlib and other files
+
+# Or with release build
+ls -lh target/release/deps/ | grep vapora_tracking
+
+

Step 5: Install CLI Components

+
# Create commands directory if it doesn't exist
+mkdir -p ~/.claude/commands
+mkdir -p ~/.claude/skills
+
+# Copy tracking commands
+cp ~/.claude/commands/log-change.md ~/.claude/commands/
+cp ~/.claude/commands/add-todo.md ~/.claude/commands/
+cp ~/.claude/commands/track-status.md ~/.claude/commands/
+
+# Copy tracking skill
+cp ~/.claude/skills/tracking.md ~/.claude/skills/
+
+# Verify installation
+ls -la ~/.claude/commands/ | grep -E "log-change|add-todo|track-status"
+ls -la ~/.claude/skills/ | grep tracking
+
+
+

Configuration

+ +

The system works out of the box with defaults:

+
# Default database location
+~/.tracking/database.sqlite
+
+# Default watch directories
+~/.coder/
+~/.claude/todos/
+
+# Default API port
+3000
+
+

No configuration needed! Skip to Verification.

+

Option 2: Custom Configuration

+

Create ~/.config/vapora-tracking.toml:

+
[database]
+# SQLite database path (use your home directory)
+url = "sqlite://~/.tracking/database.sqlite"
+
+# Max connections to database
+max_connections = 5
+
+# Connection timeout (seconds)
+timeout = 5
+
+[watcher]
+# Directories to watch for changes (customize for your setup)
+watch_dirs = [
+    "~/.coder",
+    "~/.claude/todos"
+]
+
+# Debounce time (milliseconds)
+debounce_ms = 500
+
+[api]
+# API server port
+port = 3000
+
+# API host
+host = "127.0.0.1"
+
+[logging]
+# Log level: trace, debug, info, warn, error
+level = "info"
+
+# Log file path
+file = "/tmp/vapora-tracking.log"
+
+

Option 3: Environment Variables

+
# Set database location (use your home directory)
+export TRACKING_DATABASE_URL="sqlite://~/.tracking/database.sqlite"
+
+# Set API port
+export TRACKING_API_PORT=3000
+
+# Set log level
+export RUST_LOG=info
+
+# These override config file values
+
+
+

Verification

+

Test 1: Build Success

+
# Clean rebuild to verify
+cargo clean -p vapora-tracking
+cargo build -p vapora-tracking
+
+# Check for success
+if [ $? -eq 0 ]; then
+    echo "✅ Build successful"
+else
+    echo "❌ Build failed"
+    exit 1
+fi
+
+

Test 2: Tests Pass

+
# Run all unit tests
+cargo test -p vapora-tracking --lib
+
+# Expected output:
+# running 20 tests
+# ...
+# test result: ok. 20 passed; 0 failed
+
+

If not 20 tests:

+
# Check what tests exist
+cargo test -p vapora-tracking --lib -- --list
+
+# Run with output for debugging
+cargo test -p vapora-tracking --lib -- --nocapture
+
+

Test 3: Code Quality

+
# Run clippy checks
+cargo clippy -p vapora-tracking --lib -- -W clippy::all
+
+# Should show minimal warnings (profile warning is expected)
+
+

Test 4: CLI Commands

+
# Verify commands are installed
+ls ~/.claude/commands/
+
+# Output should include:
+# add-todo.md
+# log-change.md
+# track-status.md
+
+# Verify skill
+ls ~/.claude/skills/tracking.md
+
+

Test 5: API Health

+
# Start service
+./scripts/start-tracking-service.nu
+
+# Wait 2 seconds
+sleep 2
+
+# Check health endpoint
+curl http://localhost:3000/api/v1/tracking/health
+
+# Expected output:
+# {"status":"ok","service":"vapora-tracking","timestamp":"2025-11-10T..."}
+
+

Verification Checklist

+
# Run all verifications
+echo "Running verification tests..."
+
+# Test 1: Build
+cargo build -p vapora-tracking 2>&1 | grep -q "Finished"
+[ $? -eq 0 ] && echo "✅ Build" || echo "❌ Build"
+
+# Test 2: Tests
+cargo test -p vapora-tracking --lib 2>&1 | grep -q "20 passed"
+[ $? -eq 0 ] && echo "✅ Tests" || echo "❌ Tests"
+
+# Test 3: Clippy
+cargo clippy -p vapora-tracking --lib 2>&1 | grep -q "error:" && echo "❌ Clippy" || echo "✅ Clippy"
+
+# Test 4: Commands
+[ -f ~/.claude/commands/log-change.md ] && echo "✅ Commands" || echo "❌ Commands"
+
+# Test 5: Skills
+[ -f ~/.claude/skills/tracking.md ] && echo "✅ Skills" || echo "❌ Skills"
+
+echo "Verification complete!"
+
+
+

First Use

+

Your First Change Log

+
# Log your first change
+/log-change "Set up Vapora tracking system" \
+  --impact infrastructure \
+  --files 1
+
+# Expected response: Change logged successfully
+
+

Your First TODO

+
# Create your first TODO
+/add-todo "Review tracking system documentation" \
+  --priority M \
+  --estimate S \
+  --due 2025-11-12
+
+# Expected response: TODO created successfully
+
+

Your First Status Check

+
# Check current status
+/track-status --limit 5
+
+# Expected output shows your 1 change and 1 TODO
+
+

Your First Export

+
# Export to JSON
+./scripts/export-tracking.nu json --output tracking-report
+
+# Export to Markdown
+./scripts/export-tracking.nu markdown --project vapora > report.md
+
+# Check results
+ls -la tracking-report.json
+cat report.md
+
+
+

Troubleshooting

+

Build Issues

+

Issue: "error[E0433]: failed to resolve"

+

Solution:

+
# Update Rust
+rustup update
+
+# Clean and rebuild
+cargo clean -p vapora-tracking
+cargo build -p vapora-tracking
+
+

Issue: "could not compile ... due to X previous errors"

+

Solution:

+
# Check Rust version
+rustc --version  # Must be 1.70+
+
+# Update if needed
+rustup install stable
+
+# Verify dependencies
+cargo tree -p vapora-tracking
+
+

Database Issues

+

Issue: "Database file not found"

+

Solution:

+
# Create database directory
+mkdir -p ~/.tracking
+
+# Start service to initialize
+./scripts/start-tracking-service.nu
+
+# Check database was created
+ls -la ~/.tracking/
+
+

Issue: "Failed to initialize database"

+

Solution:

+
# Reset database
+rm ~/.tracking/database.sqlite
+
+# Service will recreate on next start
+./scripts/start-tracking-service.nu
+
+

CLI Issues

+

Issue: "/log-change not found" in Claude Code

+

Solution:

+
# Verify commands are copied
+ls ~/.claude/commands/log-change.md
+
+# If missing, copy them
+cp ~/.claude/commands/log-change.md ~/.claude/commands/
+
+# Restart Claude Code
+
+

Issue: "Command not recognized"

+

Solution:

+
# Check command format
+/log-change --help
+
+# Should show usage information
+# If not, commands aren't properly installed
+
+

API Issues

+

Issue: "Connection refused" when calling API

+

Solution:

+
# Start the service
+./scripts/start-tracking-service.nu --verbose
+
+# Wait for startup
+sleep 2
+
+# Check health
+curl -v http://localhost:3000/api/v1/tracking/health
+
+# Check logs
+tail -f /tmp/vapora-tracking.log
+
+

Issue: "Port 3000 already in use"

+

Solution:

+
# Use different port
+./scripts/start-tracking-service.nu --port 3001
+
+# Or kill existing service
+lsof -i :3000
+kill -9 <PID>
+
+

Performance Issues

+

Issue: Build is very slow

+

Solution:

+
# Use incremental compilation
+export CARGO_INCREMENTAL=1
+
+# Use faster linker (if available)
+export RUSTFLAGS="-C link-arg=-fuse-ld=lld"
+
+# Or just use release build once
+cargo build -p vapora-tracking --release
+
+

Issue: High memory usage

+

Solution:

+
# Limit parallel jobs during build
+cargo build -p vapora-tracking -j 2
+
+# Or reduce connection pool
+# Edit storage.rs: max_connections = 2
+
+
+

Quick Troubleshooting Reference

+
+ + + + + + + +
ProblemQuick Fix
Build failscargo clean && cargo build
Tests failrustup update then rebuild
Commands missingcp ~/.claude/commands/*
API won't start./scripts/start-tracking-service.nu --verbose
Database errorsrm ~/.tracking/database.sqlite
Port in use./scripts/start-tracking-service.nu --port 3001
Slow buildexport CARGO_INCREMENTAL=1
+
+
+

System Validation Script

+

Save this as validate-tracking.sh:

+
#!/bin/bash
+
+set -e
+
+echo "🔍 Validating Vapora Tracking System Installation"
+echo "=================================================="
+
+# Check Rust
+echo "Checking Rust..."
+if ! command -v rustc &> /dev/null; then
+    echo "❌ Rust not found"
+    exit 1
+fi
+echo "✅ Rust $(rustc --version | awk '{print $2}')"
+
+# Check build
+echo "Building tracking crate..."
+cargo build -p vapora-tracking 2>&1 | tail -3
+echo "✅ Build successful"
+
+# Check tests
+echo "Running tests..."
+TEST_OUTPUT=$(cargo test -p vapora-tracking --lib 2>&1)
+if echo "$TEST_OUTPUT" | grep -q "test result: ok. 20 passed"; then
+    echo "✅ All 20 tests passed"
+else
+    echo "❌ Tests failed"
+    exit 1
+fi
+
+# Check CLI
+echo "Checking CLI components..."
+[ -f ~/.claude/commands/log-change.md ] && echo "✅ Commands installed" || echo "⚠️ Commands not found"
+[ -f ~/.claude/skills/tracking.md ] && echo "✅ Skill installed" || echo "⚠️ Skill not found"
+
+# Check scripts
+echo "Checking scripts..."
+[ -f ./scripts/start-tracking-service.nu ] && echo "✅ Scripts available" || echo "⚠️ Scripts not found"
+
+echo ""
+echo "=================================================="
+echo "✅ Validation Complete - System Ready!"
+echo "=================================================="
+
+echo ""
+echo "Next steps:"
+echo "1. /log-change \"Your first change\""
+echo "2. /add-todo \"Your first task\""
+echo "3. /track-status"
+
+

Run it:

+
chmod +x validate-tracking.sh
+./validate-tracking.sh
+
+
+

What's Next After Setup?

+

Immediate (Today)

+
    +
  • +Complete all verification tests
    • +
  • +Create your first change log
    • +
  • +Create your first TODO
    • +
  • +Run your first status check
    • +
+

Short Term (This Week)

+
    +
  • +Use /log-change for actual changes
    • +
  • +Use /add-todo for tasks
    • +
  • +Explore /track-status filters
    • +
  • +Try exporting to different formats
    • +
+

Medium Term (This Month)

+
    +
  • +Set up automated syncing
    • +
  • +Create custom dashboard queries
    • +
  • +Integrate with your workflows
    • +
  • +Set up reports
    • +
+
+

Getting Help

+

Issue not listed above?

+
    +
  1. Check the TROUBLESHOOTING section in INTEGRATION.md
    2. +
  2. Review TRACKING_SYSTEM_STATUS.md
    3. +
  3. Check logs: tail -f /tmp/vapora-tracking.log
    4. +
  4. Read inline code documentation: cargo doc -p vapora-tracking --open
    5. +
+
+

Summary

+

You've successfully set up the Vapora tracking system!

+

What you now have:

+

✅ Built: vapora-tracking crate compiled and tested +✅ Verified: All 20 tests passing +✅ Installed: CLI commands and skill +✅ Running: Tracking service ready +✅ Configured: Database and API ready

+

Start using it:

+
/log-change "Example change" --impact backend
+/add-todo "Example task" --priority H
+/track-status
+
+

Happy tracking! 🚀

+ +
+ + +
+
+ + + +
+ + + + + + + + + + + + + + + + + + +
+ + diff --git a/docs/setup/tracking-setup.md b/docs/setup/tracking-setup.md index 77f818f..2a5dcdb 100644 --- a/docs/setup/tracking-setup.md +++ b/docs/setup/tracking-setup.md @@ -617,7 +617,7 @@ chmod +x validate-tracking.sh --- -## What's Next After Setup? +## What's Next After Setup ### Immediate (Today) - [ ] Complete all verification tests @@ -654,7 +654,7 @@ chmod +x validate-tracking.sh You've successfully set up the Vapora tracking system! -### What you now have: +### What you now have ✅ **Built:** vapora-tracking crate compiled and tested ✅ **Verified:** All 20 tests passing @@ -662,7 +662,7 @@ You've successfully set up the Vapora tracking system! ✅ **Running:** Tracking service ready ✅ **Configured:** Database and API ready -### Start using it: +### Start using it ```bash /log-change "Example change" --impact backend