chore: add setup md files
This commit is contained in:
Jesús Pérez
parent
ff98adba88
commit
4cbbf3f864
GPG Key ID:
9F243E355E0BC939
43
CHANGELOG.md
43
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
|
||||
|
||||
@ -14,7 +14,7 @@
|
||||
[](https://istio.io)
|
||||
[](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)
|
||||
|
||||
</div>
|
||||
|
||||
@ -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.
|
||||
|
||||
|
||||
389
docs/setup/deployment-quickstart.html
Normal file
389
docs/setup/deployment-quickstart.html
Normal file
@ -0,0 +1,389 @@
|
||||
<!DOCTYPE HTML>
|
||||
<html lang="en" class="light sidebar-visible" dir="ltr">
|
||||
<head>
|
||||
<!-- Book generated using mdBook -->
|
||||
<meta charset="UTF-8">
|
||||
<title>Deployment Quickstart - VAPORA Platform Documentation</title>
|
||||
|
||||
|
||||
<!-- Custom HTML head -->
|
||||
|
||||
<meta name="description" content="Comprehensive documentation for VAPORA, an intelligent development orchestration platform built entirely in Rust.">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
<meta name="theme-color" content="#ffffff">
|
||||
|
||||
<link rel="icon" href="../favicon.svg">
|
||||
<link rel="shortcut icon" href="../favicon.png">
|
||||
<link rel="stylesheet" href="../css/variables.css">
|
||||
<link rel="stylesheet" href="../css/general.css">
|
||||
<link rel="stylesheet" href="../css/chrome.css">
|
||||
<link rel="stylesheet" href="../css/print.css" media="print">
|
||||
|
||||
<!-- Fonts -->
|
||||
<link rel="stylesheet" href="../FontAwesome/css/font-awesome.css">
|
||||
<link rel="stylesheet" href="../fonts/fonts.css">
|
||||
|
||||
<!-- Highlight.js Stylesheets -->
|
||||
<link rel="stylesheet" id="highlight-css" href="../highlight.css">
|
||||
<link rel="stylesheet" id="tomorrow-night-css" href="../tomorrow-night.css">
|
||||
<link rel="stylesheet" id="ayu-highlight-css" href="../ayu-highlight.css">
|
||||
|
||||
<!-- Custom theme stylesheets -->
|
||||
|
||||
|
||||
<!-- Provide site root and default themes to javascript -->
|
||||
<script>
|
||||
const path_to_root = "../";
|
||||
const default_light_theme = "light";
|
||||
const default_dark_theme = "dark";
|
||||
</script>
|
||||
<!-- Start loading toc.js asap -->
|
||||
<script src="../toc.js"></script>
|
||||
</head>
|
||||
<body>
|
||||
<div id="mdbook-help-container">
|
||||
<div id="mdbook-help-popup">
|
||||
<h2 class="mdbook-help-title">Keyboard shortcuts</h2>
|
||||
<div>
|
||||
<p>Press <kbd>←</kbd> or <kbd>→</kbd> to navigate between chapters</p>
|
||||
<p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
|
||||
<p>Press <kbd>?</kbd> to show this help</p>
|
||||
<p>Press <kbd>Esc</kbd> to hide this help</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<div id="body-container">
|
||||
<!-- Work around some values being stored in localStorage wrapped in quotes -->
|
||||
<script>
|
||||
try {
|
||||
let theme = localStorage.getItem('mdbook-theme');
|
||||
let sidebar = localStorage.getItem('mdbook-sidebar');
|
||||
|
||||
if (theme.startsWith('"') && theme.endsWith('"')) {
|
||||
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
|
||||
}
|
||||
|
||||
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
|
||||
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
|
||||
}
|
||||
} catch (e) { }
|
||||
</script>
|
||||
|
||||
<!-- Set the theme before any content is loaded, prevents flash -->
|
||||
<script>
|
||||
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
|
||||
let theme;
|
||||
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
|
||||
if (theme === null || theme === undefined) { theme = default_theme; }
|
||||
const html = document.documentElement;
|
||||
html.classList.remove('light')
|
||||
html.classList.add(theme);
|
||||
html.classList.add("js");
|
||||
</script>
|
||||
|
||||
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
|
||||
|
||||
<!-- Hide / unhide sidebar before it is displayed -->
|
||||
<script>
|
||||
let sidebar = null;
|
||||
const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
|
||||
if (document.body.clientWidth >= 1080) {
|
||||
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
|
||||
sidebar = sidebar || 'visible';
|
||||
} else {
|
||||
sidebar = 'hidden';
|
||||
}
|
||||
sidebar_toggle.checked = sidebar === 'visible';
|
||||
html.classList.remove('sidebar-visible');
|
||||
html.classList.add("sidebar-" + sidebar);
|
||||
</script>
|
||||
|
||||
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
|
||||
<!-- populated by js -->
|
||||
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
|
||||
<noscript>
|
||||
<iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
|
||||
</noscript>
|
||||
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
|
||||
<div class="sidebar-resize-indicator"></div>
|
||||
</div>
|
||||
</nav>
|
||||
|
||||
<div id="page-wrapper" class="page-wrapper">
|
||||
|
||||
<div class="page">
|
||||
<div id="menu-bar-hover-placeholder"></div>
|
||||
<div id="menu-bar" class="menu-bar sticky">
|
||||
<div class="left-buttons">
|
||||
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
|
||||
<i class="fa fa-bars"></i>
|
||||
</label>
|
||||
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
|
||||
<i class="fa fa-paint-brush"></i>
|
||||
</button>
|
||||
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
|
||||
<li role="none"><button role="menuitem" class="theme" id="default_theme">Auto</button></li>
|
||||
<li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
|
||||
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
|
||||
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
|
||||
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
|
||||
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
|
||||
</ul>
|
||||
<button id="search-toggle" class="icon-button" type="button" title="Search (`/`)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="/ s" aria-controls="searchbar">
|
||||
<i class="fa fa-search"></i>
|
||||
</button>
|
||||
</div>
|
||||
|
||||
<h1 class="menu-title">VAPORA Platform Documentation</h1>
|
||||
|
||||
<div class="right-buttons">
|
||||
<a href="../print.html" title="Print this book" aria-label="Print this book">
|
||||
<i id="print-button" class="fa fa-print"></i>
|
||||
</a>
|
||||
<a href="https://github.com/vapora-platform/vapora" title="Git repository" aria-label="Git repository">
|
||||
<i id="git-repository-button" class="fa fa-github"></i>
|
||||
</a>
|
||||
<a href="https://github.com/vapora-platform/vapora/edit/main/docs/src/../setup/deployment-quickstart.md" title="Suggest an edit" aria-label="Suggest an edit">
|
||||
<i id="git-edit-button" class="fa fa-edit"></i>
|
||||
</a>
|
||||
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div id="search-wrapper" class="hidden">
|
||||
<form id="searchbar-outer" class="searchbar-outer">
|
||||
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
|
||||
</form>
|
||||
<div id="searchresults-outer" class="searchresults-outer hidden">
|
||||
<div id="searchresults-header" class="searchresults-header"></div>
|
||||
<ul id="searchresults">
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
|
||||
<script>
|
||||
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
|
||||
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
|
||||
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
|
||||
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
|
||||
});
|
||||
</script>
|
||||
|
||||
<div id="content" class="content">
|
||||
<main>
|
||||
<h1 id="vapora-v10---quick-start-deployment"><a class="header" href="#vapora-v10---quick-start-deployment">VAPORA v1.0 - Quick Start Deployment</a></h1>
|
||||
<p><strong>5-Minute Production Deployment Guide</strong></p>
|
||||
<hr />
|
||||
<h2 id="prerequisites-check"><a class="header" href="#prerequisites-check">Prerequisites Check</a></h2>
|
||||
<pre><code class="language-bash"># Verify you have these tools
|
||||
kubectl version --client # Kubernetes CLI
|
||||
docker --version # Docker for building images
|
||||
nu --version # Nushell for scripts
|
||||
</code></pre>
|
||||
<hr />
|
||||
<h2 id="step-1-build-docker-images-5-minutes"><a class="header" href="#step-1-build-docker-images-5-minutes">Step 1: Build Docker Images (5 minutes)</a></h2>
|
||||
<pre><code class="language-bash"># 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
|
||||
</code></pre>
|
||||
<p><strong>Output</strong>: 4 Docker images built (~175MB total)</p>
|
||||
<hr />
|
||||
<h2 id="step-2-configure-secrets-2-minutes"><a class="header" href="#step-2-configure-secrets-2-minutes">Step 2: Configure Secrets (2 minutes)</a></h2>
|
||||
<pre><code class="language-bash"># 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)
|
||||
</code></pre>
|
||||
<p><strong>NEVER commit this file with real secrets!</strong></p>
|
||||
<hr />
|
||||
<h2 id="step-3-configure-ingress-1-minute"><a class="header" href="#step-3-configure-ingress-1-minute">Step 3: Configure Ingress (1 minute)</a></h2>
|
||||
<pre><code class="language-bash"># Edit ingress file
|
||||
nano kubernetes/08-ingress.yaml
|
||||
|
||||
# Update this line:
|
||||
# - host: vapora.yourdomain.com # Change to your domain
|
||||
</code></pre>
|
||||
<hr />
|
||||
<h2 id="step-4-deploy-to-kubernetes-3-minutes"><a class="header" href="#step-4-deploy-to-kubernetes-3-minutes">Step 4: Deploy to Kubernetes (3 minutes)</a></h2>
|
||||
<pre><code class="language-bash"># 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
|
||||
</code></pre>
|
||||
<p><strong>Output</strong>: 11 pods running (2 backend, 2 frontend, 3 agents, 1 mcp, 1 db, 1 nats)</p>
|
||||
<hr />
|
||||
<h2 id="step-5-verify-deployment-2-minutes"><a class="header" href="#step-5-verify-deployment-2-minutes">Step 5: Verify Deployment (2 minutes)</a></h2>
|
||||
<pre><code class="language-bash"># 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
|
||||
</code></pre>
|
||||
<hr />
|
||||
<h2 id="step-6-access-vapora"><a class="header" href="#step-6-access-vapora">Step 6: Access VAPORA</a></h2>
|
||||
<ol>
|
||||
<li><strong>Configure DNS</strong>: Point your domain to ingress IP</li>
|
||||
<li><strong>Access UI</strong>: <code>https://vapora.yourdomain.com</code></li>
|
||||
<li><strong>Check health</strong>: <code>https://vapora.yourdomain.com/api/v1/health</code></li>
|
||||
</ol>
|
||||
<hr />
|
||||
<h2 id="troubleshooting"><a class="header" href="#troubleshooting">Troubleshooting</a></h2>
|
||||
<h3 id="pods-not-starting"><a class="header" href="#pods-not-starting">Pods not starting?</a></h3>
|
||||
<pre><code class="language-bash">kubectl describe pod -n vapora <pod-name>
|
||||
kubectl logs -n vapora <pod-name>
|
||||
</code></pre>
|
||||
<h3 id="cant-connect-to-database"><a class="header" href="#cant-connect-to-database">Can't connect to database?</a></h3>
|
||||
<pre><code class="language-bash">kubectl logs -n vapora surrealdb-0
|
||||
kubectl exec -n vapora deploy/vapora-backend -- curl http://surrealdb:8000/health
|
||||
</code></pre>
|
||||
<h3 id="image-pull-errors"><a class="header" href="#image-pull-errors">Image pull errors?</a></h3>
|
||||
<pre><code class="language-bash"># 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>
|
||||
</code></pre>
|
||||
<hr />
|
||||
<h2 id="alternative-provisioning-deployment"><a class="header" href="#alternative-provisioning-deployment">Alternative: Provisioning Deployment</a></h2>
|
||||
<p>For advanced deployment with service mesh and auto-scaling:</p>
|
||||
<pre><code class="language-bash">cd provisioning/vapora-wrksp
|
||||
|
||||
# Validate configuration
|
||||
nu scripts/validate-provisioning.nu
|
||||
|
||||
# Deploy full stack
|
||||
provisioning workflow run workflows/deploy-full-stack.yaml
|
||||
</code></pre>
|
||||
<p>See: <a href="provisioning-integration/README.html"><code>provisioning-integration/README.md</code></a></p>
|
||||
<hr />
|
||||
<h2 id="next-steps"><a class="header" href="#next-steps">Next Steps</a></h2>
|
||||
<ul>
|
||||
<li><input disabled="" type="checkbox"/>
|
||||
Set up monitoring (Prometheus + Grafana)</li>
|
||||
<li><input disabled="" type="checkbox"/>
|
||||
Configure TLS certificates (cert-manager)</li>
|
||||
<li><input disabled="" type="checkbox"/>
|
||||
Set up backups for SurrealDB</li>
|
||||
<li><input disabled="" type="checkbox"/>
|
||||
Configure HPA (Horizontal Pod Autoscaler)</li>
|
||||
<li><input disabled="" type="checkbox"/>
|
||||
Enable log aggregation</li>
|
||||
<li><input disabled="" type="checkbox"/>
|
||||
Test agent workflows</li>
|
||||
</ul>
|
||||
<hr />
|
||||
<h2 id="full-documentation"><a class="header" href="#full-documentation">Full Documentation</a></h2>
|
||||
<ul>
|
||||
<li><strong>Comprehensive Guide</strong>: <a href="DEPLOYMENT.html"><code>DEPLOYMENT.md</code></a></li>
|
||||
<li><strong>K8s README</strong>: <a href="kubernetes/README.html"><code>kubernetes/README.md</code></a></li>
|
||||
<li><strong>Provisioning Guide</strong>: <a href="provisioning-integration/README.html"><code>provisioning-integration/README.md</code></a></li>
|
||||
<li><strong>Project Overview</strong>: <a href="PROJECT_COMPLETION_REPORT.html"><code>PROJECT_COMPLETION_REPORT.md</code></a></li>
|
||||
</ul>
|
||||
<hr />
|
||||
<h2 id="quick-commands-reference"><a class="header" href="#quick-commands-reference">Quick Commands Reference</a></h2>
|
||||
<pre><code class="language-bash"># 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
|
||||
</code></pre>
|
||||
<hr />
|
||||
<p><strong>VAPORA v1.0</strong> - Production Ready ✅
|
||||
<strong>Total Deployment Time</strong>: ~15 minutes
|
||||
<strong>Status</strong>: All 5 phases completed</p>
|
||||
|
||||
</main>
|
||||
|
||||
<nav class="nav-wrapper" aria-label="Page navigation">
|
||||
<!-- Mobile navigation buttons -->
|
||||
<a rel="prev" href="../../setup/deployment.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
|
||||
<i class="fa fa-angle-left"></i>
|
||||
</a>
|
||||
|
||||
<a rel="next prefetch" href="../../setup/tracking-setup.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
|
||||
<i class="fa fa-angle-right"></i>
|
||||
</a>
|
||||
|
||||
<div style="clear: both"></div>
|
||||
</nav>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<nav class="nav-wide-wrapper" aria-label="Page navigation">
|
||||
<a rel="prev" href="../../setup/deployment.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
|
||||
<i class="fa fa-angle-left"></i>
|
||||
</a>
|
||||
|
||||
<a rel="next prefetch" href="../../setup/tracking-setup.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
|
||||
<i class="fa fa-angle-right"></i>
|
||||
</a>
|
||||
</nav>
|
||||
|
||||
</div>
|
||||
|
||||
|
||||
|
||||
|
||||
<script>
|
||||
window.playground_copyable = true;
|
||||
</script>
|
||||
|
||||
|
||||
<script src="../elasticlunr.min.js"></script>
|
||||
<script src="../mark.min.js"></script>
|
||||
<script src="../searcher.js"></script>
|
||||
|
||||
<script src="../clipboard.min.js"></script>
|
||||
<script src="../highlight.js"></script>
|
||||
<script src="../book.js"></script>
|
||||
|
||||
<!-- Custom JS scripts -->
|
||||
|
||||
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@ -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 <pod-name>
|
||||
kubectl logs -n vapora <pod-name>
|
||||
```
|
||||
|
||||
### 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
|
||||
|
||||
873
docs/setup/deployment.html
Normal file
873
docs/setup/deployment.html
Normal file
@ -0,0 +1,873 @@
|
||||
<!DOCTYPE HTML>
|
||||
<html lang="en" class="light sidebar-visible" dir="ltr">
|
||||
<head>
|
||||
<!-- Book generated using mdBook -->
|
||||
<meta charset="UTF-8">
|
||||
<title>Deployment Guide - VAPORA Platform Documentation</title>
|
||||
|
||||
|
||||
<!-- Custom HTML head -->
|
||||
|
||||
<meta name="description" content="Comprehensive documentation for VAPORA, an intelligent development orchestration platform built entirely in Rust.">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
<meta name="theme-color" content="#ffffff">
|
||||
|
||||
<link rel="icon" href="../favicon.svg">
|
||||
<link rel="shortcut icon" href="../favicon.png">
|
||||
<link rel="stylesheet" href="../css/variables.css">
|
||||
<link rel="stylesheet" href="../css/general.css">
|
||||
<link rel="stylesheet" href="../css/chrome.css">
|
||||
<link rel="stylesheet" href="../css/print.css" media="print">
|
||||
|
||||
<!-- Fonts -->
|
||||
<link rel="stylesheet" href="../FontAwesome/css/font-awesome.css">
|
||||
<link rel="stylesheet" href="../fonts/fonts.css">
|
||||
|
||||
<!-- Highlight.js Stylesheets -->
|
||||
<link rel="stylesheet" id="highlight-css" href="../highlight.css">
|
||||
<link rel="stylesheet" id="tomorrow-night-css" href="../tomorrow-night.css">
|
||||
<link rel="stylesheet" id="ayu-highlight-css" href="../ayu-highlight.css">
|
||||
|
||||
<!-- Custom theme stylesheets -->
|
||||
|
||||
|
||||
<!-- Provide site root and default themes to javascript -->
|
||||
<script>
|
||||
const path_to_root = "../";
|
||||
const default_light_theme = "light";
|
||||
const default_dark_theme = "dark";
|
||||
</script>
|
||||
<!-- Start loading toc.js asap -->
|
||||
<script src="../toc.js"></script>
|
||||
</head>
|
||||
<body>
|
||||
<div id="mdbook-help-container">
|
||||
<div id="mdbook-help-popup">
|
||||
<h2 class="mdbook-help-title">Keyboard shortcuts</h2>
|
||||
<div>
|
||||
<p>Press <kbd>←</kbd> or <kbd>→</kbd> to navigate between chapters</p>
|
||||
<p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
|
||||
<p>Press <kbd>?</kbd> to show this help</p>
|
||||
<p>Press <kbd>Esc</kbd> to hide this help</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<div id="body-container">
|
||||
<!-- Work around some values being stored in localStorage wrapped in quotes -->
|
||||
<script>
|
||||
try {
|
||||
let theme = localStorage.getItem('mdbook-theme');
|
||||
let sidebar = localStorage.getItem('mdbook-sidebar');
|
||||
|
||||
if (theme.startsWith('"') && theme.endsWith('"')) {
|
||||
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
|
||||
}
|
||||
|
||||
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
|
||||
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
|
||||
}
|
||||
} catch (e) { }
|
||||
</script>
|
||||
|
||||
<!-- Set the theme before any content is loaded, prevents flash -->
|
||||
<script>
|
||||
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
|
||||
let theme;
|
||||
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
|
||||
if (theme === null || theme === undefined) { theme = default_theme; }
|
||||
const html = document.documentElement;
|
||||
html.classList.remove('light')
|
||||
html.classList.add(theme);
|
||||
html.classList.add("js");
|
||||
</script>
|
||||
|
||||
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
|
||||
|
||||
<!-- Hide / unhide sidebar before it is displayed -->
|
||||
<script>
|
||||
let sidebar = null;
|
||||
const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
|
||||
if (document.body.clientWidth >= 1080) {
|
||||
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
|
||||
sidebar = sidebar || 'visible';
|
||||
} else {
|
||||
sidebar = 'hidden';
|
||||
}
|
||||
sidebar_toggle.checked = sidebar === 'visible';
|
||||
html.classList.remove('sidebar-visible');
|
||||
html.classList.add("sidebar-" + sidebar);
|
||||
</script>
|
||||
|
||||
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
|
||||
<!-- populated by js -->
|
||||
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
|
||||
<noscript>
|
||||
<iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
|
||||
</noscript>
|
||||
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
|
||||
<div class="sidebar-resize-indicator"></div>
|
||||
</div>
|
||||
</nav>
|
||||
|
||||
<div id="page-wrapper" class="page-wrapper">
|
||||
|
||||
<div class="page">
|
||||
<div id="menu-bar-hover-placeholder"></div>
|
||||
<div id="menu-bar" class="menu-bar sticky">
|
||||
<div class="left-buttons">
|
||||
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
|
||||
<i class="fa fa-bars"></i>
|
||||
</label>
|
||||
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
|
||||
<i class="fa fa-paint-brush"></i>
|
||||
</button>
|
||||
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
|
||||
<li role="none"><button role="menuitem" class="theme" id="default_theme">Auto</button></li>
|
||||
<li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
|
||||
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
|
||||
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
|
||||
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
|
||||
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
|
||||
</ul>
|
||||
<button id="search-toggle" class="icon-button" type="button" title="Search (`/`)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="/ s" aria-controls="searchbar">
|
||||
<i class="fa fa-search"></i>
|
||||
</button>
|
||||
</div>
|
||||
|
||||
<h1 class="menu-title">VAPORA Platform Documentation</h1>
|
||||
|
||||
<div class="right-buttons">
|
||||
<a href="../print.html" title="Print this book" aria-label="Print this book">
|
||||
<i id="print-button" class="fa fa-print"></i>
|
||||
</a>
|
||||
<a href="https://github.com/vapora-platform/vapora" title="Git repository" aria-label="Git repository">
|
||||
<i id="git-repository-button" class="fa fa-github"></i>
|
||||
</a>
|
||||
<a href="https://github.com/vapora-platform/vapora/edit/main/docs/src/../setup/deployment.md" title="Suggest an edit" aria-label="Suggest an edit">
|
||||
<i id="git-edit-button" class="fa fa-edit"></i>
|
||||
</a>
|
||||
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div id="search-wrapper" class="hidden">
|
||||
<form id="searchbar-outer" class="searchbar-outer">
|
||||
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
|
||||
</form>
|
||||
<div id="searchresults-outer" class="searchresults-outer hidden">
|
||||
<div id="searchresults-header" class="searchresults-header"></div>
|
||||
<ul id="searchresults">
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
|
||||
<script>
|
||||
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
|
||||
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
|
||||
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
|
||||
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
|
||||
});
|
||||
</script>
|
||||
|
||||
<div id="content" class="content">
|
||||
<main>
|
||||
<h1 id="vapora-v10-deployment-guide"><a class="header" href="#vapora-v10-deployment-guide">VAPORA v1.0 Deployment Guide</a></h1>
|
||||
<p>Complete guide for deploying VAPORA v1.0 to Kubernetes (self-hosted).</p>
|
||||
<p><strong>Version</strong>: 0.1.0
|
||||
<strong>Status</strong>: Production Ready
|
||||
<strong>Last Updated</strong>: 2025-11-10</p>
|
||||
<hr />
|
||||
<h2 id="table-of-contents"><a class="header" href="#table-of-contents">Table of Contents</a></h2>
|
||||
<ol>
|
||||
<li><a href="#overview">Overview</a></li>
|
||||
<li><a href="#prerequisites">Prerequisites</a></li>
|
||||
<li><a href="#architecture">Architecture</a></li>
|
||||
<li><a href="#deployment-methods">Deployment Methods</a></li>
|
||||
<li><a href="#building-docker-images">Building Docker Images</a></li>
|
||||
<li><a href="#kubernetes-deployment">Kubernetes Deployment</a></li>
|
||||
<li><a href="#provisioning-deployment">Provisioning Deployment</a></li>
|
||||
<li><a href="#configuration">Configuration</a></li>
|
||||
<li><a href="#monitoring--health-checks">Monitoring & Health Checks</a></li>
|
||||
<li><a href="#scaling">Scaling</a></li>
|
||||
<li><a href="#troubleshooting">Troubleshooting</a></li>
|
||||
<li><a href="#rollback">Rollback</a></li>
|
||||
<li><a href="#security">Security</a></li>
|
||||
</ol>
|
||||
<hr />
|
||||
<h2 id="overview"><a class="header" href="#overview">Overview</a></h2>
|
||||
<p>VAPORA v1.0 is a <strong>cloud-native multi-agent software development platform</strong> that runs on Kubernetes. It consists of:</p>
|
||||
<ul>
|
||||
<li><strong>6 Rust services</strong>: Backend API, Frontend UI, Agents, MCP Server, LLM Router (embedded), Shared library</li>
|
||||
<li><strong>2 Infrastructure services</strong>: SurrealDB (database), NATS JetStream (messaging)</li>
|
||||
<li><strong>Multi-IA routing</strong>: Claude, OpenAI, Gemini, Ollama support</li>
|
||||
<li><strong>12 specialized agents</strong>: Architect, Developer, Reviewer, Tester, Documenter, etc.</li>
|
||||
</ul>
|
||||
<p>All services are containerized and deployed as Kubernetes workloads.</p>
|
||||
<hr />
|
||||
<h2 id="prerequisites"><a class="header" href="#prerequisites">Prerequisites</a></h2>
|
||||
<h3 id="required-tools"><a class="header" href="#required-tools">Required Tools</a></h3>
|
||||
<ul>
|
||||
<li><strong>Kubernetes 1.25+</strong> (K3s, RKE2, or managed Kubernetes)</li>
|
||||
<li><strong>kubectl</strong> (configured and connected to cluster)</li>
|
||||
<li><strong>Docker</strong> or <strong>Podman</strong> (for building images)</li>
|
||||
<li><strong>Nushell</strong> (for deployment scripts)</li>
|
||||
</ul>
|
||||
<h3 id="optional-tools"><a class="header" href="#optional-tools">Optional Tools</a></h3>
|
||||
<ul>
|
||||
<li><strong>Provisioning CLI</strong> (for advanced deployment)</li>
|
||||
<li><strong>Helm</strong> (if using Helm charts)</li>
|
||||
<li><strong>cert-manager</strong> (for automatic TLS certificates)</li>
|
||||
<li><strong>Prometheus/Grafana</strong> (for monitoring)</li>
|
||||
</ul>
|
||||
<h3 id="cluster-requirements"><a class="header" href="#cluster-requirements">Cluster Requirements</a></h3>
|
||||
<ul>
|
||||
<li><strong>Minimum</strong>: 4 CPU, 8GB RAM, 50GB storage</li>
|
||||
<li><strong>Recommended</strong>: 8 CPU, 16GB RAM, 100GB storage</li>
|
||||
<li><strong>Production</strong>: 16+ CPU, 32GB+ RAM, 200GB+ storage</li>
|
||||
</ul>
|
||||
<h3 id="storage"><a class="header" href="#storage">Storage</a></h3>
|
||||
<ul>
|
||||
<li><strong>Storage Class</strong>: Required for SurrealDB PersistentVolumeClaim</li>
|
||||
<li><strong>Options</strong>: local-path, nfs-client, rook-ceph, or cloud provider storage</li>
|
||||
<li><strong>Minimum</strong>: 20Gi for database</li>
|
||||
</ul>
|
||||
<h3 id="ingress"><a class="header" href="#ingress">Ingress</a></h3>
|
||||
<ul>
|
||||
<li><strong>nginx-ingress</strong> controller installed</li>
|
||||
<li><strong>Domain name</strong> pointing to cluster ingress IP</li>
|
||||
<li><strong>TLS certificate</strong> (optional, recommended for production)</li>
|
||||
</ul>
|
||||
<hr />
|
||||
<h2 id="architecture"><a class="header" href="#architecture">Architecture</a></h2>
|
||||
<pre><code>┌─────────────────────────────────────────────────────┐
|
||||
│ 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 │
|
||||
└───────────────────────────────────────────────┘
|
||||
</code></pre>
|
||||
<hr />
|
||||
<h2 id="deployment-methods"><a class="header" href="#deployment-methods">Deployment Methods</a></h2>
|
||||
<p>VAPORA supports two deployment methods:</p>
|
||||
<h3 id="method-1-vanilla-kubernetes-recommended-for-getting-started"><a class="header" href="#method-1-vanilla-kubernetes-recommended-for-getting-started">Method 1: Vanilla Kubernetes (Recommended for Getting Started)</a></h3>
|
||||
<p><strong>Pros</strong>:</p>
|
||||
<ul>
|
||||
<li>Simple, well-documented</li>
|
||||
<li>Standard K8s manifests</li>
|
||||
<li>Easy to understand and modify</li>
|
||||
<li>No additional tools required</li>
|
||||
</ul>
|
||||
<p><strong>Cons</strong>:</p>
|
||||
<ul>
|
||||
<li>Manual cluster management</li>
|
||||
<li>Manual service ordering</li>
|
||||
<li>No built-in rollback</li>
|
||||
</ul>
|
||||
<p><strong>Use when</strong>: Learning, testing, or simple deployments</p>
|
||||
<h3 id="method-2-provisioning-recommended-for-production"><a class="header" href="#method-2-provisioning-recommended-for-production">Method 2: Provisioning (Recommended for Production)</a></h3>
|
||||
<p><strong>Pros</strong>:</p>
|
||||
<ul>
|
||||
<li>Automated cluster creation</li>
|
||||
<li>Declarative workflows</li>
|
||||
<li>Built-in rollback</li>
|
||||
<li>Service mesh integration</li>
|
||||
<li>Secret management</li>
|
||||
</ul>
|
||||
<p><strong>Cons</strong>:</p>
|
||||
<ul>
|
||||
<li>Requires Provisioning CLI</li>
|
||||
<li>More complex configuration</li>
|
||||
<li>Steeper learning curve</li>
|
||||
</ul>
|
||||
<p><strong>Use when</strong>: Production deployments, complex environments</p>
|
||||
<hr />
|
||||
<h2 id="building-docker-images"><a class="header" href="#building-docker-images">Building Docker Images</a></h2>
|
||||
<h3 id="option-1-using-nushell-script-recommended"><a class="header" href="#option-1-using-nushell-script-recommended">Option 1: Using Nushell Script (Recommended)</a></h3>
|
||||
<pre><code class="language-bash"># 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
|
||||
</code></pre>
|
||||
<h3 id="option-2-manual-docker-build"><a class="header" href="#option-2-manual-docker-build">Option 2: Manual Docker Build</a></h3>
|
||||
<pre><code class="language-bash"># 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 .
|
||||
</code></pre>
|
||||
<h3 id="image-sizes-approximate"><a class="header" href="#image-sizes-approximate">Image Sizes (Approximate)</a></h3>
|
||||
<ul>
|
||||
<li><strong>vapora/backend</strong>: ~50MB (Alpine + Rust binary)</li>
|
||||
<li><strong>vapora/frontend</strong>: ~30MB (nginx + WASM)</li>
|
||||
<li><strong>vapora/agents</strong>: ~50MB (Alpine + Rust binary)</li>
|
||||
<li><strong>vapora/mcp-server</strong>: ~45MB (Alpine + Rust binary)</li>
|
||||
</ul>
|
||||
<hr />
|
||||
<h2 id="kubernetes-deployment"><a class="header" href="#kubernetes-deployment">Kubernetes Deployment</a></h2>
|
||||
<h3 id="step-1-configure-secrets"><a class="header" href="#step-1-configure-secrets">Step 1: Configure Secrets</a></h3>
|
||||
<p>Edit <code>kubernetes/03-secrets.yaml</code>:</p>
|
||||
<pre><code class="language-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)"
|
||||
</code></pre>
|
||||
<p><strong>IMPORTANT</strong>: Never commit real secrets to version control!</p>
|
||||
<h3 id="step-2-configure-ingress"><a class="header" href="#step-2-configure-ingress">Step 2: Configure Ingress</a></h3>
|
||||
<p>Edit <code>kubernetes/08-ingress.yaml</code>:</p>
|
||||
<pre><code class="language-yaml">spec:
|
||||
rules:
|
||||
- host: vapora.yourdomain.com # Change this!
|
||||
</code></pre>
|
||||
<h3 id="step-3-deploy-using-script-recommended"><a class="header" href="#step-3-deploy-using-script-recommended">Step 3: Deploy Using Script (Recommended)</a></h3>
|
||||
<pre><code class="language-bash"># 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
|
||||
</code></pre>
|
||||
<h3 id="step-4-manual-deploy-alternative"><a class="header" href="#step-4-manual-deploy-alternative">Step 4: Manual Deploy (Alternative)</a></h3>
|
||||
<pre><code class="language-bash"># 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
|
||||
</code></pre>
|
||||
<h3 id="step-5-verify-deployment"><a class="header" href="#step-5-verify-deployment">Step 5: Verify Deployment</a></h3>
|
||||
<pre><code class="language-bash"># 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
|
||||
</code></pre>
|
||||
<h3 id="step-6-access-vapora"><a class="header" href="#step-6-access-vapora">Step 6: Access VAPORA</a></h3>
|
||||
<pre><code class="language-bash"># 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
|
||||
</code></pre>
|
||||
<hr />
|
||||
<h2 id="provisioning-deployment"><a class="header" href="#provisioning-deployment">Provisioning Deployment</a></h2>
|
||||
<h3 id="step-1-validate-configuration"><a class="header" href="#step-1-validate-configuration">Step 1: Validate Configuration</a></h3>
|
||||
<pre><code class="language-bash"># Validate Provisioning workspace
|
||||
nu scripts/validate-provisioning.nu
|
||||
</code></pre>
|
||||
<h3 id="step-2-create-cluster"><a class="header" href="#step-2-create-cluster">Step 2: Create Cluster</a></h3>
|
||||
<pre><code class="language-bash">cd provisioning/vapora-wrksp
|
||||
|
||||
# Validate configuration
|
||||
provisioning validate --all
|
||||
|
||||
# Create cluster
|
||||
provisioning cluster create --config workspace.toml
|
||||
</code></pre>
|
||||
<h3 id="step-3-deploy-services"><a class="header" href="#step-3-deploy-services">Step 3: Deploy Services</a></h3>
|
||||
<pre><code class="language-bash"># 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
|
||||
</code></pre>
|
||||
<h3 id="step-4-health-check"><a class="header" href="#step-4-health-check">Step 4: Health Check</a></h3>
|
||||
<pre><code class="language-bash">provisioning workflow run workflows/health-check.yaml
|
||||
</code></pre>
|
||||
<p>See <code>provisioning-integration/README.md</code> for details.</p>
|
||||
<hr />
|
||||
<h2 id="configuration"><a class="header" href="#configuration">Configuration</a></h2>
|
||||
<h3 id="environment-variables"><a class="header" href="#environment-variables">Environment Variables</a></h3>
|
||||
<h4 id="backend-vapora-backend"><a class="header" href="#backend-vapora-backend">Backend (<code>vapora-backend</code>)</a></h4>
|
||||
<pre><code class="language-bash">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
|
||||
</code></pre>
|
||||
<h4 id="agents-vapora-agents"><a class="header" href="#agents-vapora-agents">Agents (<code>vapora-agents</code>)</a></h4>
|
||||
<pre><code class="language-bash">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
|
||||
</code></pre>
|
||||
<h4 id="mcp-server-vapora-mcp-server"><a class="header" href="#mcp-server-vapora-mcp-server">MCP Server (<code>vapora-mcp-server</code>)</a></h4>
|
||||
<pre><code class="language-bash">RUST_LOG=info,vapora_mcp_server=debug
|
||||
# Port configured via --port flag
|
||||
</code></pre>
|
||||
<h3 id="configmaps"><a class="header" href="#configmaps">ConfigMaps</a></h3>
|
||||
<p>Create custom configuration:</p>
|
||||
<pre><code class="language-bash">kubectl create configmap agent-config -n vapora \
|
||||
--from-file=agents.toml
|
||||
</code></pre>
|
||||
<p>Mount in deployment:</p>
|
||||
<pre><code class="language-yaml">volumeMounts:
|
||||
- name: config
|
||||
mountPath: /etc/vapora
|
||||
volumes:
|
||||
- name: config
|
||||
configMap:
|
||||
name: agent-config
|
||||
</code></pre>
|
||||
<hr />
|
||||
<h2 id="monitoring--health-checks"><a class="header" href="#monitoring--health-checks">Monitoring & Health Checks</a></h2>
|
||||
<h3 id="health-endpoints"><a class="header" href="#health-endpoints">Health Endpoints</a></h3>
|
||||
<p>All services expose health check endpoints:</p>
|
||||
<ul>
|
||||
<li><strong>Backend</strong>: <code>GET /health</code></li>
|
||||
<li><strong>Frontend</strong>: <code>GET /health.html</code></li>
|
||||
<li><strong>Agents</strong>: <code>GET /health</code>, <code>GET /ready</code></li>
|
||||
<li><strong>MCP Server</strong>: <code>GET /health</code></li>
|
||||
<li><strong>SurrealDB</strong>: <code>GET /health</code></li>
|
||||
<li><strong>NATS</strong>: <code>GET /healthz</code> (port 8222)</li>
|
||||
</ul>
|
||||
<h3 id="manual-health-checks"><a class="header" href="#manual-health-checks">Manual Health Checks</a></h3>
|
||||
<pre><code class="language-bash"># 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
|
||||
</code></pre>
|
||||
<h3 id="kubernetes-probes"><a class="header" href="#kubernetes-probes">Kubernetes Probes</a></h3>
|
||||
<p>All deployments have:</p>
|
||||
<ul>
|
||||
<li><strong>Liveness Probe</strong>: Restarts unhealthy pods</li>
|
||||
<li><strong>Readiness Probe</strong>: Removes pod from service until ready</li>
|
||||
</ul>
|
||||
<h3 id="logs"><a class="header" href="#logs">Logs</a></h3>
|
||||
<pre><code class="language-bash"># 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
|
||||
</code></pre>
|
||||
<h3 id="metrics-optional"><a class="header" href="#metrics-optional">Metrics (Optional)</a></h3>
|
||||
<p>Deploy Prometheus + Grafana:</p>
|
||||
<pre><code class="language-bash"># 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
|
||||
</code></pre>
|
||||
<p>VAPORA services expose metrics on <code>/metrics</code> endpoint (future enhancement).</p>
|
||||
<hr />
|
||||
<h2 id="scaling"><a class="header" href="#scaling">Scaling</a></h2>
|
||||
<h3 id="manual-scaling"><a class="header" href="#manual-scaling">Manual Scaling</a></h3>
|
||||
<pre><code class="language-bash"># 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
|
||||
</code></pre>
|
||||
<h3 id="horizontal-pod-autoscaler-hpa"><a class="header" href="#horizontal-pod-autoscaler-hpa">Horizontal Pod Autoscaler (HPA)</a></h3>
|
||||
<pre><code class="language-yaml">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
|
||||
</code></pre>
|
||||
<p>Apply:</p>
|
||||
<pre><code class="language-bash">kubectl apply -f hpa.yaml
|
||||
</code></pre>
|
||||
<h3 id="resource-limits"><a class="header" href="#resource-limits">Resource Limits</a></h3>
|
||||
<p>Adjust in deployment YAML:</p>
|
||||
<pre><code class="language-yaml">resources:
|
||||
requests:
|
||||
cpu: 200m
|
||||
memory: 256Mi
|
||||
limits:
|
||||
cpu: 1000m
|
||||
memory: 1Gi
|
||||
</code></pre>
|
||||
<hr />
|
||||
<h2 id="troubleshooting"><a class="header" href="#troubleshooting">Troubleshooting</a></h2>
|
||||
<h3 id="pods-not-starting"><a class="header" href="#pods-not-starting">Pods Not Starting</a></h3>
|
||||
<pre><code class="language-bash"># 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
|
||||
</code></pre>
|
||||
<h3 id="database-connection-issues"><a class="header" href="#database-connection-issues">Database Connection Issues</a></h3>
|
||||
<pre><code class="language-bash"># 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
|
||||
</code></pre>
|
||||
<h3 id="nats-connection-issues"><a class="header" href="#nats-connection-issues">NATS Connection Issues</a></h3>
|
||||
<pre><code class="language-bash"># 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
|
||||
</code></pre>
|
||||
<h3 id="image-pull-errors"><a class="header" href="#image-pull-errors">Image Pull Errors</a></h3>
|
||||
<pre><code class="language-bash"># 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
|
||||
</code></pre>
|
||||
<h3 id="ingress-not-working"><a class="header" href="#ingress-not-working">Ingress Not Working</a></h3>
|
||||
<pre><code class="language-bash"># 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
|
||||
</code></pre>
|
||||
<hr />
|
||||
<h2 id="rollback"><a class="header" href="#rollback">Rollback</a></h2>
|
||||
<h3 id="kubernetes-rollback"><a class="header" href="#kubernetes-rollback">Kubernetes Rollback</a></h3>
|
||||
<pre><code class="language-bash"># 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
|
||||
</code></pre>
|
||||
<h3 id="provisioning-rollback"><a class="header" href="#provisioning-rollback">Provisioning Rollback</a></h3>
|
||||
<pre><code class="language-bash">cd provisioning/vapora-wrksp
|
||||
|
||||
# List versions
|
||||
provisioning version list
|
||||
|
||||
# Rollback to previous version
|
||||
provisioning rollback --to-version <version-id>
|
||||
</code></pre>
|
||||
<hr />
|
||||
<h2 id="security"><a class="header" href="#security">Security</a></h2>
|
||||
<h3 id="secrets-management"><a class="header" href="#secrets-management">Secrets Management</a></h3>
|
||||
<ul>
|
||||
<li><strong>Kubernetes Secrets</strong>: Encrypted at rest (if configured in K8s)</li>
|
||||
<li><strong>External Secrets Operator</strong>: Sync from Vault, AWS Secrets Manager, etc.</li>
|
||||
<li><strong>RustyVault</strong>: Integrated with Provisioning</li>
|
||||
</ul>
|
||||
<h3 id="network-policies"><a class="header" href="#network-policies">Network Policies</a></h3>
|
||||
<p>Apply network policies to restrict pod-to-pod communication:</p>
|
||||
<pre><code class="language-yaml">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
|
||||
</code></pre>
|
||||
<h3 id="tls-certificates"><a class="header" href="#tls-certificates">TLS Certificates</a></h3>
|
||||
<p>Use cert-manager for automatic TLS:</p>
|
||||
<pre><code class="language-bash"># 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
|
||||
</code></pre>
|
||||
<p>Update ingress:</p>
|
||||
<pre><code class="language-yaml">metadata:
|
||||
annotations:
|
||||
cert-manager.io/cluster-issuer: "letsencrypt-prod"
|
||||
spec:
|
||||
tls:
|
||||
- hosts:
|
||||
- vapora.yourdomain.com
|
||||
secretName: vapora-tls
|
||||
</code></pre>
|
||||
<hr />
|
||||
<h2 id="backup--restore"><a class="header" href="#backup--restore">Backup & Restore</a></h2>
|
||||
<h3 id="surrealdb-backup"><a class="header" href="#surrealdb-backup">SurrealDB Backup</a></h3>
|
||||
<pre><code class="language-bash"># 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
|
||||
</code></pre>
|
||||
<h3 id="surrealdb-restore"><a class="header" href="#surrealdb-restore">SurrealDB Restore</a></h3>
|
||||
<pre><code class="language-bash"># 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
|
||||
</code></pre>
|
||||
<h3 id="pvc-backup"><a class="header" href="#pvc-backup">PVC Backup</a></h3>
|
||||
<pre><code class="language-bash"># 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
|
||||
</code></pre>
|
||||
<hr />
|
||||
<h2 id="uninstall"><a class="header" href="#uninstall">Uninstall</a></h2>
|
||||
<h3 id="delete-all-resources"><a class="header" href="#delete-all-resources">Delete All Resources</a></h3>
|
||||
<pre><code class="language-bash"># Delete namespace (deletes all resources)
|
||||
kubectl delete namespace vapora
|
||||
|
||||
# Or delete manifests individually
|
||||
kubectl delete -f kubernetes/
|
||||
</code></pre>
|
||||
<h3 id="delete-pvcs"><a class="header" href="#delete-pvcs">Delete PVCs</a></h3>
|
||||
<pre><code class="language-bash"># List PVCs
|
||||
kubectl get pvc -n vapora
|
||||
|
||||
# Delete PVC (data will be lost!)
|
||||
kubectl delete pvc data-surrealdb-0 -n vapora
|
||||
</code></pre>
|
||||
<hr />
|
||||
<h2 id="next-steps"><a class="header" href="#next-steps">Next Steps</a></h2>
|
||||
<p>After successful deployment:</p>
|
||||
<ol>
|
||||
<li><strong>Configure DNS</strong>: Point domain to ingress IP</li>
|
||||
<li><strong>Set up TLS</strong>: Configure cert-manager for HTTPS</li>
|
||||
<li><strong>Enable monitoring</strong>: Deploy Prometheus/Grafana</li>
|
||||
<li><strong>Configure backups</strong>: Schedule SurrealDB backups</li>
|
||||
<li><strong>Set up CI/CD</strong>: Automate deployments</li>
|
||||
<li><strong>Configure HPA</strong>: Enable autoscaling</li>
|
||||
<li><strong>Test disaster recovery</strong>: Practice rollback procedures</li>
|
||||
</ol>
|
||||
<hr />
|
||||
<h2 id="support"><a class="header" href="#support">Support</a></h2>
|
||||
<ul>
|
||||
<li><strong>Deployment Issues</strong>: Check <code>kubernetes/README.md</code></li>
|
||||
<li><strong>Provisioning Issues</strong>: Check <code>provisioning-integration/README.md</code></li>
|
||||
<li><strong>Scripts Help</strong>: Run <code>nu scripts/<script-name>.nu --help</code></li>
|
||||
<li><strong>Kubernetes Docs</strong>: https://kubernetes.io/docs/</li>
|
||||
</ul>
|
||||
<hr />
|
||||
<p><strong>VAPORA v1.0</strong> - Cloud-Native Multi-Agent Platform
|
||||
<strong>Status</strong>: Production Ready ✅</p>
|
||||
|
||||
</main>
|
||||
|
||||
<nav class="nav-wrapper" aria-label="Page navigation">
|
||||
<!-- Mobile navigation buttons -->
|
||||
<a rel="prev" href="../../setup/setup-guide.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
|
||||
<i class="fa fa-angle-left"></i>
|
||||
</a>
|
||||
|
||||
<a rel="next prefetch" href="../../setup/deployment-quickstart.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
|
||||
<i class="fa fa-angle-right"></i>
|
||||
</a>
|
||||
|
||||
<div style="clear: both"></div>
|
||||
</nav>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<nav class="nav-wide-wrapper" aria-label="Page navigation">
|
||||
<a rel="prev" href="../../setup/setup-guide.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
|
||||
<i class="fa fa-angle-left"></i>
|
||||
</a>
|
||||
|
||||
<a rel="next prefetch" href="../../setup/deployment-quickstart.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
|
||||
<i class="fa fa-angle-right"></i>
|
||||
</a>
|
||||
</nav>
|
||||
|
||||
</div>
|
||||
|
||||
|
||||
|
||||
|
||||
<script>
|
||||
window.playground_copyable = true;
|
||||
</script>
|
||||
|
||||
|
||||
<script src="../elasticlunr.min.js"></script>
|
||||
<script src="../mark.min.js"></script>
|
||||
<script src="../searcher.js"></script>
|
||||
|
||||
<script src="../clipboard.min.js"></script>
|
||||
<script src="../highlight.js"></script>
|
||||
<script src="../book.js"></script>
|
||||
|
||||
<!-- Custom JS scripts -->
|
||||
|
||||
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
242
docs/setup/index.html
Normal file
242
docs/setup/index.html
Normal file
@ -0,0 +1,242 @@
|
||||
<!DOCTYPE HTML>
|
||||
<html lang="en" class="light sidebar-visible" dir="ltr">
|
||||
<head>
|
||||
<!-- Book generated using mdBook -->
|
||||
<meta charset="UTF-8">
|
||||
<title>Setup Overview - VAPORA Platform Documentation</title>
|
||||
|
||||
|
||||
<!-- Custom HTML head -->
|
||||
|
||||
<meta name="description" content="Comprehensive documentation for VAPORA, an intelligent development orchestration platform built entirely in Rust.">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
<meta name="theme-color" content="#ffffff">
|
||||
|
||||
<link rel="icon" href="../favicon.svg">
|
||||
<link rel="shortcut icon" href="../favicon.png">
|
||||
<link rel="stylesheet" href="../css/variables.css">
|
||||
<link rel="stylesheet" href="../css/general.css">
|
||||
<link rel="stylesheet" href="../css/chrome.css">
|
||||
<link rel="stylesheet" href="../css/print.css" media="print">
|
||||
|
||||
<!-- Fonts -->
|
||||
<link rel="stylesheet" href="../FontAwesome/css/font-awesome.css">
|
||||
<link rel="stylesheet" href="../fonts/fonts.css">
|
||||
|
||||
<!-- Highlight.js Stylesheets -->
|
||||
<link rel="stylesheet" id="highlight-css" href="../highlight.css">
|
||||
<link rel="stylesheet" id="tomorrow-night-css" href="../tomorrow-night.css">
|
||||
<link rel="stylesheet" id="ayu-highlight-css" href="../ayu-highlight.css">
|
||||
|
||||
<!-- Custom theme stylesheets -->
|
||||
|
||||
|
||||
<!-- Provide site root and default themes to javascript -->
|
||||
<script>
|
||||
const path_to_root = "../";
|
||||
const default_light_theme = "light";
|
||||
const default_dark_theme = "dark";
|
||||
</script>
|
||||
<!-- Start loading toc.js asap -->
|
||||
<script src="../toc.js"></script>
|
||||
</head>
|
||||
<body>
|
||||
<div id="mdbook-help-container">
|
||||
<div id="mdbook-help-popup">
|
||||
<h2 class="mdbook-help-title">Keyboard shortcuts</h2>
|
||||
<div>
|
||||
<p>Press <kbd>←</kbd> or <kbd>→</kbd> to navigate between chapters</p>
|
||||
<p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
|
||||
<p>Press <kbd>?</kbd> to show this help</p>
|
||||
<p>Press <kbd>Esc</kbd> to hide this help</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<div id="body-container">
|
||||
<!-- Work around some values being stored in localStorage wrapped in quotes -->
|
||||
<script>
|
||||
try {
|
||||
let theme = localStorage.getItem('mdbook-theme');
|
||||
let sidebar = localStorage.getItem('mdbook-sidebar');
|
||||
|
||||
if (theme.startsWith('"') && theme.endsWith('"')) {
|
||||
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
|
||||
}
|
||||
|
||||
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
|
||||
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
|
||||
}
|
||||
} catch (e) { }
|
||||
</script>
|
||||
|
||||
<!-- Set the theme before any content is loaded, prevents flash -->
|
||||
<script>
|
||||
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
|
||||
let theme;
|
||||
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
|
||||
if (theme === null || theme === undefined) { theme = default_theme; }
|
||||
const html = document.documentElement;
|
||||
html.classList.remove('light')
|
||||
html.classList.add(theme);
|
||||
html.classList.add("js");
|
||||
</script>
|
||||
|
||||
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
|
||||
|
||||
<!-- Hide / unhide sidebar before it is displayed -->
|
||||
<script>
|
||||
let sidebar = null;
|
||||
const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
|
||||
if (document.body.clientWidth >= 1080) {
|
||||
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
|
||||
sidebar = sidebar || 'visible';
|
||||
} else {
|
||||
sidebar = 'hidden';
|
||||
}
|
||||
sidebar_toggle.checked = sidebar === 'visible';
|
||||
html.classList.remove('sidebar-visible');
|
||||
html.classList.add("sidebar-" + sidebar);
|
||||
</script>
|
||||
|
||||
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
|
||||
<!-- populated by js -->
|
||||
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
|
||||
<noscript>
|
||||
<iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
|
||||
</noscript>
|
||||
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
|
||||
<div class="sidebar-resize-indicator"></div>
|
||||
</div>
|
||||
</nav>
|
||||
|
||||
<div id="page-wrapper" class="page-wrapper">
|
||||
|
||||
<div class="page">
|
||||
<div id="menu-bar-hover-placeholder"></div>
|
||||
<div id="menu-bar" class="menu-bar sticky">
|
||||
<div class="left-buttons">
|
||||
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
|
||||
<i class="fa fa-bars"></i>
|
||||
</label>
|
||||
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
|
||||
<i class="fa fa-paint-brush"></i>
|
||||
</button>
|
||||
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
|
||||
<li role="none"><button role="menuitem" class="theme" id="default_theme">Auto</button></li>
|
||||
<li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
|
||||
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
|
||||
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
|
||||
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
|
||||
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
|
||||
</ul>
|
||||
<button id="search-toggle" class="icon-button" type="button" title="Search (`/`)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="/ s" aria-controls="searchbar">
|
||||
<i class="fa fa-search"></i>
|
||||
</button>
|
||||
</div>
|
||||
|
||||
<h1 class="menu-title">VAPORA Platform Documentation</h1>
|
||||
|
||||
<div class="right-buttons">
|
||||
<a href="../print.html" title="Print this book" aria-label="Print this book">
|
||||
<i id="print-button" class="fa fa-print"></i>
|
||||
</a>
|
||||
<a href="https://github.com/vapora-platform/vapora" title="Git repository" aria-label="Git repository">
|
||||
<i id="git-repository-button" class="fa fa-github"></i>
|
||||
</a>
|
||||
<a href="https://github.com/vapora-platform/vapora/edit/main/docs/src/../setup/README.md" title="Suggest an edit" aria-label="Suggest an edit">
|
||||
<i id="git-edit-button" class="fa fa-edit"></i>
|
||||
</a>
|
||||
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div id="search-wrapper" class="hidden">
|
||||
<form id="searchbar-outer" class="searchbar-outer">
|
||||
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
|
||||
</form>
|
||||
<div id="searchresults-outer" class="searchresults-outer hidden">
|
||||
<div id="searchresults-header" class="searchresults-header"></div>
|
||||
<ul id="searchresults">
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
|
||||
<script>
|
||||
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
|
||||
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
|
||||
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
|
||||
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
|
||||
});
|
||||
</script>
|
||||
|
||||
<div id="content" class="content">
|
||||
<main>
|
||||
<h1 id="setup--deployment"><a class="header" href="#setup--deployment">Setup & Deployment</a></h1>
|
||||
<p>Installation, configuration, and deployment guides for VAPORA.</p>
|
||||
<h2 id="contents"><a class="header" href="#contents">Contents</a></h2>
|
||||
<ul>
|
||||
<li><strong><a href="setup-guide.html">Setup Guide</a></strong> — Complete installation and configuration</li>
|
||||
<li><strong><a href="deployment.html">Deployment Guide</a></strong> — Production deployment on Kubernetes</li>
|
||||
<li><strong><a href="deployment-quickstart.html">Deployment Quickstart</a></strong> — Quick deployment walkthrough</li>
|
||||
<li><strong><a href="tracking-setup.html">Tracking Setup</a></strong> — Project tracking configuration</li>
|
||||
<li><strong><a href="tracking-quickstart.html">Tracking Quickstart</a></strong> — Quick tracking setup</li>
|
||||
</ul>
|
||||
<h2 id="quick-start"><a class="header" href="#quick-start">Quick Start</a></h2>
|
||||
<ol>
|
||||
<li>Read <a href="deployment-quickstart.html">Deployment Quickstart</a> for fast setup</li>
|
||||
<li>Refer to <a href="setup-guide.html">Setup Guide</a> for detailed configuration</li>
|
||||
<li>Use <a href="deployment.html">Deployment Guide</a> for production deployments</li>
|
||||
</ol>
|
||||
|
||||
</main>
|
||||
|
||||
<nav class="nav-wrapper" aria-label="Page navigation">
|
||||
<!-- Mobile navigation buttons -->
|
||||
<a rel="prev" href="../../quickstart.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
|
||||
<i class="fa fa-angle-left"></i>
|
||||
</a>
|
||||
|
||||
<a rel="next prefetch" href="../../setup/setup-guide.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
|
||||
<i class="fa fa-angle-right"></i>
|
||||
</a>
|
||||
|
||||
<div style="clear: both"></div>
|
||||
</nav>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<nav class="nav-wide-wrapper" aria-label="Page navigation">
|
||||
<a rel="prev" href="../../quickstart.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
|
||||
<i class="fa fa-angle-left"></i>
|
||||
</a>
|
||||
|
||||
<a rel="next prefetch" href="../../setup/setup-guide.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
|
||||
<i class="fa fa-angle-right"></i>
|
||||
</a>
|
||||
</nav>
|
||||
|
||||
</div>
|
||||
|
||||
|
||||
|
||||
|
||||
<script>
|
||||
window.playground_copyable = true;
|
||||
</script>
|
||||
|
||||
|
||||
<script src="../elasticlunr.min.js"></script>
|
||||
<script src="../mark.min.js"></script>
|
||||
<script src="../searcher.js"></script>
|
||||
|
||||
<script src="../clipboard.min.js"></script>
|
||||
<script src="../highlight.js"></script>
|
||||
<script src="../book.js"></script>
|
||||
|
||||
<!-- Custom JS scripts -->
|
||||
|
||||
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
379
docs/setup/secretumvault-integration.html
Normal file
379
docs/setup/secretumvault-integration.html
Normal file
@ -0,0 +1,379 @@
|
||||
<!DOCTYPE HTML>
|
||||
<html lang="en" class="light sidebar-visible" dir="ltr">
|
||||
<head>
|
||||
<!-- Book generated using mdBook -->
|
||||
<meta charset="UTF-8">
|
||||
<title>SecretumVault Integration - VAPORA Platform Documentation</title>
|
||||
|
||||
|
||||
<!-- Custom HTML head -->
|
||||
|
||||
<meta name="description" content="Comprehensive documentation for VAPORA, an intelligent development orchestration platform built entirely in Rust.">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
<meta name="theme-color" content="#ffffff">
|
||||
|
||||
<link rel="icon" href="../favicon.svg">
|
||||
<link rel="shortcut icon" href="../favicon.png">
|
||||
<link rel="stylesheet" href="../css/variables.css">
|
||||
<link rel="stylesheet" href="../css/general.css">
|
||||
<link rel="stylesheet" href="../css/chrome.css">
|
||||
<link rel="stylesheet" href="../css/print.css" media="print">
|
||||
|
||||
<!-- Fonts -->
|
||||
<link rel="stylesheet" href="../FontAwesome/css/font-awesome.css">
|
||||
<link rel="stylesheet" href="../fonts/fonts.css">
|
||||
|
||||
<!-- Highlight.js Stylesheets -->
|
||||
<link rel="stylesheet" id="highlight-css" href="../highlight.css">
|
||||
<link rel="stylesheet" id="tomorrow-night-css" href="../tomorrow-night.css">
|
||||
<link rel="stylesheet" id="ayu-highlight-css" href="../ayu-highlight.css">
|
||||
|
||||
<!-- Custom theme stylesheets -->
|
||||
|
||||
|
||||
<!-- Provide site root and default themes to javascript -->
|
||||
<script>
|
||||
const path_to_root = "../";
|
||||
const default_light_theme = "light";
|
||||
const default_dark_theme = "dark";
|
||||
</script>
|
||||
<!-- Start loading toc.js asap -->
|
||||
<script src="../toc.js"></script>
|
||||
</head>
|
||||
<body>
|
||||
<div id="mdbook-help-container">
|
||||
<div id="mdbook-help-popup">
|
||||
<h2 class="mdbook-help-title">Keyboard shortcuts</h2>
|
||||
<div>
|
||||
<p>Press <kbd>←</kbd> or <kbd>→</kbd> to navigate between chapters</p>
|
||||
<p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
|
||||
<p>Press <kbd>?</kbd> to show this help</p>
|
||||
<p>Press <kbd>Esc</kbd> to hide this help</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<div id="body-container">
|
||||
<!-- Work around some values being stored in localStorage wrapped in quotes -->
|
||||
<script>
|
||||
try {
|
||||
let theme = localStorage.getItem('mdbook-theme');
|
||||
let sidebar = localStorage.getItem('mdbook-sidebar');
|
||||
|
||||
if (theme.startsWith('"') && theme.endsWith('"')) {
|
||||
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
|
||||
}
|
||||
|
||||
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
|
||||
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
|
||||
}
|
||||
} catch (e) { }
|
||||
</script>
|
||||
|
||||
<!-- Set the theme before any content is loaded, prevents flash -->
|
||||
<script>
|
||||
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
|
||||
let theme;
|
||||
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
|
||||
if (theme === null || theme === undefined) { theme = default_theme; }
|
||||
const html = document.documentElement;
|
||||
html.classList.remove('light')
|
||||
html.classList.add(theme);
|
||||
html.classList.add("js");
|
||||
</script>
|
||||
|
||||
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
|
||||
|
||||
<!-- Hide / unhide sidebar before it is displayed -->
|
||||
<script>
|
||||
let sidebar = null;
|
||||
const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
|
||||
if (document.body.clientWidth >= 1080) {
|
||||
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
|
||||
sidebar = sidebar || 'visible';
|
||||
} else {
|
||||
sidebar = 'hidden';
|
||||
}
|
||||
sidebar_toggle.checked = sidebar === 'visible';
|
||||
html.classList.remove('sidebar-visible');
|
||||
html.classList.add("sidebar-" + sidebar);
|
||||
</script>
|
||||
|
||||
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
|
||||
<!-- populated by js -->
|
||||
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
|
||||
<noscript>
|
||||
<iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
|
||||
</noscript>
|
||||
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
|
||||
<div class="sidebar-resize-indicator"></div>
|
||||
</div>
|
||||
</nav>
|
||||
|
||||
<div id="page-wrapper" class="page-wrapper">
|
||||
|
||||
<div class="page">
|
||||
<div id="menu-bar-hover-placeholder"></div>
|
||||
<div id="menu-bar" class="menu-bar sticky">
|
||||
<div class="left-buttons">
|
||||
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
|
||||
<i class="fa fa-bars"></i>
|
||||
</label>
|
||||
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
|
||||
<i class="fa fa-paint-brush"></i>
|
||||
</button>
|
||||
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
|
||||
<li role="none"><button role="menuitem" class="theme" id="default_theme">Auto</button></li>
|
||||
<li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
|
||||
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
|
||||
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
|
||||
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
|
||||
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
|
||||
</ul>
|
||||
<button id="search-toggle" class="icon-button" type="button" title="Search (`/`)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="/ s" aria-controls="searchbar">
|
||||
<i class="fa fa-search"></i>
|
||||
</button>
|
||||
</div>
|
||||
|
||||
<h1 class="menu-title">VAPORA Platform Documentation</h1>
|
||||
|
||||
<div class="right-buttons">
|
||||
<a href="../print.html" title="Print this book" aria-label="Print this book">
|
||||
<i id="print-button" class="fa fa-print"></i>
|
||||
</a>
|
||||
<a href="https://github.com/vapora-platform/vapora" title="Git repository" aria-label="Git repository">
|
||||
<i id="git-repository-button" class="fa fa-github"></i>
|
||||
</a>
|
||||
<a href="https://github.com/vapora-platform/vapora/edit/main/docs/src/../setup/secretumvault-integration.md" title="Suggest an edit" aria-label="Suggest an edit">
|
||||
<i id="git-edit-button" class="fa fa-edit"></i>
|
||||
</a>
|
||||
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div id="search-wrapper" class="hidden">
|
||||
<form id="searchbar-outer" class="searchbar-outer">
|
||||
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
|
||||
</form>
|
||||
<div id="searchresults-outer" class="searchresults-outer hidden">
|
||||
<div id="searchresults-header" class="searchresults-header"></div>
|
||||
<ul id="searchresults">
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
|
||||
<script>
|
||||
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
|
||||
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
|
||||
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
|
||||
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
|
||||
});
|
||||
</script>
|
||||
|
||||
<div id="content" class="content">
|
||||
<main>
|
||||
<h1 id="secretumvault-integration"><a class="header" href="#secretumvault-integration">SecretumVault Integration</a></h1>
|
||||
<p>VAPORA integrates with <strong>SecretumVault</strong>, a post-quantum ready secrets management system, for secure credential and API key management across all microservices.</p>
|
||||
<h2 id="overview"><a class="header" href="#overview">Overview</a></h2>
|
||||
<p>SecretumVault provides:</p>
|
||||
<ul>
|
||||
<li><strong>Post-quantum cryptography</strong> ready for future-proof security</li>
|
||||
<li><strong>Multi-backend storage</strong> (filesystem, SurrealDB, PostgreSQL, etcd)</li>
|
||||
<li><strong>Fine-grained access control</strong> with Cedar policy engine</li>
|
||||
<li><strong>Secrets server</strong> for centralized credential management</li>
|
||||
<li><strong>CLI tools</strong> for operations and development</li>
|
||||
</ul>
|
||||
<h2 id="integration-points"><a class="header" href="#integration-points">Integration Points</a></h2>
|
||||
<p>SecretumVault is integrated into these VAPORA services:</p>
|
||||
<div class="table-wrapper"><table><thead><tr><th>Service</th><th>Purpose</th><th>Features</th></tr></thead><tbody>
|
||||
<tr><td><strong>vapora-backend</strong></td><td>REST API credentials, database secrets, JWT keys</td><td>Central secrets management</td></tr>
|
||||
<tr><td><strong>vapora-agents</strong></td><td>Agent authentication, service credentials</td><td>Secure agent-to-service auth</td></tr>
|
||||
<tr><td><strong>vapora-llm-router</strong></td><td>LLM provider API keys (Claude, OpenAI, Gemini, Ollama)</td><td>Cost tracking + credential rotation</td></tr>
|
||||
</tbody></table>
|
||||
</div>
|
||||
<h2 id="architecture"><a class="header" href="#architecture">Architecture</a></h2>
|
||||
<pre><code>┌─────────────────────────────────────────────────────────────┐
|
||||
│ VAPORA Services │
|
||||
├─────────────┬──────────────────┬────────────────────────────┤
|
||||
│ Backend API │ Agent Orchestration │ LLM Router │
|
||||
└──────┬──────┴────────┬─────────┴──────────┬─────────────────┘
|
||||
│ │ │
|
||||
└───────────────┼────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────┐
|
||||
│ SecretumVault Server │
|
||||
├─────────────────────────────┤
|
||||
│ • Credential storage │
|
||||
│ • Policy enforcement │
|
||||
│ • Audit logging │
|
||||
│ • Key rotation │
|
||||
└──────────┬──────────────────┘
|
||||
│
|
||||
┌───────────┴────────────┐
|
||||
▼ ▼
|
||||
Storage Layer Policy Engine
|
||||
(SurrealDB) (Cedar)
|
||||
</code></pre>
|
||||
<h2 id="configuration"><a class="header" href="#configuration">Configuration</a></h2>
|
||||
<h3 id="environment-variables"><a class="header" href="#environment-variables">Environment Variables</a></h3>
|
||||
<pre><code class="language-bash"># 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
|
||||
</code></pre>
|
||||
<h3 id="cargo-features"><a class="header" href="#cargo-features">Cargo Features</a></h3>
|
||||
<p>SecretumVault is integrated with these features enabled:</p>
|
||||
<pre><code class="language-toml">secretumvault = { workspace = true }
|
||||
# Automatically uses: "server", "surrealdb-storage"
|
||||
</code></pre>
|
||||
<h2 id="usage-examples"><a class="header" href="#usage-examples">Usage Examples</a></h2>
|
||||
<h3 id="in-vapora-backend"><a class="header" href="#in-vapora-backend">In vapora-backend</a></h3>
|
||||
<pre><pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
|
||||
</span><span class="boring">fn main() {
|
||||
</span>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?;
|
||||
<span class="boring">}</span></code></pre></pre>
|
||||
<h3 id="in-vapora-llm-router"><a class="header" href="#in-vapora-llm-router">In vapora-llm-router</a></h3>
|
||||
<pre><pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
|
||||
</span><span class="boring">fn main() {
|
||||
</span>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)
|
||||
<span class="boring">}</span></code></pre></pre>
|
||||
<h2 id="running-secretumvault"><a class="header" href="#running-secretumvault">Running SecretumVault</a></h2>
|
||||
<h3 id="local-development"><a class="header" href="#local-development">Local Development</a></h3>
|
||||
<pre><code class="language-bash"># 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
|
||||
</code></pre>
|
||||
<h3 id="production-kubernetes"><a class="header" href="#production-kubernetes">Production (Kubernetes)</a></h3>
|
||||
<pre><code class="language-bash"># Will be added to kubernetes/
|
||||
kubectl apply -f kubernetes/secretumvault/
|
||||
</code></pre>
|
||||
<h2 id="security-best-practices"><a class="header" href="#security-best-practices">Security Best Practices</a></h2>
|
||||
<ol>
|
||||
<li>
|
||||
<p><strong>Token Management</strong></p>
|
||||
<ul>
|
||||
<li>Use identity-based tokens (not basic auth)</li>
|
||||
<li>Rotate tokens regularly</li>
|
||||
<li>Store token in <code>.env.local</code> (not in git)</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li>
|
||||
<p><strong>Secret Storage</strong></p>
|
||||
<ul>
|
||||
<li>Never commit credentials to git</li>
|
||||
<li>Use SecretumVault for all sensitive data</li>
|
||||
<li>Enable audit logging for compliance</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li>
|
||||
<p><strong>Policy Enforcement</strong></p>
|
||||
<ul>
|
||||
<li>Define Cedar policies per role/service</li>
|
||||
<li>Restrict access by principle of least privilege</li>
|
||||
<li>Review policies during security audits</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li>
|
||||
<p><strong>Crypto Backend</strong></p>
|
||||
<ul>
|
||||
<li>Use <code>aws-lc</code> for post-quantum readiness</li>
|
||||
<li>Plan migration as quantum threats evolve</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ol>
|
||||
<h2 id="related-documentation"><a class="header" href="#related-documentation">Related Documentation</a></h2>
|
||||
<ul>
|
||||
<li><a href="../../../../secretumvault/">SecretumVault Project</a></li>
|
||||
<li><a href="vapora-architecture.html">VAPORA Architecture</a></li>
|
||||
<li><a href="../architecture/roles-permissions-profiles.html">Security & RBAC</a></li>
|
||||
</ul>
|
||||
<hr />
|
||||
<p><strong>Integration Status</strong>: ✅ Active
|
||||
<strong>Services</strong>: Backend, Agents, LLM Router
|
||||
<strong>Features</strong>: server, surrealdb-storage, cedar-policies</p>
|
||||
|
||||
</main>
|
||||
|
||||
<nav class="nav-wrapper" aria-label="Page navigation">
|
||||
<!-- Mobile navigation buttons -->
|
||||
<a rel="prev" href="../../setup/tracking-quickstart.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
|
||||
<i class="fa fa-angle-left"></i>
|
||||
</a>
|
||||
|
||||
<a rel="next prefetch" href="../../features/index.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
|
||||
<i class="fa fa-angle-right"></i>
|
||||
</a>
|
||||
|
||||
<div style="clear: both"></div>
|
||||
</nav>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<nav class="nav-wide-wrapper" aria-label="Page navigation">
|
||||
<a rel="prev" href="../../setup/tracking-quickstart.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
|
||||
<i class="fa fa-angle-left"></i>
|
||||
</a>
|
||||
|
||||
<a rel="next prefetch" href="../../features/index.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
|
||||
<i class="fa fa-angle-right"></i>
|
||||
</a>
|
||||
</nav>
|
||||
|
||||
</div>
|
||||
|
||||
|
||||
|
||||
|
||||
<script>
|
||||
window.playground_copyable = true;
|
||||
</script>
|
||||
|
||||
|
||||
<script src="../elasticlunr.min.js"></script>
|
||||
<script src="../mark.min.js"></script>
|
||||
<script src="../searcher.js"></script>
|
||||
|
||||
<script src="../clipboard.min.js"></script>
|
||||
<script src="../highlight.js"></script>
|
||||
<script src="../book.js"></script>
|
||||
|
||||
<!-- Custom JS scripts -->
|
||||
|
||||
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
890
docs/setup/setup-guide.html
Normal file
890
docs/setup/setup-guide.html
Normal file
@ -0,0 +1,890 @@
|
||||
<!DOCTYPE HTML>
|
||||
<html lang="en" class="light sidebar-visible" dir="ltr">
|
||||
<head>
|
||||
<!-- Book generated using mdBook -->
|
||||
<meta charset="UTF-8">
|
||||
<title>Setup Guide - VAPORA Platform Documentation</title>
|
||||
|
||||
|
||||
<!-- Custom HTML head -->
|
||||
|
||||
<meta name="description" content="Comprehensive documentation for VAPORA, an intelligent development orchestration platform built entirely in Rust.">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
<meta name="theme-color" content="#ffffff">
|
||||
|
||||
<link rel="icon" href="../favicon.svg">
|
||||
<link rel="shortcut icon" href="../favicon.png">
|
||||
<link rel="stylesheet" href="../css/variables.css">
|
||||
<link rel="stylesheet" href="../css/general.css">
|
||||
<link rel="stylesheet" href="../css/chrome.css">
|
||||
<link rel="stylesheet" href="../css/print.css" media="print">
|
||||
|
||||
<!-- Fonts -->
|
||||
<link rel="stylesheet" href="../FontAwesome/css/font-awesome.css">
|
||||
<link rel="stylesheet" href="../fonts/fonts.css">
|
||||
|
||||
<!-- Highlight.js Stylesheets -->
|
||||
<link rel="stylesheet" id="highlight-css" href="../highlight.css">
|
||||
<link rel="stylesheet" id="tomorrow-night-css" href="../tomorrow-night.css">
|
||||
<link rel="stylesheet" id="ayu-highlight-css" href="../ayu-highlight.css">
|
||||
|
||||
<!-- Custom theme stylesheets -->
|
||||
|
||||
|
||||
<!-- Provide site root and default themes to javascript -->
|
||||
<script>
|
||||
const path_to_root = "../";
|
||||
const default_light_theme = "light";
|
||||
const default_dark_theme = "dark";
|
||||
</script>
|
||||
<!-- Start loading toc.js asap -->
|
||||
<script src="../toc.js"></script>
|
||||
</head>
|
||||
<body>
|
||||
<div id="mdbook-help-container">
|
||||
<div id="mdbook-help-popup">
|
||||
<h2 class="mdbook-help-title">Keyboard shortcuts</h2>
|
||||
<div>
|
||||
<p>Press <kbd>←</kbd> or <kbd>→</kbd> to navigate between chapters</p>
|
||||
<p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
|
||||
<p>Press <kbd>?</kbd> to show this help</p>
|
||||
<p>Press <kbd>Esc</kbd> to hide this help</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<div id="body-container">
|
||||
<!-- Work around some values being stored in localStorage wrapped in quotes -->
|
||||
<script>
|
||||
try {
|
||||
let theme = localStorage.getItem('mdbook-theme');
|
||||
let sidebar = localStorage.getItem('mdbook-sidebar');
|
||||
|
||||
if (theme.startsWith('"') && theme.endsWith('"')) {
|
||||
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
|
||||
}
|
||||
|
||||
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
|
||||
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
|
||||
}
|
||||
} catch (e) { }
|
||||
</script>
|
||||
|
||||
<!-- Set the theme before any content is loaded, prevents flash -->
|
||||
<script>
|
||||
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
|
||||
let theme;
|
||||
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
|
||||
if (theme === null || theme === undefined) { theme = default_theme; }
|
||||
const html = document.documentElement;
|
||||
html.classList.remove('light')
|
||||
html.classList.add(theme);
|
||||
html.classList.add("js");
|
||||
</script>
|
||||
|
||||
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
|
||||
|
||||
<!-- Hide / unhide sidebar before it is displayed -->
|
||||
<script>
|
||||
let sidebar = null;
|
||||
const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
|
||||
if (document.body.clientWidth >= 1080) {
|
||||
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
|
||||
sidebar = sidebar || 'visible';
|
||||
} else {
|
||||
sidebar = 'hidden';
|
||||
}
|
||||
sidebar_toggle.checked = sidebar === 'visible';
|
||||
html.classList.remove('sidebar-visible');
|
||||
html.classList.add("sidebar-" + sidebar);
|
||||
</script>
|
||||
|
||||
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
|
||||
<!-- populated by js -->
|
||||
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
|
||||
<noscript>
|
||||
<iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
|
||||
</noscript>
|
||||
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
|
||||
<div class="sidebar-resize-indicator"></div>
|
||||
</div>
|
||||
</nav>
|
||||
|
||||
<div id="page-wrapper" class="page-wrapper">
|
||||
|
||||
<div class="page">
|
||||
<div id="menu-bar-hover-placeholder"></div>
|
||||
<div id="menu-bar" class="menu-bar sticky">
|
||||
<div class="left-buttons">
|
||||
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
|
||||
<i class="fa fa-bars"></i>
|
||||
</label>
|
||||
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
|
||||
<i class="fa fa-paint-brush"></i>
|
||||
</button>
|
||||
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
|
||||
<li role="none"><button role="menuitem" class="theme" id="default_theme">Auto</button></li>
|
||||
<li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
|
||||
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
|
||||
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
|
||||
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
|
||||
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
|
||||
</ul>
|
||||
<button id="search-toggle" class="icon-button" type="button" title="Search (`/`)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="/ s" aria-controls="searchbar">
|
||||
<i class="fa fa-search"></i>
|
||||
</button>
|
||||
</div>
|
||||
|
||||
<h1 class="menu-title">VAPORA Platform Documentation</h1>
|
||||
|
||||
<div class="right-buttons">
|
||||
<a href="../print.html" title="Print this book" aria-label="Print this book">
|
||||
<i id="print-button" class="fa fa-print"></i>
|
||||
</a>
|
||||
<a href="https://github.com/vapora-platform/vapora" title="Git repository" aria-label="Git repository">
|
||||
<i id="git-repository-button" class="fa fa-github"></i>
|
||||
</a>
|
||||
<a href="https://github.com/vapora-platform/vapora/edit/main/docs/src/../setup/setup-guide.md" title="Suggest an edit" aria-label="Suggest an edit">
|
||||
<i id="git-edit-button" class="fa fa-edit"></i>
|
||||
</a>
|
||||
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div id="search-wrapper" class="hidden">
|
||||
<form id="searchbar-outer" class="searchbar-outer">
|
||||
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
|
||||
</form>
|
||||
<div id="searchresults-outer" class="searchresults-outer hidden">
|
||||
<div id="searchresults-header" class="searchresults-header"></div>
|
||||
<ul id="searchresults">
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
|
||||
<script>
|
||||
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
|
||||
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
|
||||
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
|
||||
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
|
||||
});
|
||||
</script>
|
||||
|
||||
<div id="content" class="content">
|
||||
<main>
|
||||
<hr />
|
||||
<h2>title: Vapora Project - Complete Setup Guide
|
||||
date: 2025-11-10
|
||||
version: 1.0
|
||||
status: READY</h2>
|
||||
<h1 id="-vapora---complete-setup-guide"><a class="header" href="#-vapora---complete-setup-guide">🛠️ Vapora - Complete Setup Guide</a></h1>
|
||||
<p><strong>Complete step-by-step guide for setting up the entire Vapora project from scratch.</strong></p>
|
||||
<hr />
|
||||
<h2 id="-table-of-contents"><a class="header" href="#-table-of-contents">📋 Table of Contents</a></h2>
|
||||
<ol>
|
||||
<li><a href="#prerequisites--environment">Prerequisites & Environment</a></li>
|
||||
<li><a href="#installation">Installation</a></li>
|
||||
<li><a href="#configuration">Configuration</a></li>
|
||||
<li><a href="#building--testing">Building & Testing</a></li>
|
||||
<li><a href="#development-setup">Development Setup</a></li>
|
||||
<li><a href="#first-run">First Run</a></li>
|
||||
<li><a href="#troubleshooting">Troubleshooting</a></li>
|
||||
</ol>
|
||||
<hr />
|
||||
<h2 id="prerequisites--environment"><a class="header" href="#prerequisites--environment">Prerequisites & Environment</a></h2>
|
||||
<h3 id="system-requirements"><a class="header" href="#system-requirements">System Requirements</a></h3>
|
||||
<div class="table-wrapper"><table><thead><tr><th>Requirement</th><th>Minimum</th><th>Recommended</th></tr></thead><tbody>
|
||||
<tr><td>OS</td><td>macOS 10.15+</td><td>macOS 12+ (M1/M2 optimized)</td></tr>
|
||||
<tr><td>CPU</td><td>2-core</td><td>4+ cores</td></tr>
|
||||
<tr><td>RAM</td><td>4GB</td><td>8GB+</td></tr>
|
||||
<tr><td>Disk</td><td>2GB</td><td>5GB+</td></tr>
|
||||
<tr><td>Internet</td><td>Required</td><td>Required</td></tr>
|
||||
</tbody></table>
|
||||
</div>
|
||||
<h3 id="software-requirements"><a class="header" href="#software-requirements">Software Requirements</a></h3>
|
||||
<p><strong>Required:</strong></p>
|
||||
<ul>
|
||||
<li>Rust 1.75+ (install from https://rustup.rs)</li>
|
||||
<li>Cargo (comes with Rust)</li>
|
||||
<li>Git 2.20+</li>
|
||||
<li>NuShell 0.95+ (for scripts)</li>
|
||||
</ul>
|
||||
<p><strong>Optional but Recommended:</strong></p>
|
||||
<ul>
|
||||
<li>Node.js 18+ (for frontend tooling)</li>
|
||||
<li>Docker (for containerization)</li>
|
||||
<li>Kubernetes tools (kubectl, k3s for deployment)</li>
|
||||
</ul>
|
||||
<h3 id="prerequisite-check-script"><a class="header" href="#prerequisite-check-script">Prerequisite Check Script</a></h3>
|
||||
<pre><code class="language-bash">#!/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!"
|
||||
</code></pre>
|
||||
<p>Save as <code>check-prerequisites.sh</code> and run:</p>
|
||||
<pre><code class="language-bash">chmod +x check-prerequisites.sh
|
||||
./check-prerequisites.sh
|
||||
</code></pre>
|
||||
<hr />
|
||||
<h2 id="installation"><a class="header" href="#installation">Installation</a></h2>
|
||||
<h3 id="step-1-prepare-your-environment"><a class="header" href="#step-1-prepare-your-environment">Step 1: Prepare Your Environment</a></h3>
|
||||
<pre><code class="language-bash"># 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
|
||||
</code></pre>
|
||||
<h3 id="step-2-install-nushell-if-needed"><a class="header" href="#step-2-install-nushell-if-needed">Step 2: Install NuShell (if needed)</a></h3>
|
||||
<pre><code class="language-bash"># macOS with Homebrew
|
||||
brew install nu
|
||||
|
||||
# Or from source (if on other OS)
|
||||
# See https://www.nushell.sh/book/installation.html
|
||||
</code></pre>
|
||||
<p>Verify:</p>
|
||||
<pre><code class="language-bash">nu --version # Should be 0.95+
|
||||
</code></pre>
|
||||
<h3 id="step-3-install-frontend-tools-if-building-frontend"><a class="header" href="#step-3-install-frontend-tools-if-building-frontend">Step 3: Install Frontend Tools (if building frontend)</a></h3>
|
||||
<pre><code class="language-bash"># Install trunk for Leptos WASM building
|
||||
cargo install trunk
|
||||
|
||||
# Install wasm-pack for WASM compilation
|
||||
rustup target add wasm32-unknown-unknown
|
||||
</code></pre>
|
||||
<h3 id="step-4-download-workspace-dependencies"><a class="header" href="#step-4-download-workspace-dependencies">Step 4: Download Workspace Dependencies</a></h3>
|
||||
<pre><code class="language-bash"># Download all dependencies (no compilation yet)
|
||||
cargo fetch
|
||||
|
||||
# This may take 2-3 minutes depending on internet speed
|
||||
</code></pre>
|
||||
<h3 id="step-5-verify-workspace-structure"><a class="header" href="#step-5-verify-workspace-structure">Step 5: Verify Workspace Structure</a></h3>
|
||||
<pre><code class="language-bash"># 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/
|
||||
</code></pre>
|
||||
<hr />
|
||||
<h2 id="configuration"><a class="header" href="#configuration">Configuration</a></h2>
|
||||
<h3 id="option-1-default-configuration-recommended"><a class="header" href="#option-1-default-configuration-recommended">Option 1: Default Configuration (Recommended)</a></h3>
|
||||
<p>The project works out of the box with sensible defaults:</p>
|
||||
<pre><code class="language-yaml"># 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
|
||||
</code></pre>
|
||||
<p><strong>No configuration needed to start developing!</strong> Skip to <a href="#building--testing">Building & Testing</a>.</p>
|
||||
<h3 id="option-2-environment-variables"><a class="header" href="#option-2-environment-variables">Option 2: Environment Variables</a></h3>
|
||||
<p>Create <code>.env</code> file in project root:</p>
|
||||
<pre><code class="language-bash"># 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
|
||||
</code></pre>
|
||||
<p>Load with:</p>
|
||||
<pre><code class="language-bash">export $(cat .env | xargs)
|
||||
</code></pre>
|
||||
<h3 id="option-3-configuration-file"><a class="header" href="#option-3-configuration-file">Option 3: Configuration File</a></h3>
|
||||
<p>Create <code>~/.vapora/config.toml</code>:</p>
|
||||
<pre><code class="language-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"
|
||||
</code></pre>
|
||||
<hr />
|
||||
<h2 id="building--testing"><a class="header" href="#building--testing">Building & Testing</a></h2>
|
||||
<h3 id="phase-1-build-all-crates"><a class="header" href="#phase-1-build-all-crates">Phase 1: Build All Crates</a></h3>
|
||||
<pre><code class="language-bash"># 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)
|
||||
</code></pre>
|
||||
<h3 id="phase-2-run-full-test-suite"><a class="header" href="#phase-2-run-full-test-suite">Phase 2: Run Full Test Suite</a></h3>
|
||||
<pre><code class="language-bash"># 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
|
||||
</code></pre>
|
||||
<h3 id="phase-3-code-quality-checks"><a class="header" href="#phase-3-code-quality-checks">Phase 3: Code Quality Checks</a></h3>
|
||||
<pre><code class="language-bash"># 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
|
||||
</code></pre>
|
||||
<h3 id="phase-4-documentation"><a class="header" href="#phase-4-documentation">Phase 4: Documentation</a></h3>
|
||||
<pre><code class="language-bash"># 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
|
||||
</code></pre>
|
||||
<h3 id="verification-checklist"><a class="header" href="#verification-checklist">Verification Checklist</a></h3>
|
||||
<pre><code class="language-bash">#!/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!"
|
||||
</code></pre>
|
||||
<hr />
|
||||
<h2 id="development-setup"><a class="header" href="#development-setup">Development Setup</a></h2>
|
||||
<h3 id="ide-setup"><a class="header" href="#ide-setup">IDE Setup</a></h3>
|
||||
<p><strong>VS Code (Recommended)</strong></p>
|
||||
<pre><code class="language-bash"># 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
|
||||
}
|
||||
</code></pre>
|
||||
<p><strong>IntelliJ IDEA / CLion</strong></p>
|
||||
<pre><code class="language-bash"># Install Rust plugin
|
||||
# Settings → Plugins → Rust → Install
|
||||
|
||||
# Recommended settings:
|
||||
# Rust → Clippy → Use Clippy instead of Cargo check
|
||||
# Rust → Macro Expansion → Expand experimental attribute macros
|
||||
</code></pre>
|
||||
<h3 id="git-setup"><a class="header" href="#git-setup">Git Setup</a></h3>
|
||||
<pre><code class="language-bash"># 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
|
||||
</code></pre>
|
||||
<h3 id="development-workflow"><a class="header" href="#development-workflow">Development Workflow</a></h3>
|
||||
<pre><code class="language-bash"># 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
|
||||
</code></pre>
|
||||
<hr />
|
||||
<h2 id="first-run"><a class="header" href="#first-run">First Run</a></h2>
|
||||
<h3 id="run-backend-server"><a class="header" href="#run-backend-server">Run Backend Server</a></h3>
|
||||
<p><strong>Terminal 1: Backend</strong></p>
|
||||
<pre><code class="language-bash"># 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
|
||||
</code></pre>
|
||||
<h3 id="run-frontend-optional"><a class="header" href="#run-frontend-optional">Run Frontend (Optional)</a></h3>
|
||||
<p><strong>Terminal 2: Frontend</strong></p>
|
||||
<pre><code class="language-bash">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
|
||||
</code></pre>
|
||||
<h3 id="test-endpoints"><a class="header" href="#test-endpoints">Test Endpoints</a></h3>
|
||||
<p><strong>Terminal 3: Test</strong></p>
|
||||
<pre><code class="language-bash"># 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"}'
|
||||
</code></pre>
|
||||
<h3 id="using-cli-commands"><a class="header" href="#using-cli-commands">Using CLI Commands</a></h3>
|
||||
<pre><code class="language-bash"># 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
|
||||
</code></pre>
|
||||
<hr />
|
||||
<h2 id="troubleshooting"><a class="header" href="#troubleshooting">Troubleshooting</a></h2>
|
||||
<h3 id="build-issues"><a class="header" href="#build-issues">Build Issues</a></h3>
|
||||
<p><strong>Error: "error[E0433]: failed to resolve: use of undeclared type"</strong></p>
|
||||
<p>Solution:</p>
|
||||
<pre><code class="language-bash"># Update Rust
|
||||
rustup update stable
|
||||
|
||||
# Clean cache
|
||||
cargo clean
|
||||
|
||||
# Rebuild
|
||||
cargo build
|
||||
</code></pre>
|
||||
<p><strong>Error: "could not compile ... due to X previous errors"</strong></p>
|
||||
<p>Solution:</p>
|
||||
<pre><code class="language-bash"># Check Rust version (must be 1.75+)
|
||||
rustc --version
|
||||
|
||||
# Update if needed
|
||||
rustup install 1.75
|
||||
rustup default 1.75
|
||||
</code></pre>
|
||||
<p><strong>Error: "linker 'cc' not found"</strong></p>
|
||||
<p>Solution (macOS):</p>
|
||||
<pre><code class="language-bash"># Install Xcode command line tools
|
||||
xcode-select --install
|
||||
</code></pre>
|
||||
<h3 id="test-issues"><a class="header" href="#test-issues">Test Issues</a></h3>
|
||||
<p><strong>Tests fail with timeout</strong></p>
|
||||
<p>Solution:</p>
|
||||
<pre><code class="language-bash"># Run with single thread
|
||||
cargo test --lib -- --test-threads=1
|
||||
|
||||
# Increase timeout
|
||||
RUST_TEST_TIME_UNIT=60000 cargo test --lib
|
||||
</code></pre>
|
||||
<p><strong>Tests panic with "thread 'main' panicked"</strong></p>
|
||||
<p>Solution:</p>
|
||||
<pre><code class="language-bash"># Run with backtrace
|
||||
RUST_BACKTRACE=1 cargo test --lib -- --nocapture
|
||||
|
||||
# Check logs for actual error
|
||||
RUST_LOG=trace cargo test --lib -- --nocapture
|
||||
</code></pre>
|
||||
<h3 id="database-issues"><a class="header" href="#database-issues">Database Issues</a></h3>
|
||||
<p><strong>Error: "database file not found"</strong></p>
|
||||
<p>Solution:</p>
|
||||
<pre><code class="language-bash"># Create database directory
|
||||
mkdir -p ~/.tracking
|
||||
mkdir -p ~/.vapora
|
||||
|
||||
# Initialize databases
|
||||
./scripts/start-tracking-service.nu
|
||||
|
||||
# Wait for init and stop with Ctrl+C
|
||||
</code></pre>
|
||||
<p><strong>Error: "Failed to acquire database lock"</strong></p>
|
||||
<p>Solution:</p>
|
||||
<pre><code class="language-bash"># 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
|
||||
</code></pre>
|
||||
<h3 id="port-already-in-use"><a class="header" href="#port-already-in-use">Port Already in Use</a></h3>
|
||||
<p><strong>Error: "Address already in use"</strong></p>
|
||||
<p>Solution:</p>
|
||||
<pre><code class="language-bash"># 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
|
||||
</code></pre>
|
||||
<h3 id="nushell-script-issues"><a class="header" href="#nushell-script-issues">NuShell Script Issues</a></h3>
|
||||
<p><strong>Error: "command not found: nu"</strong></p>
|
||||
<p>Solution:</p>
|
||||
<pre><code class="language-bash"># Install NuShell
|
||||
brew install nu
|
||||
|
||||
# Or add to PATH
|
||||
export PATH="/usr/local/bin:$PATH"
|
||||
</code></pre>
|
||||
<p><strong>Scripts not executable</strong></p>
|
||||
<p>Solution:</p>
|
||||
<pre><code class="language-bash"># Make scripts executable
|
||||
chmod +x scripts/*.nu
|
||||
|
||||
# Run with nu explicitly
|
||||
nu scripts/start-tracking-service.nu
|
||||
</code></pre>
|
||||
<h3 id="frontend-issues"><a class="header" href="#frontend-issues">Frontend Issues</a></h3>
|
||||
<p><strong>Error: "trunk: command not found"</strong></p>
|
||||
<p>Solution:</p>
|
||||
<pre><code class="language-bash"># Install trunk
|
||||
cargo install trunk
|
||||
|
||||
# Install WASM target
|
||||
rustup target add wasm32-unknown-unknown
|
||||
</code></pre>
|
||||
<p><strong>Frontend won't load styles</strong></p>
|
||||
<p>Solution:</p>
|
||||
<pre><code class="language-bash"># Clear build cache
|
||||
rm -rf crates/vapora-frontend/target
|
||||
rm -rf crates/vapora-frontend/dist
|
||||
|
||||
# Rebuild
|
||||
cd crates/vapora-frontend && trunk serve
|
||||
</code></pre>
|
||||
<h3 id="quick-troubleshooting-reference"><a class="header" href="#quick-troubleshooting-reference">Quick Troubleshooting Reference</a></h3>
|
||||
<div class="table-wrapper"><table><thead><tr><th>Problem</th><th>Quick Fix</th></tr></thead><tbody>
|
||||
<tr><td>Build fails</td><td><code>cargo clean && cargo build</code></td></tr>
|
||||
<tr><td>Tests fail</td><td><code>rustup update && cargo test --lib</code></td></tr>
|
||||
<tr><td>Port in use</td><td><code>lsof -i :3000 && kill -9 <PID></code></td></tr>
|
||||
<tr><td>DB errors</td><td><code>rm ~/.vapora/data.db && cargo run</code></td></tr>
|
||||
<tr><td>NuShell missing</td><td><code>brew install nu</code></td></tr>
|
||||
<tr><td>Clippy warnings</td><td><code>cargo clippy -- -W clippy::all</code></td></tr>
|
||||
<tr><td>Format issues</td><td><code>cargo fmt</code></td></tr>
|
||||
<tr><td>Slow build</td><td><code>export CARGO_INCREMENTAL=1</code></td></tr>
|
||||
</tbody></table>
|
||||
</div>
|
||||
<hr />
|
||||
<h2 id="verification-steps"><a class="header" href="#verification-steps">Verification Steps</a></h2>
|
||||
<h3 id="post-installation-verification"><a class="header" href="#post-installation-verification">Post-Installation Verification</a></h3>
|
||||
<pre><code class="language-bash">#!/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!"
|
||||
</code></pre>
|
||||
<hr />
|
||||
<h2 id="whats-next"><a class="header" href="#whats-next">What's Next?</a></h2>
|
||||
<h3 id="immediate-next-steps"><a class="header" href="#immediate-next-steps">Immediate Next Steps</a></h3>
|
||||
<ol>
|
||||
<li>Read <a href="./QUICKSTART.html"><code>QUICKSTART.md</code></a> for 15-minute quick start</li>
|
||||
<li>Run backend: <code>cargo run -p vapora-backend</code></li>
|
||||
<li>Visit frontend: <code>http://localhost:8080</code></li>
|
||||
<li>Create first tracking entry: <code>/log-change "Setup complete"</code></li>
|
||||
</ol>
|
||||
<h3 id="learning-resources"><a class="header" href="#learning-resources">Learning Resources</a></h3>
|
||||
<ul>
|
||||
<li>API Documentation: <code>cargo doc --open</code></li>
|
||||
<li>Crate READMEs: <code>crates/*/README.md</code></li>
|
||||
<li>Tracking System: <a href="./QUICKSTART_TRACKING.html"><code>QUICKSTART_TRACKING.md</code></a></li>
|
||||
<li>Architecture: <a href="./.coder/"><code>.coder/</code></a></li>
|
||||
</ul>
|
||||
<h3 id="development-tips"><a class="header" href="#development-tips">Development Tips</a></h3>
|
||||
<ul>
|
||||
<li>Use <code>cargo watch</code> for continuous building</li>
|
||||
<li>Set <code>RUST_LOG=debug</code> for detailed logs</li>
|
||||
<li>Use IDE debugging (VS Code + CodeLLDB)</li>
|
||||
<li>Join community for help</li>
|
||||
</ul>
|
||||
<hr />
|
||||
<h2 id="getting-help"><a class="header" href="#getting-help">Getting Help</a></h2>
|
||||
<p><strong>Issues not listed above?</strong></p>
|
||||
<ol>
|
||||
<li>Check crate-specific documentation: <code>cargo doc --open</code></li>
|
||||
<li>Review <code>.coder/</code> documentation for architecture</li>
|
||||
<li>Check inline code comments</li>
|
||||
<li>Run with <code>RUST_LOG=trace</code> for detailed logs</li>
|
||||
<li>See <a href="./QUICKSTART.html"><code>QUICKSTART.md</code></a> for quick reference</li>
|
||||
</ol>
|
||||
<hr />
|
||||
<h2 id="-setup-completion-checklist"><a class="header" href="#-setup-completion-checklist">✅ Setup Completion Checklist</a></h2>
|
||||
<ul>
|
||||
<li><input disabled="" type="checkbox"/>
|
||||
Rust 1.75+ installed</li>
|
||||
<li><input disabled="" type="checkbox"/>
|
||||
All prerequisites verified</li>
|
||||
<li><input disabled="" type="checkbox"/>
|
||||
Repository cloned</li>
|
||||
<li><input disabled="" type="checkbox"/>
|
||||
Dependencies downloaded (<code>cargo fetch</code>)</li>
|
||||
<li><input disabled="" type="checkbox"/>
|
||||
Workspace builds successfully (<code>cargo build</code>)</li>
|
||||
<li><input disabled="" type="checkbox"/>
|
||||
All tests pass (<code>cargo test --lib</code>)</li>
|
||||
<li><input disabled="" type="checkbox"/>
|
||||
Code quality checks pass (<code>cargo clippy</code>)</li>
|
||||
<li><input disabled="" type="checkbox"/>
|
||||
Backend runs (<code>cargo run -p vapora-backend</code>)</li>
|
||||
<li><input disabled="" type="checkbox"/>
|
||||
Frontend loads (optional)</li>
|
||||
<li><input disabled="" type="checkbox"/>
|
||||
Tracking system works (<code>/track-status</code>)</li>
|
||||
</ul>
|
||||
<p><strong>All checked? ✅ Vapora is ready for development!</strong></p>
|
||||
<hr />
|
||||
<p><strong>For quick 15-minute setup:</strong> See <a href="./QUICKSTART.html"><code>QUICKSTART.md</code></a></p>
|
||||
<p><strong>For tracking system setup:</strong> See <a href="./SETUP_TRACKING.html"><code>SETUP_TRACKING.md</code></a></p>
|
||||
|
||||
</main>
|
||||
|
||||
<nav class="nav-wrapper" aria-label="Page navigation">
|
||||
<!-- Mobile navigation buttons -->
|
||||
<a rel="prev" href="../../setup/index.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
|
||||
<i class="fa fa-angle-left"></i>
|
||||
</a>
|
||||
|
||||
<a rel="next prefetch" href="../../setup/deployment.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
|
||||
<i class="fa fa-angle-right"></i>
|
||||
</a>
|
||||
|
||||
<div style="clear: both"></div>
|
||||
</nav>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<nav class="nav-wide-wrapper" aria-label="Page navigation">
|
||||
<a rel="prev" href="../../setup/index.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
|
||||
<i class="fa fa-angle-left"></i>
|
||||
</a>
|
||||
|
||||
<a rel="next prefetch" href="../../setup/deployment.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
|
||||
<i class="fa fa-angle-right"></i>
|
||||
</a>
|
||||
</nav>
|
||||
|
||||
</div>
|
||||
|
||||
|
||||
|
||||
|
||||
<script>
|
||||
window.playground_copyable = true;
|
||||
</script>
|
||||
|
||||
|
||||
<script src="../elasticlunr.min.js"></script>
|
||||
<script src="../mark.min.js"></script>
|
||||
<script src="../searcher.js"></script>
|
||||
|
||||
<script src="../clipboard.min.js"></script>
|
||||
<script src="../highlight.js"></script>
|
||||
<script src="../book.js"></script>
|
||||
|
||||
<!-- Custom JS scripts -->
|
||||
|
||||
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@ -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
|
||||
|
||||
435
docs/setup/tracking-quickstart.html
Normal file
435
docs/setup/tracking-quickstart.html
Normal file
@ -0,0 +1,435 @@
|
||||
<!DOCTYPE HTML>
|
||||
<html lang="en" class="light sidebar-visible" dir="ltr">
|
||||
<head>
|
||||
<!-- Book generated using mdBook -->
|
||||
<meta charset="UTF-8">
|
||||
<title>Tracking Quickstart - VAPORA Platform Documentation</title>
|
||||
|
||||
|
||||
<!-- Custom HTML head -->
|
||||
|
||||
<meta name="description" content="Comprehensive documentation for VAPORA, an intelligent development orchestration platform built entirely in Rust.">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
<meta name="theme-color" content="#ffffff">
|
||||
|
||||
<link rel="icon" href="../favicon.svg">
|
||||
<link rel="shortcut icon" href="../favicon.png">
|
||||
<link rel="stylesheet" href="../css/variables.css">
|
||||
<link rel="stylesheet" href="../css/general.css">
|
||||
<link rel="stylesheet" href="../css/chrome.css">
|
||||
<link rel="stylesheet" href="../css/print.css" media="print">
|
||||
|
||||
<!-- Fonts -->
|
||||
<link rel="stylesheet" href="../FontAwesome/css/font-awesome.css">
|
||||
<link rel="stylesheet" href="../fonts/fonts.css">
|
||||
|
||||
<!-- Highlight.js Stylesheets -->
|
||||
<link rel="stylesheet" id="highlight-css" href="../highlight.css">
|
||||
<link rel="stylesheet" id="tomorrow-night-css" href="../tomorrow-night.css">
|
||||
<link rel="stylesheet" id="ayu-highlight-css" href="../ayu-highlight.css">
|
||||
|
||||
<!-- Custom theme stylesheets -->
|
||||
|
||||
|
||||
<!-- Provide site root and default themes to javascript -->
|
||||
<script>
|
||||
const path_to_root = "../";
|
||||
const default_light_theme = "light";
|
||||
const default_dark_theme = "dark";
|
||||
</script>
|
||||
<!-- Start loading toc.js asap -->
|
||||
<script src="../toc.js"></script>
|
||||
</head>
|
||||
<body>
|
||||
<div id="mdbook-help-container">
|
||||
<div id="mdbook-help-popup">
|
||||
<h2 class="mdbook-help-title">Keyboard shortcuts</h2>
|
||||
<div>
|
||||
<p>Press <kbd>←</kbd> or <kbd>→</kbd> to navigate between chapters</p>
|
||||
<p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
|
||||
<p>Press <kbd>?</kbd> to show this help</p>
|
||||
<p>Press <kbd>Esc</kbd> to hide this help</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<div id="body-container">
|
||||
<!-- Work around some values being stored in localStorage wrapped in quotes -->
|
||||
<script>
|
||||
try {
|
||||
let theme = localStorage.getItem('mdbook-theme');
|
||||
let sidebar = localStorage.getItem('mdbook-sidebar');
|
||||
|
||||
if (theme.startsWith('"') && theme.endsWith('"')) {
|
||||
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
|
||||
}
|
||||
|
||||
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
|
||||
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
|
||||
}
|
||||
} catch (e) { }
|
||||
</script>
|
||||
|
||||
<!-- Set the theme before any content is loaded, prevents flash -->
|
||||
<script>
|
||||
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
|
||||
let theme;
|
||||
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
|
||||
if (theme === null || theme === undefined) { theme = default_theme; }
|
||||
const html = document.documentElement;
|
||||
html.classList.remove('light')
|
||||
html.classList.add(theme);
|
||||
html.classList.add("js");
|
||||
</script>
|
||||
|
||||
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
|
||||
|
||||
<!-- Hide / unhide sidebar before it is displayed -->
|
||||
<script>
|
||||
let sidebar = null;
|
||||
const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
|
||||
if (document.body.clientWidth >= 1080) {
|
||||
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
|
||||
sidebar = sidebar || 'visible';
|
||||
} else {
|
||||
sidebar = 'hidden';
|
||||
}
|
||||
sidebar_toggle.checked = sidebar === 'visible';
|
||||
html.classList.remove('sidebar-visible');
|
||||
html.classList.add("sidebar-" + sidebar);
|
||||
</script>
|
||||
|
||||
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
|
||||
<!-- populated by js -->
|
||||
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
|
||||
<noscript>
|
||||
<iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
|
||||
</noscript>
|
||||
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
|
||||
<div class="sidebar-resize-indicator"></div>
|
||||
</div>
|
||||
</nav>
|
||||
|
||||
<div id="page-wrapper" class="page-wrapper">
|
||||
|
||||
<div class="page">
|
||||
<div id="menu-bar-hover-placeholder"></div>
|
||||
<div id="menu-bar" class="menu-bar sticky">
|
||||
<div class="left-buttons">
|
||||
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
|
||||
<i class="fa fa-bars"></i>
|
||||
</label>
|
||||
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
|
||||
<i class="fa fa-paint-brush"></i>
|
||||
</button>
|
||||
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
|
||||
<li role="none"><button role="menuitem" class="theme" id="default_theme">Auto</button></li>
|
||||
<li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
|
||||
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
|
||||
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
|
||||
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
|
||||
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
|
||||
</ul>
|
||||
<button id="search-toggle" class="icon-button" type="button" title="Search (`/`)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="/ s" aria-controls="searchbar">
|
||||
<i class="fa fa-search"></i>
|
||||
</button>
|
||||
</div>
|
||||
|
||||
<h1 class="menu-title">VAPORA Platform Documentation</h1>
|
||||
|
||||
<div class="right-buttons">
|
||||
<a href="../print.html" title="Print this book" aria-label="Print this book">
|
||||
<i id="print-button" class="fa fa-print"></i>
|
||||
</a>
|
||||
<a href="https://github.com/vapora-platform/vapora" title="Git repository" aria-label="Git repository">
|
||||
<i id="git-repository-button" class="fa fa-github"></i>
|
||||
</a>
|
||||
<a href="https://github.com/vapora-platform/vapora/edit/main/docs/src/../setup/tracking-quickstart.md" title="Suggest an edit" aria-label="Suggest an edit">
|
||||
<i id="git-edit-button" class="fa fa-edit"></i>
|
||||
</a>
|
||||
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div id="search-wrapper" class="hidden">
|
||||
<form id="searchbar-outer" class="searchbar-outer">
|
||||
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
|
||||
</form>
|
||||
<div id="searchresults-outer" class="searchresults-outer hidden">
|
||||
<div id="searchresults-header" class="searchresults-header"></div>
|
||||
<ul id="searchresults">
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
|
||||
<script>
|
||||
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
|
||||
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
|
||||
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
|
||||
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
|
||||
});
|
||||
</script>
|
||||
|
||||
<div id="content" class="content">
|
||||
<main>
|
||||
<hr />
|
||||
<h2>title: Vapora Tracking System - Quick Start Guide
|
||||
date: 2025-11-10
|
||||
status: READY
|
||||
type: tracking-quickstart</h2>
|
||||
<h1 id="-vapora-tracking-system---quick-start-guide"><a class="header" href="#-vapora-tracking-system---quick-start-guide">🚀 Vapora Tracking System - Quick Start Guide</a></h1>
|
||||
<p><strong>⏱️ Time to get running: 5-10 minutes</strong></p>
|
||||
<p>This guide walks you through installing and getting started with the Vapora tracking system component in the simplest way possible.</p>
|
||||
<p><strong>Note:</strong> This guide is for the tracking system only. For complete Vapora project setup, see <a href="./QUICKSTART.html"><code>QUICKSTART.md</code></a>.</p>
|
||||
<hr />
|
||||
<h2 id="-prerequisites"><a class="header" href="#-prerequisites">📋 Prerequisites</a></h2>
|
||||
<p>You need:</p>
|
||||
<ul>
|
||||
<li>✅ Rust 1.70+ (install from https://rustup.rs)</li>
|
||||
<li>✅ Cargo (comes with Rust)</li>
|
||||
<li>✅ Git</li>
|
||||
<li>✅ 500MB free disk space</li>
|
||||
<li>✅ Bash or Zsh shell</li>
|
||||
</ul>
|
||||
<p><strong>Check if you have everything:</strong></p>
|
||||
<pre><code class="language-bash">rustc --version # Should show Rust 1.70+
|
||||
cargo --version # Should show Cargo 1.70+
|
||||
which git # Should show /usr/bin/git or similar
|
||||
</code></pre>
|
||||
<hr />
|
||||
<h2 id="-5-minute-quick-start"><a class="header" href="#-5-minute-quick-start">🎯 5-Minute Quick Start</a></h2>
|
||||
<h3 id="step-1-build-the-tracking-system"><a class="header" href="#step-1-build-the-tracking-system">Step 1: Build the Tracking System</a></h3>
|
||||
<pre><code class="language-bash"># Build the tracking crate
|
||||
cargo build -p vapora-tracking
|
||||
|
||||
# Or with backend integration
|
||||
cargo build -p vapora-backend
|
||||
</code></pre>
|
||||
<p><strong>Expected output:</strong></p>
|
||||
<pre><code> Finished `dev` profile [unoptimized + debuginfo] target(s) in X.XXs
|
||||
</code></pre>
|
||||
<h3 id="step-3-run-tests"><a class="header" href="#step-3-run-tests">Step 3: Run Tests</a></h3>
|
||||
<pre><code class="language-bash"># Verify everything works
|
||||
cargo test -p vapora-tracking --lib
|
||||
|
||||
# Should show: test result: ok. 20 passed
|
||||
</code></pre>
|
||||
<h3 id="step-4-start-using-it"><a class="header" href="#step-4-start-using-it">Step 4: Start Using It</a></h3>
|
||||
<p><strong>Option A: Using Slash Commands (Easiest)</strong></p>
|
||||
<pre><code class="language-bash"># 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
|
||||
</code></pre>
|
||||
<p><strong>Option B: Using Scripts (Manual Sync)</strong></p>
|
||||
<pre><code class="language-bash"># 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
|
||||
</code></pre>
|
||||
<p><strong>Option C: Using API (Integration)</strong></p>
|
||||
<pre><code class="language-bash"># Query the API
|
||||
curl http://localhost:3000/api/v1/tracking/summary
|
||||
curl http://localhost:3000/api/v1/tracking/entries?limit=10
|
||||
</code></pre>
|
||||
<hr />
|
||||
<h2 id="-verify-installation"><a class="header" href="#-verify-installation">✅ Verify Installation</a></h2>
|
||||
<p>After building, verify everything works:</p>
|
||||
<h3 id="test-1-build-success"><a class="header" href="#test-1-build-success">Test 1: Build Success</a></h3>
|
||||
<pre><code class="language-bash">cargo build -p vapora-tracking 2>&1 | tail -3
|
||||
# Should show: Finished `dev` profile [unoptimized + debuginfo]
|
||||
</code></pre>
|
||||
<h3 id="test-2-tests-pass"><a class="header" href="#test-2-tests-pass">Test 2: Tests Pass</a></h3>
|
||||
<pre><code class="language-bash">cargo test -p vapora-tracking --lib 2>&1 | grep "test result"
|
||||
# Should show: test result: ok. 20 passed; 0 failed
|
||||
</code></pre>
|
||||
<h3 id="test-3-clippy-clean"><a class="header" href="#test-3-clippy-clean">Test 3: Clippy Clean</a></h3>
|
||||
<pre><code class="language-bash">cargo clippy -p vapora-tracking --lib 2>&1 | grep "warning:" | wc -l
|
||||
# Should show: 1 (profile warning only, which is expected)
|
||||
</code></pre>
|
||||
<h3 id="test-4-commands-available"><a class="header" href="#test-4-commands-available">Test 4: Commands Available</a></h3>
|
||||
<pre><code class="language-bash">ls ~/.claude/commands/ | grep -E "log-change|add-todo|track-status"
|
||||
# Should show all 3 commands
|
||||
</code></pre>
|
||||
<h3 id="test-5-skill-available"><a class="header" href="#test-5-skill-available">Test 5: Skill Available</a></h3>
|
||||
<pre><code class="language-bash">ls ~/.claude/skills/tracking.md
|
||||
# Should show the file exists
|
||||
</code></pre>
|
||||
<p><strong>If all 5 tests pass: ✅ Installation Complete!</strong></p>
|
||||
<hr />
|
||||
<h2 id="-first-time-usage"><a class="header" href="#-first-time-usage">🎬 First Time Usage</a></h2>
|
||||
<h3 id="scenario-1-log-your-first-change"><a class="header" href="#scenario-1-log-your-first-change">Scenario 1: Log Your First Change</a></h3>
|
||||
<p><strong>Using Slash Command (Easiest):</strong></p>
|
||||
<pre><code class="language-bash">/log-change "Implemented user authentication" \
|
||||
--impact backend \
|
||||
--files 5
|
||||
</code></pre>
|
||||
<p><strong>What happens:</strong></p>
|
||||
<ol>
|
||||
<li>✅ Change is logged to database</li>
|
||||
<li>✅ Timestamp added automatically</li>
|
||||
<li>✅ Can be queried with <code>/track-status</code></li>
|
||||
</ol>
|
||||
<h3 id="scenario-2-create-your-first-todo"><a class="header" href="#scenario-2-create-your-first-todo">Scenario 2: Create Your First TODO</a></h3>
|
||||
<p><strong>Using Slash Command:</strong></p>
|
||||
<pre><code class="language-bash">/add-todo "Review code changes" \
|
||||
--priority H \
|
||||
--estimate M \
|
||||
--due 2025-11-15
|
||||
</code></pre>
|
||||
<p><strong>What happens:</strong></p>
|
||||
<ol>
|
||||
<li>✅ TODO created in database</li>
|
||||
<li>✅ Can be tracked with <code>/track-status</code></li>
|
||||
<li>✅ Shows up in exports</li>
|
||||
</ol>
|
||||
<h3 id="scenario-3-check-your-status"><a class="header" href="#scenario-3-check-your-status">Scenario 3: Check Your Status</a></h3>
|
||||
<p><strong>Using Slash Command:</strong></p>
|
||||
<pre><code class="language-bash">/track-status --limit 5
|
||||
</code></pre>
|
||||
<p><strong>Output:</strong></p>
|
||||
<pre><code>✅ 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
|
||||
</code></pre>
|
||||
<hr />
|
||||
<h2 id="-next-steps-after-installation"><a class="header" href="#-next-steps-after-installation">📚 Next Steps After Installation</a></h2>
|
||||
<h3 id="short-term-today"><a class="header" href="#short-term-today">Short Term (Today)</a></h3>
|
||||
<ol>
|
||||
<li>✅ Log 2-3 changes you've made</li>
|
||||
<li>✅ Create 2-3 TODOs for upcoming work</li>
|
||||
<li>✅ Run <code>/track-status</code> to see results</li>
|
||||
</ol>
|
||||
<h3 id="medium-term-this-week"><a class="header" href="#medium-term-this-week">Medium Term (This Week)</a></h3>
|
||||
<ol>
|
||||
<li>📝 Set up daily tracking in your workflow</li>
|
||||
<li>🔄 Sync multiple projects with <code>sync-tracking.nu</code></li>
|
||||
<li>📊 Export your tracking data with <code>export-tracking.nu</code></li>
|
||||
</ol>
|
||||
<h3 id="long-term-ongoing"><a class="header" href="#long-term-ongoing">Long Term (Ongoing)</a></h3>
|
||||
<ol>
|
||||
<li>📈 Monitor project progress via <code>/track-status</code></li>
|
||||
<li>🎯 Use for sprint planning and retrospectives</li>
|
||||
<li>📉 Generate reports from exported data</li>
|
||||
<li>🔗 Integrate with other Vapora services</li>
|
||||
</ol>
|
||||
<hr />
|
||||
<h2 id="-need-more-help"><a class="header" href="#-need-more-help">🆘 Need More Help?</a></h2>
|
||||
<div class="table-wrapper"><table><thead><tr><th>Question</th><th>Answer Location</th></tr></thead><tbody>
|
||||
<tr><td>How do I use the tracking system?</td><td><code>TRACKING_SYSTEM_STATUS.md</code> (How to use section)</td></tr>
|
||||
<tr><td>What are all the features?</td><td><code>crates/vapora-tracking/README.md</code> (Features section)</td></tr>
|
||||
<tr><td>How do I deploy it?</td><td><code>crates/vapora-tracking/INTEGRATION.md</code> (Deployment section)</td></tr>
|
||||
<tr><td>How do I fix an issue?</td><td><code>SETUP_TRACKING.md</code> (Troubleshooting section)</td></tr>
|
||||
<tr><td>What's the architecture?</td><td><code>TRACKING_DOCUMENTATION_INDEX.md</code></td></tr>
|
||||
</tbody></table>
|
||||
</div>
|
||||
<hr />
|
||||
<h2 id="-super-quick-reference"><a class="header" href="#-super-quick-reference">⚡ Super Quick Reference</a></h2>
|
||||
<pre><code class="language-bash"># 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
|
||||
</code></pre>
|
||||
<hr />
|
||||
<h2 id="-installation-checklist"><a class="header" href="#-installation-checklist">✅ Installation Checklist</a></h2>
|
||||
<ul>
|
||||
<li><input disabled="" type="checkbox"/>
|
||||
Rust 1.75+ installed</li>
|
||||
<li><input disabled="" type="checkbox"/>
|
||||
Vapora repo available</li>
|
||||
<li><input disabled="" type="checkbox"/>
|
||||
<code>cargo build -p vapora-tracking</code> succeeds</li>
|
||||
<li><input disabled="" type="checkbox"/>
|
||||
<code>cargo test -p vapora-tracking --lib</code> shows 20 passed</li>
|
||||
<li><input disabled="" type="checkbox"/>
|
||||
Slash commands copied to <code>~/.claude/commands/</code></li>
|
||||
<li><input disabled="" type="checkbox"/>
|
||||
Skill copied to <code>~/.claude/skills/</code></li>
|
||||
<li><input disabled="" type="checkbox"/>
|
||||
<code>/log-change</code> command works</li>
|
||||
<li><input disabled="" type="checkbox"/>
|
||||
<code>/track-status</code> shows results</li>
|
||||
</ul>
|
||||
<p><strong>All checked? ✅ You're ready to go!</strong></p>
|
||||
<hr />
|
||||
<p><strong>For complete Vapora project setup:</strong> See <a href="./QUICKSTART.html"><code>QUICKSTART.md</code></a></p>
|
||||
<p><strong>For tracking system deep dive:</strong> See <a href="./SETUP_TRACKING.html"><code>SETUP_TRACKING.md</code></a></p>
|
||||
|
||||
</main>
|
||||
|
||||
<nav class="nav-wrapper" aria-label="Page navigation">
|
||||
<!-- Mobile navigation buttons -->
|
||||
<a rel="prev" href="../../setup/tracking-setup.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
|
||||
<i class="fa fa-angle-left"></i>
|
||||
</a>
|
||||
|
||||
<a rel="next prefetch" href="../../setup/secretumvault-integration.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
|
||||
<i class="fa fa-angle-right"></i>
|
||||
</a>
|
||||
|
||||
<div style="clear: both"></div>
|
||||
</nav>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<nav class="nav-wide-wrapper" aria-label="Page navigation">
|
||||
<a rel="prev" href="../../setup/tracking-setup.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
|
||||
<i class="fa fa-angle-left"></i>
|
||||
</a>
|
||||
|
||||
<a rel="next prefetch" href="../../setup/secretumvault-integration.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
|
||||
<i class="fa fa-angle-right"></i>
|
||||
</a>
|
||||
</nav>
|
||||
|
||||
</div>
|
||||
|
||||
|
||||
|
||||
|
||||
<script>
|
||||
window.playground_copyable = true;
|
||||
</script>
|
||||
|
||||
|
||||
<script src="../elasticlunr.min.js"></script>
|
||||
<script src="../mark.min.js"></script>
|
||||
<script src="../searcher.js"></script>
|
||||
|
||||
<script src="../clipboard.min.js"></script>
|
||||
<script src="../highlight.js"></script>
|
||||
<script src="../book.js"></script>
|
||||
|
||||
<!-- Custom JS scripts -->
|
||||
|
||||
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@ -202,7 +202,7 @@ Impact: backend | Breaking: no | Files: 5
|
||||
|
||||
---
|
||||
|
||||
## 🆘 Need More Help?
|
||||
## 🆘 Need More Help
|
||||
|
||||
| Question | Answer Location |
|
||||
|----------|-----------------|
|
||||
|
||||
774
docs/setup/tracking-setup.html
Normal file
774
docs/setup/tracking-setup.html
Normal file
@ -0,0 +1,774 @@
|
||||
<!DOCTYPE HTML>
|
||||
<html lang="en" class="light sidebar-visible" dir="ltr">
|
||||
<head>
|
||||
<!-- Book generated using mdBook -->
|
||||
<meta charset="UTF-8">
|
||||
<title>Tracking Setup - VAPORA Platform Documentation</title>
|
||||
|
||||
|
||||
<!-- Custom HTML head -->
|
||||
|
||||
<meta name="description" content="Comprehensive documentation for VAPORA, an intelligent development orchestration platform built entirely in Rust.">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
<meta name="theme-color" content="#ffffff">
|
||||
|
||||
<link rel="icon" href="../favicon.svg">
|
||||
<link rel="shortcut icon" href="../favicon.png">
|
||||
<link rel="stylesheet" href="../css/variables.css">
|
||||
<link rel="stylesheet" href="../css/general.css">
|
||||
<link rel="stylesheet" href="../css/chrome.css">
|
||||
<link rel="stylesheet" href="../css/print.css" media="print">
|
||||
|
||||
<!-- Fonts -->
|
||||
<link rel="stylesheet" href="../FontAwesome/css/font-awesome.css">
|
||||
<link rel="stylesheet" href="../fonts/fonts.css">
|
||||
|
||||
<!-- Highlight.js Stylesheets -->
|
||||
<link rel="stylesheet" id="highlight-css" href="../highlight.css">
|
||||
<link rel="stylesheet" id="tomorrow-night-css" href="../tomorrow-night.css">
|
||||
<link rel="stylesheet" id="ayu-highlight-css" href="../ayu-highlight.css">
|
||||
|
||||
<!-- Custom theme stylesheets -->
|
||||
|
||||
|
||||
<!-- Provide site root and default themes to javascript -->
|
||||
<script>
|
||||
const path_to_root = "../";
|
||||
const default_light_theme = "light";
|
||||
const default_dark_theme = "dark";
|
||||
</script>
|
||||
<!-- Start loading toc.js asap -->
|
||||
<script src="../toc.js"></script>
|
||||
</head>
|
||||
<body>
|
||||
<div id="mdbook-help-container">
|
||||
<div id="mdbook-help-popup">
|
||||
<h2 class="mdbook-help-title">Keyboard shortcuts</h2>
|
||||
<div>
|
||||
<p>Press <kbd>←</kbd> or <kbd>→</kbd> to navigate between chapters</p>
|
||||
<p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
|
||||
<p>Press <kbd>?</kbd> to show this help</p>
|
||||
<p>Press <kbd>Esc</kbd> to hide this help</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<div id="body-container">
|
||||
<!-- Work around some values being stored in localStorage wrapped in quotes -->
|
||||
<script>
|
||||
try {
|
||||
let theme = localStorage.getItem('mdbook-theme');
|
||||
let sidebar = localStorage.getItem('mdbook-sidebar');
|
||||
|
||||
if (theme.startsWith('"') && theme.endsWith('"')) {
|
||||
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
|
||||
}
|
||||
|
||||
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
|
||||
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
|
||||
}
|
||||
} catch (e) { }
|
||||
</script>
|
||||
|
||||
<!-- Set the theme before any content is loaded, prevents flash -->
|
||||
<script>
|
||||
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
|
||||
let theme;
|
||||
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
|
||||
if (theme === null || theme === undefined) { theme = default_theme; }
|
||||
const html = document.documentElement;
|
||||
html.classList.remove('light')
|
||||
html.classList.add(theme);
|
||||
html.classList.add("js");
|
||||
</script>
|
||||
|
||||
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
|
||||
|
||||
<!-- Hide / unhide sidebar before it is displayed -->
|
||||
<script>
|
||||
let sidebar = null;
|
||||
const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
|
||||
if (document.body.clientWidth >= 1080) {
|
||||
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
|
||||
sidebar = sidebar || 'visible';
|
||||
} else {
|
||||
sidebar = 'hidden';
|
||||
}
|
||||
sidebar_toggle.checked = sidebar === 'visible';
|
||||
html.classList.remove('sidebar-visible');
|
||||
html.classList.add("sidebar-" + sidebar);
|
||||
</script>
|
||||
|
||||
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
|
||||
<!-- populated by js -->
|
||||
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
|
||||
<noscript>
|
||||
<iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
|
||||
</noscript>
|
||||
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
|
||||
<div class="sidebar-resize-indicator"></div>
|
||||
</div>
|
||||
</nav>
|
||||
|
||||
<div id="page-wrapper" class="page-wrapper">
|
||||
|
||||
<div class="page">
|
||||
<div id="menu-bar-hover-placeholder"></div>
|
||||
<div id="menu-bar" class="menu-bar sticky">
|
||||
<div class="left-buttons">
|
||||
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
|
||||
<i class="fa fa-bars"></i>
|
||||
</label>
|
||||
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
|
||||
<i class="fa fa-paint-brush"></i>
|
||||
</button>
|
||||
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
|
||||
<li role="none"><button role="menuitem" class="theme" id="default_theme">Auto</button></li>
|
||||
<li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
|
||||
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
|
||||
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
|
||||
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
|
||||
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
|
||||
</ul>
|
||||
<button id="search-toggle" class="icon-button" type="button" title="Search (`/`)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="/ s" aria-controls="searchbar">
|
||||
<i class="fa fa-search"></i>
|
||||
</button>
|
||||
</div>
|
||||
|
||||
<h1 class="menu-title">VAPORA Platform Documentation</h1>
|
||||
|
||||
<div class="right-buttons">
|
||||
<a href="../print.html" title="Print this book" aria-label="Print this book">
|
||||
<i id="print-button" class="fa fa-print"></i>
|
||||
</a>
|
||||
<a href="https://github.com/vapora-platform/vapora" title="Git repository" aria-label="Git repository">
|
||||
<i id="git-repository-button" class="fa fa-github"></i>
|
||||
</a>
|
||||
<a href="https://github.com/vapora-platform/vapora/edit/main/docs/src/../setup/tracking-setup.md" title="Suggest an edit" aria-label="Suggest an edit">
|
||||
<i id="git-edit-button" class="fa fa-edit"></i>
|
||||
</a>
|
||||
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div id="search-wrapper" class="hidden">
|
||||
<form id="searchbar-outer" class="searchbar-outer">
|
||||
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
|
||||
</form>
|
||||
<div id="searchresults-outer" class="searchresults-outer hidden">
|
||||
<div id="searchresults-header" class="searchresults-header"></div>
|
||||
<ul id="searchresults">
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
|
||||
<script>
|
||||
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
|
||||
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
|
||||
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
|
||||
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
|
||||
});
|
||||
</script>
|
||||
|
||||
<div id="content" class="content">
|
||||
<main>
|
||||
<hr />
|
||||
<h2>title: Vapora Tracking System - Complete Setup Guide
|
||||
date: 2025-11-10
|
||||
version: 1.0</h2>
|
||||
<h1 id="-vapora-tracking-system---complete-setup-guide"><a class="header" href="#-vapora-tracking-system---complete-setup-guide">🛠️ Vapora Tracking System - Complete Setup Guide</a></h1>
|
||||
<p><strong>This guide covers everything from zero to fully operational tracking system.</strong></p>
|
||||
<hr />
|
||||
<h2 id="-table-of-contents"><a class="header" href="#-table-of-contents">📋 Table of Contents</a></h2>
|
||||
<ol>
|
||||
<li><a href="#prerequisites">Prerequisites</a></li>
|
||||
<li><a href="#installation">Installation</a></li>
|
||||
<li><a href="#configuration">Configuration</a></li>
|
||||
<li><a href="#verification">Verification</a></li>
|
||||
<li><a href="#first-use">First Use</a></li>
|
||||
<li><a href="#troubleshooting">Troubleshooting</a></li>
|
||||
</ol>
|
||||
<hr />
|
||||
<h2 id="prerequisites"><a class="header" href="#prerequisites">Prerequisites</a></h2>
|
||||
<h3 id="system-requirements"><a class="header" href="#system-requirements">System Requirements</a></h3>
|
||||
<div class="table-wrapper"><table><thead><tr><th>Requirement</th><th>Minimum</th><th>Recommended</th></tr></thead><tbody>
|
||||
<tr><td>OS</td><td>macOS 10.15+</td><td>macOS 12+</td></tr>
|
||||
<tr><td>RAM</td><td>2GB</td><td>4GB+</td></tr>
|
||||
<tr><td>Disk</td><td>1GB</td><td>2GB+</td></tr>
|
||||
<tr><td>Internet</td><td>Required for install</td><td>Required</td></tr>
|
||||
</tbody></table>
|
||||
</div>
|
||||
<h3 id="software-requirements"><a class="header" href="#software-requirements">Software Requirements</a></h3>
|
||||
<pre><code class="language-bash"># Check if installed
|
||||
rustc --version # Need 1.70+
|
||||
cargo --version # Comes with Rust
|
||||
git --version # Need 2.20+
|
||||
</code></pre>
|
||||
<h3 id="installation-check"><a class="header" href="#installation-check">Installation Check</a></h3>
|
||||
<pre><code class="language-bash">#!/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!"
|
||||
</code></pre>
|
||||
<hr />
|
||||
<h2 id="installation"><a class="header" href="#installation">Installation</a></h2>
|
||||
<h3 id="step-1-install-rust-if-needed"><a class="header" href="#step-1-install-rust-if-needed">Step 1: Install Rust (if needed)</a></h3>
|
||||
<pre><code class="language-bash"># 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
|
||||
</code></pre>
|
||||
<p><strong>Expected output:</strong></p>
|
||||
<pre><code>rustc 1.XX.X (XXXXXXXXXXXX YYYY-MM-DD)
|
||||
cargo 1.XX.X (XXXXXXXXXXXX YYYY-MM-DD)
|
||||
</code></pre>
|
||||
<h3 id="step-2-clone-or-navigate-to-vapora"><a class="header" href="#step-2-clone-or-navigate-to-vapora">Step 2: Clone or Navigate to Vapora</a></h3>
|
||||
<pre><code class="language-bash"># 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/
|
||||
</code></pre>
|
||||
<h3 id="step-3-build-the-tracking-system"><a class="header" href="#step-3-build-the-tracking-system">Step 3: Build the Tracking System</a></h3>
|
||||
<pre><code class="language-bash"># 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]
|
||||
</code></pre>
|
||||
<p><strong>Build time:</strong></p>
|
||||
<ul>
|
||||
<li>Debug: 30-60 seconds (first time)</li>
|
||||
<li>Release: 2-5 minutes (first time)</li>
|
||||
<li>Subsequent: 1-10 seconds (incremental)</li>
|
||||
</ul>
|
||||
<h3 id="step-4-verify-build"><a class="header" href="#step-4-verify-build">Step 4: Verify Build</a></h3>
|
||||
<pre><code class="language-bash"># 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
|
||||
</code></pre>
|
||||
<h3 id="step-5-install-cli-components"><a class="header" href="#step-5-install-cli-components">Step 5: Install CLI Components</a></h3>
|
||||
<pre><code class="language-bash"># 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
|
||||
</code></pre>
|
||||
<hr />
|
||||
<h2 id="configuration"><a class="header" href="#configuration">Configuration</a></h2>
|
||||
<h3 id="option-1-default-configuration-recommended"><a class="header" href="#option-1-default-configuration-recommended">Option 1: Default Configuration (Recommended)</a></h3>
|
||||
<p>The system works out of the box with defaults:</p>
|
||||
<pre><code class="language-bash"># Default database location
|
||||
~/.tracking/database.sqlite
|
||||
|
||||
# Default watch directories
|
||||
~/.coder/
|
||||
~/.claude/todos/
|
||||
|
||||
# Default API port
|
||||
3000
|
||||
</code></pre>
|
||||
<p><strong>No configuration needed! Skip to Verification.</strong></p>
|
||||
<h3 id="option-2-custom-configuration"><a class="header" href="#option-2-custom-configuration">Option 2: Custom Configuration</a></h3>
|
||||
<p>Create <code>~/.config/vapora-tracking.toml</code>:</p>
|
||||
<pre><code class="language-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"
|
||||
</code></pre>
|
||||
<h3 id="option-3-environment-variables"><a class="header" href="#option-3-environment-variables">Option 3: Environment Variables</a></h3>
|
||||
<pre><code class="language-bash"># 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
|
||||
</code></pre>
|
||||
<hr />
|
||||
<h2 id="verification"><a class="header" href="#verification">Verification</a></h2>
|
||||
<h3 id="test-1-build-success"><a class="header" href="#test-1-build-success">Test 1: Build Success</a></h3>
|
||||
<pre><code class="language-bash"># 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
|
||||
</code></pre>
|
||||
<h3 id="test-2-tests-pass"><a class="header" href="#test-2-tests-pass">Test 2: Tests Pass</a></h3>
|
||||
<pre><code class="language-bash"># Run all unit tests
|
||||
cargo test -p vapora-tracking --lib
|
||||
|
||||
# Expected output:
|
||||
# running 20 tests
|
||||
# ...
|
||||
# test result: ok. 20 passed; 0 failed
|
||||
</code></pre>
|
||||
<p><strong>If not 20 tests:</strong></p>
|
||||
<pre><code class="language-bash"># Check what tests exist
|
||||
cargo test -p vapora-tracking --lib -- --list
|
||||
|
||||
# Run with output for debugging
|
||||
cargo test -p vapora-tracking --lib -- --nocapture
|
||||
</code></pre>
|
||||
<h3 id="test-3-code-quality"><a class="header" href="#test-3-code-quality">Test 3: Code Quality</a></h3>
|
||||
<pre><code class="language-bash"># Run clippy checks
|
||||
cargo clippy -p vapora-tracking --lib -- -W clippy::all
|
||||
|
||||
# Should show minimal warnings (profile warning is expected)
|
||||
</code></pre>
|
||||
<h3 id="test-4-cli-commands"><a class="header" href="#test-4-cli-commands">Test 4: CLI Commands</a></h3>
|
||||
<pre><code class="language-bash"># 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
|
||||
</code></pre>
|
||||
<h3 id="test-5-api-health"><a class="header" href="#test-5-api-health">Test 5: API Health</a></h3>
|
||||
<pre><code class="language-bash"># 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..."}
|
||||
</code></pre>
|
||||
<h3 id="verification-checklist"><a class="header" href="#verification-checklist">Verification Checklist</a></h3>
|
||||
<pre><code class="language-bash"># 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!"
|
||||
</code></pre>
|
||||
<hr />
|
||||
<h2 id="first-use"><a class="header" href="#first-use">First Use</a></h2>
|
||||
<h3 id="your-first-change-log"><a class="header" href="#your-first-change-log">Your First Change Log</a></h3>
|
||||
<pre><code class="language-bash"># Log your first change
|
||||
/log-change "Set up Vapora tracking system" \
|
||||
--impact infrastructure \
|
||||
--files 1
|
||||
|
||||
# Expected response: Change logged successfully
|
||||
</code></pre>
|
||||
<h3 id="your-first-todo"><a class="header" href="#your-first-todo">Your First TODO</a></h3>
|
||||
<pre><code class="language-bash"># Create your first TODO
|
||||
/add-todo "Review tracking system documentation" \
|
||||
--priority M \
|
||||
--estimate S \
|
||||
--due 2025-11-12
|
||||
|
||||
# Expected response: TODO created successfully
|
||||
</code></pre>
|
||||
<h3 id="your-first-status-check"><a class="header" href="#your-first-status-check">Your First Status Check</a></h3>
|
||||
<pre><code class="language-bash"># Check current status
|
||||
/track-status --limit 5
|
||||
|
||||
# Expected output shows your 1 change and 1 TODO
|
||||
</code></pre>
|
||||
<h3 id="your-first-export"><a class="header" href="#your-first-export">Your First Export</a></h3>
|
||||
<pre><code class="language-bash"># 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
|
||||
</code></pre>
|
||||
<hr />
|
||||
<h2 id="troubleshooting"><a class="header" href="#troubleshooting">Troubleshooting</a></h2>
|
||||
<h3 id="build-issues"><a class="header" href="#build-issues">Build Issues</a></h3>
|
||||
<h4 id="issue-errore0433-failed-to-resolve"><a class="header" href="#issue-errore0433-failed-to-resolve">Issue: "error[E0433]: failed to resolve"</a></h4>
|
||||
<p><strong>Solution:</strong></p>
|
||||
<pre><code class="language-bash"># Update Rust
|
||||
rustup update
|
||||
|
||||
# Clean and rebuild
|
||||
cargo clean -p vapora-tracking
|
||||
cargo build -p vapora-tracking
|
||||
</code></pre>
|
||||
<h4 id="issue-could-not-compile--due-to-x-previous-errors"><a class="header" href="#issue-could-not-compile--due-to-x-previous-errors">Issue: "could not compile ... due to X previous errors"</a></h4>
|
||||
<p><strong>Solution:</strong></p>
|
||||
<pre><code class="language-bash"># Check Rust version
|
||||
rustc --version # Must be 1.70+
|
||||
|
||||
# Update if needed
|
||||
rustup install stable
|
||||
|
||||
# Verify dependencies
|
||||
cargo tree -p vapora-tracking
|
||||
</code></pre>
|
||||
<h3 id="database-issues"><a class="header" href="#database-issues">Database Issues</a></h3>
|
||||
<h4 id="issue-database-file-not-found"><a class="header" href="#issue-database-file-not-found">Issue: "Database file not found"</a></h4>
|
||||
<p><strong>Solution:</strong></p>
|
||||
<pre><code class="language-bash"># Create database directory
|
||||
mkdir -p ~/.tracking
|
||||
|
||||
# Start service to initialize
|
||||
./scripts/start-tracking-service.nu
|
||||
|
||||
# Check database was created
|
||||
ls -la ~/.tracking/
|
||||
</code></pre>
|
||||
<h4 id="issue-failed-to-initialize-database"><a class="header" href="#issue-failed-to-initialize-database">Issue: "Failed to initialize database"</a></h4>
|
||||
<p><strong>Solution:</strong></p>
|
||||
<pre><code class="language-bash"># Reset database
|
||||
rm ~/.tracking/database.sqlite
|
||||
|
||||
# Service will recreate on next start
|
||||
./scripts/start-tracking-service.nu
|
||||
</code></pre>
|
||||
<h3 id="cli-issues"><a class="header" href="#cli-issues">CLI Issues</a></h3>
|
||||
<h4 id="issue-log-change-not-found-in-claude-code"><a class="header" href="#issue-log-change-not-found-in-claude-code">Issue: "/log-change not found" in Claude Code</a></h4>
|
||||
<p><strong>Solution:</strong></p>
|
||||
<pre><code class="language-bash"># 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
|
||||
</code></pre>
|
||||
<h4 id="issue-command-not-recognized"><a class="header" href="#issue-command-not-recognized">Issue: "Command not recognized"</a></h4>
|
||||
<p><strong>Solution:</strong></p>
|
||||
<pre><code class="language-bash"># Check command format
|
||||
/log-change --help
|
||||
|
||||
# Should show usage information
|
||||
# If not, commands aren't properly installed
|
||||
</code></pre>
|
||||
<h3 id="api-issues"><a class="header" href="#api-issues">API Issues</a></h3>
|
||||
<h4 id="issue-connection-refused-when-calling-api"><a class="header" href="#issue-connection-refused-when-calling-api">Issue: "Connection refused" when calling API</a></h4>
|
||||
<p><strong>Solution:</strong></p>
|
||||
<pre><code class="language-bash"># 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
|
||||
</code></pre>
|
||||
<h4 id="issue-port-3000-already-in-use"><a class="header" href="#issue-port-3000-already-in-use">Issue: "Port 3000 already in use"</a></h4>
|
||||
<p><strong>Solution:</strong></p>
|
||||
<pre><code class="language-bash"># Use different port
|
||||
./scripts/start-tracking-service.nu --port 3001
|
||||
|
||||
# Or kill existing service
|
||||
lsof -i :3000
|
||||
kill -9 <PID>
|
||||
</code></pre>
|
||||
<h3 id="performance-issues"><a class="header" href="#performance-issues">Performance Issues</a></h3>
|
||||
<h4 id="issue-build-is-very-slow"><a class="header" href="#issue-build-is-very-slow">Issue: Build is very slow</a></h4>
|
||||
<p><strong>Solution:</strong></p>
|
||||
<pre><code class="language-bash"># 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
|
||||
</code></pre>
|
||||
<h4 id="issue-high-memory-usage"><a class="header" href="#issue-high-memory-usage">Issue: High memory usage</a></h4>
|
||||
<p><strong>Solution:</strong></p>
|
||||
<pre><code class="language-bash"># Limit parallel jobs during build
|
||||
cargo build -p vapora-tracking -j 2
|
||||
|
||||
# Or reduce connection pool
|
||||
# Edit storage.rs: max_connections = 2
|
||||
</code></pre>
|
||||
<hr />
|
||||
<h2 id="quick-troubleshooting-reference"><a class="header" href="#quick-troubleshooting-reference">Quick Troubleshooting Reference</a></h2>
|
||||
<div class="table-wrapper"><table><thead><tr><th>Problem</th><th>Quick Fix</th></tr></thead><tbody>
|
||||
<tr><td>Build fails</td><td><code>cargo clean && cargo build</code></td></tr>
|
||||
<tr><td>Tests fail</td><td><code>rustup update</code> then rebuild</td></tr>
|
||||
<tr><td>Commands missing</td><td><code>cp ~/.claude/commands/*</code></td></tr>
|
||||
<tr><td>API won't start</td><td><code>./scripts/start-tracking-service.nu --verbose</code></td></tr>
|
||||
<tr><td>Database errors</td><td><code>rm ~/.tracking/database.sqlite</code></td></tr>
|
||||
<tr><td>Port in use</td><td><code>./scripts/start-tracking-service.nu --port 3001</code></td></tr>
|
||||
<tr><td>Slow build</td><td><code>export CARGO_INCREMENTAL=1</code></td></tr>
|
||||
</tbody></table>
|
||||
</div>
|
||||
<hr />
|
||||
<h2 id="system-validation-script"><a class="header" href="#system-validation-script">System Validation Script</a></h2>
|
||||
<p>Save this as <code>validate-tracking.sh</code>:</p>
|
||||
<pre><code class="language-bash">#!/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"
|
||||
</code></pre>
|
||||
<p>Run it:</p>
|
||||
<pre><code class="language-bash">chmod +x validate-tracking.sh
|
||||
./validate-tracking.sh
|
||||
</code></pre>
|
||||
<hr />
|
||||
<h2 id="whats-next-after-setup"><a class="header" href="#whats-next-after-setup">What's Next After Setup?</a></h2>
|
||||
<h3 id="immediate-today"><a class="header" href="#immediate-today">Immediate (Today)</a></h3>
|
||||
<ul>
|
||||
<li><input disabled="" type="checkbox"/>
|
||||
Complete all verification tests</li>
|
||||
<li><input disabled="" type="checkbox"/>
|
||||
Create your first change log</li>
|
||||
<li><input disabled="" type="checkbox"/>
|
||||
Create your first TODO</li>
|
||||
<li><input disabled="" type="checkbox"/>
|
||||
Run your first status check</li>
|
||||
</ul>
|
||||
<h3 id="short-term-this-week"><a class="header" href="#short-term-this-week">Short Term (This Week)</a></h3>
|
||||
<ul>
|
||||
<li><input disabled="" type="checkbox"/>
|
||||
Use <code>/log-change</code> for actual changes</li>
|
||||
<li><input disabled="" type="checkbox"/>
|
||||
Use <code>/add-todo</code> for tasks</li>
|
||||
<li><input disabled="" type="checkbox"/>
|
||||
Explore <code>/track-status</code> filters</li>
|
||||
<li><input disabled="" type="checkbox"/>
|
||||
Try exporting to different formats</li>
|
||||
</ul>
|
||||
<h3 id="medium-term-this-month"><a class="header" href="#medium-term-this-month">Medium Term (This Month)</a></h3>
|
||||
<ul>
|
||||
<li><input disabled="" type="checkbox"/>
|
||||
Set up automated syncing</li>
|
||||
<li><input disabled="" type="checkbox"/>
|
||||
Create custom dashboard queries</li>
|
||||
<li><input disabled="" type="checkbox"/>
|
||||
Integrate with your workflows</li>
|
||||
<li><input disabled="" type="checkbox"/>
|
||||
Set up reports</li>
|
||||
</ul>
|
||||
<hr />
|
||||
<h2 id="getting-help"><a class="header" href="#getting-help">Getting Help</a></h2>
|
||||
<p><strong>Issue not listed above?</strong></p>
|
||||
<ol>
|
||||
<li>Check the <a href="../crates/vapora-tracking/INTEGRATION.html#troubleshooting">TROUBLESHOOTING section</a> in INTEGRATION.md</li>
|
||||
<li>Review <a href="./TRACKING_SYSTEM_STATUS.html">TRACKING_SYSTEM_STATUS.md</a></li>
|
||||
<li>Check logs: <code>tail -f /tmp/vapora-tracking.log</code></li>
|
||||
<li>Read inline code documentation: <code>cargo doc -p vapora-tracking --open</code></li>
|
||||
</ol>
|
||||
<hr />
|
||||
<h2 id="summary"><a class="header" href="#summary">Summary</a></h2>
|
||||
<p>You've successfully set up the Vapora tracking system!</p>
|
||||
<h3 id="what-you-now-have"><a class="header" href="#what-you-now-have">What you now have:</a></h3>
|
||||
<p>✅ <strong>Built:</strong> vapora-tracking crate compiled and tested
|
||||
✅ <strong>Verified:</strong> All 20 tests passing
|
||||
✅ <strong>Installed:</strong> CLI commands and skill
|
||||
✅ <strong>Running:</strong> Tracking service ready
|
||||
✅ <strong>Configured:</strong> Database and API ready</p>
|
||||
<h3 id="start-using-it"><a class="header" href="#start-using-it">Start using it:</a></h3>
|
||||
<pre><code class="language-bash">/log-change "Example change" --impact backend
|
||||
/add-todo "Example task" --priority H
|
||||
/track-status
|
||||
</code></pre>
|
||||
<p><strong>Happy tracking! 🚀</strong></p>
|
||||
|
||||
</main>
|
||||
|
||||
<nav class="nav-wrapper" aria-label="Page navigation">
|
||||
<!-- Mobile navigation buttons -->
|
||||
<a rel="prev" href="../../setup/deployment-quickstart.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
|
||||
<i class="fa fa-angle-left"></i>
|
||||
</a>
|
||||
|
||||
<a rel="next prefetch" href="../../setup/tracking-quickstart.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
|
||||
<i class="fa fa-angle-right"></i>
|
||||
</a>
|
||||
|
||||
<div style="clear: both"></div>
|
||||
</nav>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<nav class="nav-wide-wrapper" aria-label="Page navigation">
|
||||
<a rel="prev" href="../../setup/deployment-quickstart.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
|
||||
<i class="fa fa-angle-left"></i>
|
||||
</a>
|
||||
|
||||
<a rel="next prefetch" href="../../setup/tracking-quickstart.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
|
||||
<i class="fa fa-angle-right"></i>
|
||||
</a>
|
||||
</nav>
|
||||
|
||||
</div>
|
||||
|
||||
|
||||
|
||||
|
||||
<script>
|
||||
window.playground_copyable = true;
|
||||
</script>
|
||||
|
||||
|
||||
<script src="../elasticlunr.min.js"></script>
|
||||
<script src="../mark.min.js"></script>
|
||||
<script src="../searcher.js"></script>
|
||||
|
||||
<script src="../clipboard.min.js"></script>
|
||||
<script src="../highlight.js"></script>
|
||||
<script src="../book.js"></script>
|
||||
|
||||
<!-- Custom JS scripts -->
|
||||
|
||||
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@ -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
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user