​

Intervo.ai: Application Setup Guide

This guide will walk you through setting up and running the Intervo.ai application using Docker Compose in a local development environment.

​

📦 Prerequisites

Before you start, ensure the following software is installed:

​

Required Tools

• Docker & Docker Compose
  Install Docker Desktop (includes Docker Engine + Compose).
• Git
  Install Git for your operating system.
• FFmpeg
  Required for audio processing.

​

FFmpeg Installation

macOS (Homebrew)

brew install ffmpeg

Ubuntu/Debian

sudo apt update && sudo apt install ffmpeg

Windows

choco install ffmpeg
# or
scoop install ffmpeg

​

🖥️ Minimum System Requirements

• RAM: 4GB (8GB recommended)
• Disk Space: 10GB minimum (Docker images, volumes, source files)

​

🗂 Project Structure

intervo-react/
├── packages/
│   ├── intervo-frontend/
│   ├── intervo-backend/
│   │   └── rag_py/
│   │       ├── requirements.txt
│   │       └── api.py
│   └── intervo-widget/
├── package.json
└── docker-compose.yml

​

🚀 Setup Instructions

​

1. Clone the Repository

git clone https://github.com/intervo/intervo
cd intervo-react

​

2. Verify Directory Structure

Ensure the structure matches the layout above. Docker volumes and npm workspaces depend on this.

​

3. Start the Application

Foreground (with logs)

docker-compose -f docker-compose.yml up

Detached Mode

docker-compose -f docker-compose.yml up -d

​

4. First-Time Setup

On the first run, Docker will:

• Pull base images
• Install npm and pip dependencies
• Initialize MongoDB

Startup Order:

1. MongoDB
2. Backend (after MongoDB is ready)
3. Frontend and RAG API (in parallel)

​

🌐 Accessing Services

​

🛠 Development Workflow

​

Code Changes

• Frontend: Auto-reloads via Next.js
• Backend: Auto-restarts via nodemon
• RAG API: Restart container manually after changes

​

View Logs

# All logs
docker-compose -f docker-compose.yml logs

# Specific service
docker-compose -f docker-compose.yml logs backend

# Real-time logs
docker-compose -f docker-compose.yml logs -f

​

🧪 Managing the Application

​

Stop Services

docker-compose -f docker-compose.yml down

​

Clean Reset (Remove Volumes)

docker-compose -f docker-compose.yml down -v

​

Rebuild Services

docker-compose -f docker-compose.yml up --build

​

Restart Specific Service

docker-compose -f docker-compose.yml restart frontend

​

🛢️ Database Access

​

Connection Info

• Host: localhost:27017
• Username: admin
• Password: password123
• DB Name: intervo
• Auth Source: admin

​

MongoDB Compass

Use:

mongodb://admin:password123@localhost:27017/intervo?authSource=admin

​

Command Line

docker-compose -f docker-compose.yml exec mongodb mongosh -u admin -p password123 --authenticationDatabase admin

​

🧩 Troubleshooting

​

Common Issues

• Port Conflicts
  Check with: sudo lsof -i :3000

• Docker Stuck
  Restart Docker or run: docker system prune

• Corrupt Volumes
  Run: docker-compose -f docker-compose.yml down -v

• Build Failures
  Clean and rebuild:

  Copy

  docker-compose -f docker-compose.yml down -v
  docker-compose -f docker-compose.yml up --build
  

​

Debugging Services

# Container status
docker-compose -f docker-compose.yml ps

# Open shell in backend
docker-compose -f docker-compose.yml exec backend sh

​

💡 Development Tips

• Live Reload: Code changes reflect instantly due to mounted volumes

• Persistent MongoDB: Data is stored in Docker volume mongodb_data

• Clean Fix: If stuck, run:

  Copy

  docker-compose -f docker-compose.yml down -v && docker-compose -f docker-compose.yml up
  

​

🔑 Environment Variables

Defined in docker-compose.yml:

NODE_ENV=development
MONGO_URI=mongodb://admin:password123@mongodb:27017/intervo?authSource=admin
PYTHONPATH=/app/packages/intervo-backend

​

✅ Next Steps

• Visit the app at: http://localhost:3000
• Test API endpoints via Postman or browser at http://localhost:3001
• Check RAG API status at http://localhost:4003

​

🚀 Production Deployment

For production, create a dedicated and secure docker-compose.prod.yml and update environment variables and secrets accordingly.

Happy coding! 🎉