​
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

ServiceURL/Port
Frontendhttp://localhost:3000
Backend APIhttp://localhost:3001
RAG APIhttp://localhost:4003
MongoDB URImongodb://admin:password123@localhost:27017/intervo?authSource=admin

​
🛠 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:     
    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: 
    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

​
🚀 Production Deployment

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