CurrenciCombo/docs/QUICK_START.md

Quick Start Guide

Get up and running with CurrenciCombo in 5 minutes!

Prerequisites

• WSL 2 with Ubuntu installed
• Node.js 18+ (will be checked during setup)
• Docker (optional, for local database)

One-Command Setup

# Navigate to project
cd /mnt/c/Users/intlc/defi_oracle_projects/CurrenciCombo

# Run complete setup
./scripts/setup-complete.sh

This will:

• ✅ Check prerequisites
• ✅ Install missing tools
• ✅ Create environment files
• ✅ Install all dependencies
• ✅ Setup database (if Docker available)
• ✅ Run migrations

Manual Setup (Step by Step)

1. Install Prerequisites

# Update package list
sudo apt update && sudo apt upgrade -y

# Install Node.js 18+
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt install -y nodejs

# Install required tools
sudo apt install -y jq bc netcat-openbsd postgresql-client

# Install Docker (optional, for database)
# Follow: https://docs.docker.com/engine/install/ubuntu/

2. Setup Environment

# Create webapp environment
cat > webapp/.env.local << EOF
NEXT_PUBLIC_ORCH_URL=http://localhost:8080
NEXTAUTH_SECRET=dev-secret-change-in-production-min-32-chars-$(date +%s)
EOF

# Create orchestrator environment
cat > orchestrator/.env << EOF
NODE_ENV=development
PORT=8080
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/comboflow
SESSION_SECRET=dev-secret-change-in-production-min-32-chars-$(date +%s)
RUN_MIGRATIONS=true
LOG_LEVEL=info
EOF

3. Install Dependencies

# Install all dependencies
cd webapp && npm install && cd ..
cd orchestrator && npm install && cd ..
cd contracts && npm install && cd ..

4. Setup Database

# Setup PostgreSQL with Docker
./scripts/setup-database.sh

# Run migrations
./scripts/run-migrations.sh

5. Start Services

# Start all services
./scripts/start-all.sh

# Or start individually:
# Terminal 1: cd webapp && npm run dev
# Terminal 2: cd orchestrator && npm run dev

6. Verify Setup

# Check service status
./scripts/check-status.sh

# Validate setup
./scripts/validate-setup.sh

# Test endpoints
./scripts/test-curl.sh

Access Services

Once services are running:

• Webapp: http://localhost:3000
• Orchestrator API: http://localhost:8080
• Health Check: http://localhost:8080/health
• Metrics: http://localhost:8080/metrics

Troubleshooting

Services Not Starting

# Check what's using the ports
lsof -ti:3000  # Webapp
lsof -ti:8080  # Orchestrator

# Kill processes if needed
kill $(lsof -ti:3000)
kill $(lsof -ti:8080)

Database Connection Issues

# Check database is running
docker ps | grep combo-postgres

# Test connection
./scripts/test-database.sh

# Check environment variables
cat orchestrator/.env | grep DATABASE_URL

Frontend Not Loading

# Fix frontend issues
./scripts/fix-frontend.sh

# Check Next.js compilation
cd webapp && npm run build

Validation Errors

# Run full validation
./scripts/validate-setup.sh

# Fix specific issues based on output

Next Steps

1. Explore the API: Use ./scripts/test-curl.sh to test endpoints
2. Create a Plan: Use the webapp UI at http://localhost:3000
3. Test End-to-End: Run ./scripts/test-e2e-flow.sh
4. Read Documentation: Check docs/ folder for detailed guides

Development Workflow

Daily Development

# 1. Start services
./scripts/start-all.sh

# 2. Check status
./scripts/check-status.sh

# 3. Make changes...

# 4. Test changes
./scripts/test-curl.sh

Before Committing

# 1. Validate setup
./scripts/validate-setup.sh

# 2. Run tests
cd webapp && npm run test
cd ../orchestrator && npm run test
cd ../contracts && npm run test

# 3. Check linting
cd webapp && npm run lint
cd ../orchestrator && npm run lint

Common Commands

Command	Purpose
./scripts/setup-complete.sh	Complete setup
./scripts/start-all.sh	Start all services
./scripts/check-status.sh	Check service status
./scripts/validate-setup.sh	Validate setup
./scripts/test-curl.sh	Test API endpoints
./scripts/test-e2e-flow.sh	Test end-to-end flow
./scripts/fix-frontend.sh	Fix frontend issues

Getting Help

• Documentation: See docs/ folder
• Troubleshooting: See docs/TROUBLESHOOTING.md
• WSL Setup: See docs/WSL_SETUP.md
• Database Options: See docs/DATABASE_OPTIONS.md

---

Last Updated: 2025-01-15