168 lines
3.2 KiB
Markdown
168 lines
3.2 KiB
Markdown
# Quick Start Guide
|
|
|
|
Get the hybrid Node.js + Python architecture running in 5 minutes.
|
|
|
|
## Prerequisites
|
|
|
|
- Node.js 18+ installed
|
|
- Python 3.11+ installed
|
|
- PostgreSQL database running
|
|
- Database credentials configured
|
|
|
|
## Step 1: Install Dependencies
|
|
|
|
### Python Service
|
|
```bash
|
|
cd backend/python_service
|
|
python -m venv venv
|
|
|
|
# Activate virtual environment
|
|
# Windows:
|
|
venv\Scripts\activate
|
|
# macOS/Linux:
|
|
source venv/bin/activate
|
|
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
### Node.js Backend
|
|
```bash
|
|
cd backend
|
|
npm install
|
|
```
|
|
|
|
## Step 2: Configure Environment
|
|
|
|
### Python Service
|
|
Create `backend/python_service/.env`:
|
|
```env
|
|
USE_LOCAL_DB=true
|
|
LOCAL_DB_HOST=localhost
|
|
LOCAL_DB_PORT=5432
|
|
LOCAL_DB_USER=postgres
|
|
LOCAL_DB_PASSWORD=your_password
|
|
LOCAL_DB_NAME=institutional_trader
|
|
```
|
|
|
|
### Node.js Backend
|
|
Add to `backend/.env`:
|
|
```env
|
|
PYTHON_SERVICE_URL=http://localhost:8010
|
|
USE_PYTHON_SERVICE=true
|
|
|
|
# Your existing database config...
|
|
```
|
|
|
|
## Step 3: Start Services
|
|
|
|
### Terminal 1: Python Service
|
|
```bash
|
|
cd backend/python_service
|
|
# Activate virtual environment:
|
|
# Git Bash on Windows:
|
|
source venv/Scripts/activate
|
|
# PowerShell/CMD on Windows:
|
|
venv\Scripts\activate
|
|
# Linux/macOS:
|
|
source venv/bin/activate
|
|
|
|
uvicorn main:app --reload --port 8010
|
|
```
|
|
|
|
You should see:
|
|
```
|
|
INFO: Uvicorn running on http://0.0.0.0:8010
|
|
INFO: Application startup complete.
|
|
```
|
|
|
|
### Terminal 2: Node.js Backend
|
|
```bash
|
|
cd backend
|
|
npm run dev
|
|
```
|
|
|
|
You should see:
|
|
```
|
|
🚀 Server running on http://localhost:3010
|
|
🐍 Starting Python service health checks...
|
|
✅ Python service is healthy
|
|
```
|
|
|
|
## Step 4: Test Integration
|
|
|
|
### Test Health Endpoint
|
|
```bash
|
|
curl http://localhost:3010/health
|
|
```
|
|
|
|
Expected response:
|
|
```json
|
|
{
|
|
"status": "ok",
|
|
"database": { "status": "connected" },
|
|
"pythonService": { "available": true, "status": "healthy" }
|
|
}
|
|
```
|
|
|
|
### Test Options Flow
|
|
```bash
|
|
curl "http://localhost:3010/api/options/flow?startDate=2024-01-01&endDate=2024-01-02"
|
|
```
|
|
|
|
Check Node.js logs - you should see:
|
|
```
|
|
✅ Using Python service: 150 rows
|
|
```
|
|
|
|
## Step 5: Verify Fallback
|
|
|
|
Stop the Python service (Ctrl+C in Terminal 1), then test again:
|
|
|
|
```bash
|
|
curl "http://localhost:3010/api/options/flow?startDate=2024-01-01&endDate=2024-01-02"
|
|
```
|
|
|
|
Check Node.js logs - you should see:
|
|
```
|
|
⚠️ Python service unavailable, falling back to SQL
|
|
📊 Using SQL query (fallback or Python disabled)
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Python Service Won't Start
|
|
- Check database credentials in `.env`
|
|
- Verify PostgreSQL is running
|
|
- Check port 8010 is available
|
|
- Review Python service logs
|
|
|
|
### Node.js Can't Connect
|
|
- Verify `PYTHON_SERVICE_URL` in `.env`
|
|
- Check Python service is running
|
|
- Test: `curl http://localhost:8010/health`
|
|
|
|
### No Data Returned
|
|
- Check database has data
|
|
- Verify date range has data
|
|
- Review database connection
|
|
- Check service logs
|
|
|
|
## Next Steps
|
|
|
|
1. ✅ Services running
|
|
2. Run validation: `cd backend/python_service && python scripts/validate_against_sql.py`
|
|
3. Review `INTEGRATION_COMPLETE.md` for full documentation
|
|
4. Check `TESTING.md` for testing guide
|
|
|
|
## Production Deployment
|
|
|
|
For production:
|
|
- Use process managers (PM2, systemd)
|
|
- Set up proper logging
|
|
- Configure monitoring
|
|
- Use environment-specific configs
|
|
- Set up health check alerts
|
|
|
|
See `INTEGRATION_COMPLETE.md` for deployment details.
|
|
|