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

🛠️ Vapora - Complete Setup Guide

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

📋 Table of Contents

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

Prerequisites & Environment

System Requirements

Software Requirements

Required:

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

Optional but Recommended:

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

Prerequisite Check Script

#!/bin/bash
echo "🔍 Checking Vapora prerequisites..."
echo "=================================="

# Check Rust
if ! command -v rustc &> /dev/null; then
    echo "❌ Rust not found. Install from https://rustup.rs"
    exit 1
fi
echo "✅ Rust $(rustc --version | awk '{print $2}')"

# Check Cargo
if ! command -v cargo &> /dev/null; then
    echo "❌ Cargo not found"
    exit 1
fi
echo "✅ Cargo $(cargo --version | awk '{print $2}')"

# Check Git
if ! command -v git &> /dev/null; then
    echo "❌ Git not found. Install from https://git-scm.com"
    exit 1
fi
echo "✅ Git $(git --version | awk '{print $3}')"

# Check NuShell (optional)
if command -v nu &> /dev/null; then
    echo "✅ NuShell $(nu --version)"
else
    echo "⚠️  NuShell not found (optional, needed for scripts)"
fi

echo "=================================="
echo "✅ All prerequisites satisfied!"

Save as check-prerequisites.sh and run:

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

Installation

Step 1: Prepare Your Environment

# Update Rust (if already installed)
rustup update stable
rustup component add rustfmt clippy

# Clone or verify Vapora repo
if [ ! -d vapora ]; then
    git clone https://github.com/vapora/vapora.git
fi

cd vapora

Step 2: Install NuShell (if needed)

# macOS with Homebrew
brew install nu

# Or from source (if on other OS)
# See https://www.nushell.sh/book/installation.html

Verify:

nu --version  # Should be 0.95+

Step 3: Install Frontend Tools (if building frontend)

# Install trunk for Leptos WASM building
cargo install trunk

# Install wasm-pack for WASM compilation
rustup target add wasm32-unknown-unknown

Step 4: Download Workspace Dependencies

# Download all dependencies (no compilation yet)
cargo fetch

# This may take 2-3 minutes depending on internet speed

Step 5: Verify Workspace Structure

# Verify all crates are present
ls -la crates/

# Expected output (8 crates):
# vapora-agents/
# vapora-backend/
# vapora-doc-lifecycle/
# vapora-frontend/
# vapora-llm-router/
# vapora-mcp-server/
# vapora-shared/
# vapora-tracking/

Configuration

Option 1: Default Configuration (Recommended)

The project works out of the box with sensible defaults:

# Default Settings
Backend:
  port: 3000
  host: 127.0.0.1
  env: development

Database:
  type: SQLite (local)
  path: ~/.vapora/data.db

Tracking:
  database: ~/.tracking/database.sqlite
  watch_dirs:
    - .coder/
    - ~/.claude/todos/
  debounce_ms: 500

LLM Router:
  default_providers:
    - claude3-opus
    - gpt-4
    - gemini-2-pro
  fallback_enabled: true

Frontend:
  port: 8080
  hot_reload: true

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

Option 2: Environment Variables

Create .env file in project root:

# Backend Configuration
VAPORA_PORT=3000
VAPORA_HOST=127.0.0.1
RUST_ENV=development
RUST_LOG=debug

# Database
VAPORA_DATABASE_URL=sqlite:///Users/Akasha/.vapora/data.db
DATABASE_MAX_CONNECTIONS=5

# Tracking System
TRACKING_DATABASE_URL=sqlite:///Users/Akasha/.tracking/database.sqlite
TRACKING_API_PORT=3000
TRACKING_WATCH_DIRS=/Users/Akasha/.coder,/Users/Akasha/.claude/todos
TRACKING_DEBOUNCE_MS=500

# LLM Configuration
LLM_DEFAULT_PROVIDER=claude-opus
LLM_FALLBACK_ENABLED=true
OPENAI_API_KEY=your_key_here
ANTHROPIC_API_KEY=your_key_here
GOOGLE_API_KEY=your_key_here

# Frontend
FRONTEND_PORT=8080
FRONTEND_HOT_RELOAD=true

# Logging
LOG_LEVEL=debug
LOG_FORMAT=json

Load with:

export $(cat .env | xargs)

Option 3: Configuration File

Create ~/.vapora/config.toml:

[server]
port = 3000
host = "127.0.0.1"
environment = "development"

[database]
url = "sqlite:///Users/Akasha/.vapora/data.db"
max_connections = 5
timeout_seconds = 5

[tracking]
database_url = "sqlite:///Users/Akasha/.tracking/database.sqlite"
api_port = 3000
watch_dirs = [
    "/Users/Akasha/.coder",
    "/Users/Akasha/.claude/todos"
]
debounce_ms = 500

