Vapora/provisioning/quickstart.md

# VAPORA Provisioning Quick Start

Get VAPORA running in 5 minutes.

## Choose Your Path

### 🚀 Fastest: Copy & Deploy (2 minutes)

```bash
cd provisioning

# Pick your mode
cp config/examples/vapora.solo.example.toml config/runtime/vapora.toml

# Done! Deploy with docker-compose
docker compose up -d
```

### 📋 Customizable: Interactive Wizard (3 minutes)

```bash
cd provisioning

# Answer 50+ questions
typedialog --form .typedialog/vapora/forms/vapora-main-form.toml \
  --output config/runtime/vapora.toml

# Deploy
docker compose up -d
```

### 🔧 Advanced: Nickel Composition (5 minutes)

```bash
cd provisioning

# Create custom config
cat > config/runtime/custom.ncl << 'EOF'
let defaults = import "../../schemas/vapora/main.ncl" in
let mode = import "../../schemas/platform/defaults/deployment/multiuser.ncl" in

std.record.merge defaults {
  backend.port = 9001,
  llm_router.providers.ollama_enabled = true,
}
EOF

# Export to JSON
nickel export config/runtime/custom.ncl > config/runtime/vapora.json

# Deploy with config
docker compose up -d
```

## Configuration Files

Your configuration goes in **`config/runtime/vapora.toml`** after generation or copying.

| Mode | Description | Best For |
|------|-------------|----------|
| **solo** | Local dev | Development, testing |
| **multiuser** | Shared backend | Team of 5-20 developers |
| **enterprise** | HA production | Organizations, production |

## What Gets Generated

```plaintext
provisioning/
├── config/
│   └── runtime/
│       └── vapora.toml          ← Your configuration goes here
├── schemas/
│   └── vapora/*.ncl             ← Configuration structure (read-only)
└── .typedialog/
    └── vapora/forms/*.toml      ← Interactive forms (read-only)
```

## Verify Configuration

```bash
# TOML syntax check
toml-cli validate config/runtime/vapora.toml

# Nickel type check
nickel typecheck config/examples/vapora.solo.example.ncl

# JSON validation
jq . config/runtime/vapora.json
```

## Deploy

### Docker Compose

```bash
# Services read from config/runtime/vapora.toml
docker compose up -d

# Check status
docker compose logs -f vapora-backend
```

### Kubernetes

```bash
# Create config from file
kubectl create configmap vapora-config \
  --from-file=config/runtime/vapora.toml

# Deploy (Pod mounts ConfigMap)
kubectl apply -f kubernetes/manifests/
```

### Custom Script

```bash
# Source configuration
source <(grep '^\[' config/runtime/vapora.toml | tr -d '[]')

# Use in your deployment
export VAPORA_CONFIG=$(pwd)/config/runtime/vapora.toml
./deploy.sh
```

## Common Customizations

### Change Port

```toml
[backend]
port = 9001
```

### Enable Ollama (Local LLMs)

```toml
[providers]
ollama_enabled = true
ollama_url = "http://localhost:11434"
```

### Set Budget Limits

```toml
[llm_router.budget_enforcement.role_limits]
architect_cents = 1000000       # $10,000/month
developer_cents = 500000        # $5,000/month
```

### Enable Observability

```toml
[monitoring]
prometheus_enabled = true
log_level = "debug"
tracing_enabled = true
```

## Troubleshooting

### "Port already in use"
```bash
# Change port in config
[backend]
port = 9001  # Instead of 8001
```

### "Database connection failed"
```bash
# Check SurrealDB is running
curl -i http://localhost:8000

# Update config with correct URL
[database]
url = "ws://surrealdb.example.com:8000"
```

### "Configuration not loading"
```bash
# Ensure file exists
ls -l config/runtime/vapora.toml

# Check syntax
toml-cli validate config/runtime/vapora.toml

# Restart services
docker compose restart
```

## Environment Overrides

All config can be overridden via environment variables:

```bash
export VAPORA_BACKEND_PORT=9001
export VAPORA_BACKEND_WORKERS=8
export SURREAL_URL=ws://surrealdb:8000
export ANTHROPIC_API_KEY=sk-ant-...

docker compose up -d
```

## Next Steps

1. **Read Full Docs**: `README.md` (complete reference)
2. **Understand Modes**: `config/examples/README.md` (all deployment options)
3. **Learn Integration**: `integration.md` (deployment workflows)
4. **Check Examples**: `config/examples/vapora.*.example.toml` (reference configs)

## One-Command Deploy

### Solo (Development)

```bash
cd provisioning && \
cp config/examples/vapora.solo.example.toml config/runtime/vapora.toml && \
docker compose up -d
```

### Multiuser (Team)

```bash
cd provisioning && \
cp config/examples/vapora.multiuser.example.toml config/runtime/vapora.toml && \
# Edit config/runtime/vapora.toml with your URLs
docker compose up -d
```

### Enterprise (Production)

```bash
cd provisioning && \
cp config/examples/vapora.enterprise.example.toml config/runtime/vapora.toml && \
# Edit config/runtime/vapora.toml with your infrastructure details
docker compose up -d
```

---

**That's it!** Your VAPORA instance is running.

**Need help?** Check `README.md` for comprehensive documentation.