Skip to content

setup.md

Latest commit

 

History

History
390 lines (274 loc) · 6.64 KB

setup.md

File metadata and controls

390 lines (274 loc) · 6.64 KB
Raw

Development Setup

This guide will help you set up a local development environment for ISC-CodeConnect.

Prerequisites

System Requirements

  • Python 3.12+ with pip
  • Node.js 18+ with npm/yarn
  • Git for version control
  • Docker (optional, for containerized development)
  • 4GB RAM minimum (8GB recommended for optimal performance)

Required Accounts & Services

  • IBM Cloud Account with WatsonX.ai access
  • GitHub Enterprise access for repository
  • Milvus Cloud account (or local Milvus instance)
  • MongoDB Atlas account (or local MongoDB instance)

Environment Setup

1. Clone Repository

git clone https://github.ibm.com/BPManagementTools/isc-code-connect-agent.git
cd isc-code-connect-agent

2. Backend Setup

Create Virtual Environment

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Install Dependencies

pip install -r requirements.txt

Development Dependencies (Optional)

pip install -r requirements-dev.txt

3. Environment Configuration

Copy Environment Template

cp .env.example .env

Configure Environment Variables

Edit .env with your specific configurations:

Environment variables are shared in 1Password vault.

4. Database Setup

Start Local Services (Docker)

# Start Milvus (if using Docker)
docker run -d --name milvus-standalone \
  -p 19530:19530 \
  -v $(pwd)/volumes/milvus:/var/lib/milvus \
  milvusdb/milvus:v2.3.0 \
  milvus run standalone

# Start MongoDB (if using Docker)
docker run -d --name mongodb \
  -p 27017:27017 \
  -v $(pwd)/volumes/mongodb:/data/db \
  mongo:6.0

Initialize Database Schema

python -m src.utils.init_database

Load Sample Data (Optional)

python -m src.utils.load_sample_data

5. Frontend Setup

Navigate to Frontend Directory

cd frontend

Install Dependencies

npm install
# or
yarn install

Configure Frontend Environment

cp .env.local.example .env.local

Edit .env.local:

NEXT_PUBLIC_API_URL=http://localhost:8000/api/v1
NEXT_PUBLIC_WS_URL=ws://localhost:8000/ws
NEXT_PUBLIC_APP_NAME=ISC-CodeConnect
NEXT_PUBLIC_ENVIRONMENT=development

Development Workflow

1. Start Backend Services

Development Server

# From project root
source venv/bin/activate
python -m uvicorn api.main:app --reload --host 0.0.0.0 --port 8000

Alternative: Use Development Script

chmod +x dev.sh
./dev.sh

2. Start Frontend Development Server

# From frontend directory
npm run dev
# or
yarn dev

3. Access Applications

Development Tools

Code Quality

Linting and Formatting

# Python (Backend)
black src/ tests/
flake8 src/ tests/
mypy src/

# TypeScript/JavaScript (Frontend)
cd frontend
npm run lint
npm run format

Pre-commit Hooks

pip install pre-commit
pre-commit install

Testing

Backend Tests

# Unit tests
python -m pytest tests/unit/ -v

# Integration tests
python -m pytest tests/integration/ -v

# Agent tests
python -m pytest tests/agents/ -v

# Coverage report
python -m pytest --cov=src tests/

Frontend Tests

cd frontend
npm test
npm run test:coverage

Debugging

Backend Debugging

# Enable debug mode
export DEBUG=true

# Run with debugger
python -m pdb -m uvicorn api.main:app --reload

Agent Debugging

# Enable agent logging
export ENABLE_AGENT_LOGGING=true

# View agent logs
tail -f logs/agents.log

Database Debugging

# Test Milvus connection
python -m src.utils.test_milvus

# Test MongoDB connection
python -m src.utils.test_mongodb

# View collection stats
python -m src.utils.collection_stats

IDE Configuration

VS Code Settings

Create .vscode/settings.json:

{
  "python.defaultInterpreterPath": "./venv/bin/python",
  "python.linting.enabled": true,
  "python.linting.pylintEnabled": false,
  "python.linting.flake8Enabled": true,
  "python.formatting.provider": "black",
  "typescript.preferences.importModuleSpecifier": "relative",
  "eslint.workingDirectories": ["frontend"]
}

VS Code Extensions

Recommended extensions:

  • Python
  • Pylance
  • Black Formatter
  • ESLint
  • Prettier
  • Thunder Client (for API testing)

Docker Development (Optional)

Full Stack with Docker Compose

# Build and start all services
docker-compose -f docker-compose.dev.yml up --build

# Start specific service
docker-compose -f docker-compose.dev.yml up backend

# View logs
docker-compose -f docker-compose.dev.yml logs -f backend

Development Container

# Build development image
docker build -f Dockerfile.dev -t isc-codeconnect:dev .

# Run development container
docker run -it --rm \
  -v $(pwd):/app \
  -p 8000:8000 \
  isc-codeconnect:dev

Troubleshooting

Common Issues

Python Dependencies

# Clear pip cache
pip cache purge

# Reinstall requirements
pip install -r requirements.txt --force-reinstall

Node Dependencies

# Clear npm cache
npm cache clean --force

# Remove and reinstall
rm -rf node_modules package-lock.json
npm install

Database Connection Issues

# Check service status
docker ps

# Restart services
docker-compose restart milvus mongodb

# Check logs
docker logs milvus-standalone
docker logs mongodb

Environment Issues

# Verify environment variables
python -c "import os; print(os.getenv('WATSONX_API_KEY'))"

# Check .env file
cat .env | grep -E '^[A-Z_]+='

Performance Optimization

Memory Usage

# Monitor memory usage
python -m memory_profiler src/main.py

# Agent memory profiling
python -m src.utils.profile_agents

Database Performance

# Milvus performance check
python -m src.utils.benchmark_milvus

# MongoDB performance check
python -m src.utils.benchmark_mongodb

Next Steps

  1. Read Architecture Documentation: Understand the system design
  2. Explore Agent Code: Review existing agent implementations
  3. Run Tests: Ensure everything works correctly
  4. Create Feature Branch: Start developing your feature
  5. Follow Code Standards: Maintain code quality

Getting Help

  • Documentation: Check other sections for specific topics
  • Issues: Create GitHub issues for bugs or questions
  • Discussions: Join team discussions for architecture questions
  • Code Review: Request reviews for development guidance