[llm_router]
default_provider = "claude-opus"
fallback_enabled = true

[frontend]
port = 8080
hot_reload = true

[logging]
level = "debug"
format = "json"
file = "/tmp/vapora.log"

Building & Testing

Phase 1: Build All Crates

# Build all crates in workspace (dev mode)
cargo build

# Build time: 3-8 minutes (first time)
# Subsequent builds: 10-30 seconds

# For optimized release build (slower to build, faster runtime)
cargo build --release

# Build time: 5-15 minutes (first time)

Phase 2: Run Full Test Suite

# Run all tests
cargo test --lib

# Expected output:
# test result: ok. XXX passed; 0 failed; 0 ignored; 0 measured

# Run tests for specific crate
cargo test -p vapora-tracking --lib
cargo test -p vapora-backend --lib
cargo test -p vapora-agents --lib

# Run tests with output
cargo test --lib -- --nocapture --test-threads=1

# Run specific test
cargo test test_health_endpoint -- --exact

Phase 3: Code Quality Checks

# Format code
cargo fmt

# Check formatting without modifying
cargo fmt -- --check

# Lint with clippy
cargo clippy --all-targets --all-features -- -W clippy::all

# Run both format and clippy
cargo fmt && cargo clippy --all-targets --all-features -- -W clippy::all

Phase 4: Documentation

# Generate documentation for all crates
cargo doc --no-deps --open

# Generate for specific crate
cargo doc -p vapora-tracking --no-deps --open

# Check documentation coverage
cargo doc --document-private-items

Verification Checklist

#!/bin/bash
set -e

echo "🔍 Running Vapora verification..."
echo "=================================="

# Build
echo "1. Building workspace..."
cargo build 2>&1 | tail -3
echo "✅ Build successful"

# Tests
echo "2. Running tests..."
cargo test --lib 2>&1 | grep "test result"
echo "✅ Tests passed"

# Clippy
echo "3. Running clippy..."
cargo clippy --all-targets --all-features 2>&1 | grep -v "warning:" | tail -1
echo "✅ Code quality checks passed"

# Format
echo "4. Checking format..."
cargo fmt -- --check 2>&1 && echo "✅ Code is properly formatted" || echo "⚠️ Code needs formatting"

echo "=================================="
echo "✅ Verification complete!"

Development Setup

IDE Setup

VS Code (Recommended)

# Install recommended extensions
# 1. rust-analyzer (rust-lang.rust-analyzer)
# 2. CodeLLDB (vadimcn.vscode-lldb)
# 3. Even Better TOML (tamasfe.even-better-toml)
# 4. Leptos (Leptos)

# .vscode/settings.json
{
  "[rust]": {
    "editor.formatOnSave": true,
    "editor.defaultFormatter": "rust-lang.rust-analyzer"
  },
  "rust-analyzer.inlayHints.enable": true,
  "rust-analyzer.lens.enable": true
}

IntelliJ IDEA / CLion

# Install Rust plugin
# Settings → Plugins → Rust → Install

# Recommended settings:
# Rust → Clippy → Use Clippy instead of Cargo check
# Rust → Macro Expansion → Expand experimental attribute macros

Git Setup

# Clone pre-commit hooks (if available)
git clone https://github.com/vapora/hooks .git/hooks

# Or create basic hook:
cat > .git/hooks/pre-commit << 'EOF'
#!/bin/bash
cargo fmt --check && cargo clippy --all -- -W clippy::all
EOF

chmod +x .git/hooks/pre-commit

Development Workflow

# 1. Create feature branch
git checkout -b feat/my-feature

# 2. Make changes and build
cargo build

# 3. Run tests
cargo test --lib

# 4. Check code quality
cargo fmt
cargo clippy --all -- -W clippy::all

# 5. Commit and push
git add .
git commit -m "feat: implement my-feature"
git push origin feat/my-feature

# 6. Create pull request

First Run

Run Backend Server

Terminal 1: Backend

# Run backend
cargo run -p vapora-backend

# With debug logging
RUST_LOG=debug cargo run -p vapora-backend

# Expected output:
# 🚀 Vapora Backend Server
# Listening on http://127.0.0.1:3000
# Available endpoints:
#   GET    /api/v1/health
#   GET    /api/v1/tracking/summary
#   POST   /api/v1/agents/orchestrate

Run Frontend (Optional)

Terminal 2: Frontend

cd crates/vapora-frontend

# Install trunk (if not already)
cargo install trunk

# Run frontend with hot-reload
trunk serve

# Expected output:
# 🦕 Listening on http://127.0.0.1:8080

Test Endpoints

Terminal 3: Test

