Vapora/provisioning/quickstart.md

VAPORA Provisioning Quick Start

Get VAPORA running in 5 minutes.

Choose Your Path

🚀 Fastest: Copy & Deploy (2 minutes)

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)

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)

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

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

# 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

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

# Check status
docker compose logs -f vapora-backend

Kubernetes

# 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

# 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

[backend]
port = 9001

Enable Ollama (Local LLMs)

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

Set Budget Limits

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

Enable Observability

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

Troubleshooting

"Port already in use"

# Change port in config
[backend]
port = 9001  # Instead of 8001

"Database connection failed"

# Check SurrealDB is running
curl -i http://localhost:8000

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

"Configuration not loading"

# 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:

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)

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

Multiuser (Team)

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)

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.