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

# 🛠️ Vapora Tracking System - Complete Setup Guide

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

---

## 📋 Table of Contents

1. [Prerequisites](#prerequisites)
2. [Installation](#installation)
3. [Configuration](#configuration)
4. [Verification](#verification)
5. [First Use](#first-use)
6. [Troubleshooting](#troubleshooting)

---

## Prerequisites

### System Requirements

| Requirement | Minimum | Recommended |
|------------|---------|-------------|
| OS | macOS 10.15+ | macOS 12+ |
| RAM | 2GB | 4GB+ |
| Disk | 1GB | 2GB+ |
| Internet | Required for install | Required |

### Software Requirements

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

### Installation Check

```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!"
```

---

## Installation

### Step 1: Install Rust (if needed)

```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
```

**Expected output:**
```
rustc 1.XX.X (XXXXXXXXXXXX YYYY-MM-DD)
cargo 1.XX.X (XXXXXXXXXXXX YYYY-MM-DD)
```

### Step 2: Clone or Navigate to Vapora

```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/
```

### Step 3: Build the Tracking System

```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]
```

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

### Step 4: Verify Build

```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
```

### Step 5: Install CLI Components

```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
```

---

## Configuration

### Option 1: Default Configuration (Recommended)

The system works out of the box with defaults:

```bash
# Default database location
~/.tracking/database.sqlite

# Default watch directories
~/.coder/
~/.claude/todos/

# Default API port
3000
```

**No configuration needed! Skip to Verification.**

### Option 2: Custom Configuration

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

```toml
[database]
# SQLite database path (use your home directory)
url = "sqlite://~/.tracking/database.sqlite"

# Max connections to database
max_connections = 5

# Connection timeout (seconds)
timeout = 5

[watcher]
# Directories to watch for changes (customize for your setup)
watch_dirs = [
    "~/.coder",
    "~/.claude/todos"
]

# Debounce time (milliseconds)
debounce_ms = 500

[api]
# API server port
port = 3000

# API host
host = "127.0.0.1"

[logging]
# Log level: trace, debug, info, warn, error
level = "info"

# Log file path
file = "/tmp/vapora-tracking.log"
```

### Option 3: Environment Variables

```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
```

---

## Verification

### Test 1: Build Success

```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
```

### Test 2: Tests Pass

```bash
# Run all unit tests
cargo test -p vapora-tracking --lib

# Expected output:
# running 20 tests
# ...
# test result: ok. 20 passed; 0 failed
```

**If not 20 tests:**
```bash
# Check what tests exist
cargo test -p vapora-tracking --lib -- --list

# Run with output for debugging
cargo test -p vapora-tracking --lib -- --nocapture
```

### Test 3: Code Quality

```bash
# Run clippy checks
cargo clippy -p vapora-tracking --lib -- -W clippy::all

# Should show minimal warnings (profile warning is expected)
```

### Test 4: CLI Commands

```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
```

### Test 5: API Health

```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..."}
```

### Verification Checklist

```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!"
```

---

## First Use

### Your First Change Log

```bash
# Log your first change
/log-change "Set up Vapora tracking system" \
  --impact infrastructure \
  --files 1

# Expected response: Change logged successfully
```

### Your First TODO

```bash
# Create your first TODO
/add-todo "Review tracking system documentation" \
  --priority M \
  --estimate S \
  --due 2025-11-12

# Expected response: TODO created successfully
```

### Your First Status Check

```bash
# Check current status
/track-status --limit 5

# Expected output shows your 1 change and 1 TODO
```

### Your First Export

```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
```

---

## Troubleshooting

### Build Issues

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

**Solution:**
```bash
# Update Rust
rustup update

# Clean and rebuild
cargo clean -p vapora-tracking
cargo build -p vapora-tracking
```

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

**Solution:**
```bash
# Check Rust version
rustc --version  # Must be 1.70+

# Update if needed
rustup install stable

# Verify dependencies
cargo tree -p vapora-tracking
```

### Database Issues

#### Issue: "Database file not found"

**Solution:**
```bash
# Create database directory
mkdir -p ~/.tracking

# Start service to initialize
./scripts/start-tracking-service.nu

# Check database was created
ls -la ~/.tracking/
```

#### Issue: "Failed to initialize database"

**Solution:**
```bash
# Reset database
rm ~/.tracking/database.sqlite

# Service will recreate on next start
./scripts/start-tracking-service.nu
```

### CLI Issues

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

**Solution:**
```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
```

#### Issue: "Command not recognized"

**Solution:**
```bash
# Check command format
/log-change --help

# Should show usage information
# If not, commands aren't properly installed
```

### API Issues

#### Issue: "Connection refused" when calling API

**Solution:**
```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
```

#### Issue: "Port 3000 already in use"

**Solution:**
```bash
# Use different port
./scripts/start-tracking-service.nu --port 3001

# Or kill existing service
lsof -i :3000
kill -9 <PID>
```

### Performance Issues

#### Issue: Build is very slow

**Solution:**
```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
```

#### Issue: High memory usage

**Solution:**
```bash
# Limit parallel jobs during build
cargo build -p vapora-tracking -j 2

# Or reduce connection pool
# Edit storage.rs: max_connections = 2
```

---

## Quick Troubleshooting Reference

| Problem | Quick Fix |
|---------|-----------|
| Build fails | `cargo clean && cargo build` |
| Tests fail | `rustup update` then rebuild |
| Commands missing | `cp ~/.claude/commands/*` |
| API won't start | `./scripts/start-tracking-service.nu --verbose` |
| Database errors | `rm ~/.tracking/database.sqlite` |
| Port in use | `./scripts/start-tracking-service.nu --port 3001` |
| Slow build | `export CARGO_INCREMENTAL=1` |

---

## System Validation Script

Save this as `validate-tracking.sh`:

```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"
```

Run it:
```bash
chmod +x validate-tracking.sh
./validate-tracking.sh
```

---

## What's Next After Setup

### Immediate (Today)
- [ ] Complete all verification tests
- [ ] Create your first change log
- [ ] Create your first TODO
- [ ] Run your first status check

### Short Term (This Week)
- [ ] Use `/log-change` for actual changes
- [ ] Use `/add-todo` for tasks
- [ ] Explore `/track-status` filters
- [ ] Try exporting to different formats

### Medium Term (This Month)
- [ ] Set up automated syncing
- [ ] Create custom dashboard queries
- [ ] Integrate with your workflows
- [ ] Set up reports

---

## Getting Help

**Issue not listed above?**

1. Check the [TROUBLESHOOTING section](../crates/vapora-tracking/INTEGRATION.md#troubleshooting) in INTEGRATION.md
2. Review [TRACKING_SYSTEM_STATUS.md](./TRACKING_SYSTEM_STATUS.md)
3. Check logs: `tail -f /tmp/vapora-tracking.log`
4. Read inline code documentation: `cargo doc -p vapora-tracking --open`

---

## Summary

You've successfully set up the Vapora tracking system!

### What you now have

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

### Start using it

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

**Happy tracking! 🚀**