# Health check
curl http://localhost:3000/api/v1/health
# Response: {"status":"ok","service":"vapora-backend",...}

# Tracking summary
curl http://localhost:3000/api/v1/tracking/summary
# Response: {"total_entries":0,"changes":0,"todos":0}

# Create tracking entry
curl -X POST http://localhost:3000/api/v1/tracking/entries \
  -H "Content-Type: application/json" \
  -d '{"summary":"First entry","impact":"backend"}'

Using CLI Commands

# Start tracking service (if using local service)
./scripts/start-tracking-service.nu --verbose

# Log a change
/log-change "Completed setup" --impact infrastructure --files 1

# Create a TODO
/add-todo "Review tracking system" --priority H --estimate M

# Check status
/track-status --limit 10

# Export data
./scripts/export-tracking.nu json --output setup-report.json

Troubleshooting

Build Issues

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

Solution:

# Update Rust
rustup update stable

# Clean cache
cargo clean

# Rebuild
cargo build

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

Solution:

# Check Rust version (must be 1.75+)
rustc --version

# Update if needed
rustup install 1.75
rustup default 1.75

Error: "linker 'cc' not found"

Solution (macOS):

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

Test Issues

Tests fail with timeout

Solution:

# Run with single thread
cargo test --lib -- --test-threads=1

# Increase timeout
RUST_TEST_TIME_UNIT=60000 cargo test --lib

Tests panic with "thread 'main' panicked"

Solution:

# Run with backtrace
RUST_BACKTRACE=1 cargo test --lib -- --nocapture

# Check logs for actual error
RUST_LOG=trace cargo test --lib -- --nocapture

Database Issues

Error: "database file not found"

Solution:

# Create database directory
mkdir -p ~/.tracking
mkdir -p ~/.vapora

# Initialize databases
./scripts/start-tracking-service.nu

# Wait for init and stop with Ctrl+C

Error: "Failed to acquire database lock"

Solution:

# Ensure only one instance is running
lsof | grep database.sqlite

# Kill any lingering processes
pkill -f "vapora-backend"
pkill -f "tracking-service"

# Restart
cargo run -p vapora-backend

Port Already in Use

Error: "Address already in use"

Solution:

# Find process using port 3000
lsof -i :3000

# Kill process
kill -9 <PID>

# Or use different port
VAPORA_PORT=3001 cargo run -p vapora-backend

NuShell Script Issues

Error: "command not found: nu"

Solution:

# Install NuShell
brew install nu

# Or add to PATH
export PATH="/usr/local/bin:$PATH"

Scripts not executable

Solution:

# Make scripts executable
chmod +x scripts/*.nu

# Run with nu explicitly
nu scripts/start-tracking-service.nu

Frontend Issues

Error: "trunk: command not found"

Solution:

# Install trunk
cargo install trunk

# Install WASM target
rustup target add wasm32-unknown-unknown

Frontend won't load styles

Solution:

# Clear build cache
rm -rf crates/vapora-frontend/target
rm -rf crates/vapora-frontend/dist

# Rebuild
cd crates/vapora-frontend && trunk serve

Quick Troubleshooting Reference

Verification Steps

Post-Installation Verification

#!/bin/bash

echo "🔍 Post-installation verification..."
echo "===================================="

# 1. Check Rust
echo "1. Checking Rust..."
rustc --version | grep -q "1\.[0-9]\+\.[0-9]\+" && echo "✅ Rust OK" || echo "❌ Rust issue"

# 2. Check build
echo "2. Building..."
cargo build 2>&1 | grep -q "Finished" && echo "✅ Build OK" || echo "❌ Build failed"

# 3. Check tests
echo "3. Testing..."
cargo test --lib 2>&1 | grep -q "test result: ok" && echo "✅ Tests OK" || echo "❌ Tests failed"

# 4. Check code quality
echo "4. Code quality..."
cargo clippy --all 2>&1 | grep -v "warning:" | tail -1 | grep -q "error" && echo "❌ Clippy issues" || echo "✅ Code quality OK"

# 5. Check structure
echo "5. Project structure..."
[ -f "Cargo.toml" ] && [ -d "crates" ] && echo "✅ Structure OK" || echo "❌ Structure issue"

echo "===================================="
echo "✅ Verification complete!"

What's Next?

Immediate Next Steps

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

Learning Resources

• API Documentation: cargo doc --open
• Crate READMEs: crates/*/README.md
• Tracking System: QUICKSTART_TRACKING.md
• Architecture: .coder/

Development Tips

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

Getting Help

Issues not listed above?

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

✅ Setup Completion Checklist

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

All checked? ✅ Vapora is ready for development!

For quick 15-minute setup: See QUICKSTART.md

For tracking system setup: See SETUP_TRACKING.md