> ## Documentation Index
> Fetch the complete documentation index at: https://docs.intervo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Setup & Installation Guide

> A complete guide to setting up and running the Intervo.ai open-source application using Docker for local development.

# 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](https://www.docker.com/products/docker-desktop) (includes Docker Engine + Compose).
* **Git**\
  [Install Git](https://git-scm.com/downloads) for your operating system.
* **FFmpeg**\
  Required for audio processing.

#### FFmpeg Installation

**macOS (Homebrew)**

```bash theme={null}
brew install ffmpeg
```

**Ubuntu/Debian**

```bash theme={null}
sudo apt update && sudo apt install ffmpeg
```

**Windows**

```bash theme={null}
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

```bash theme={null}
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)**

```bash theme={null}
docker-compose -f docker-compose.yml up
```

**Detached Mode**

```bash theme={null}
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

| Service     | URL/Port                                                               |
| ----------- | ---------------------------------------------------------------------- |
| Frontend    | [http://localhost:3000](http://localhost:3000)                         |
| Backend API | [http://localhost:3001](http://localhost:3001)                         |
| RAG API     | [http://localhost:4003](http://localhost:4003)                         |
| MongoDB URI | `mongodb://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

```bash theme={null}
# 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

```bash theme={null}
docker-compose -f docker-compose.yml down
```

### Clean Reset (Remove Volumes)

```bash theme={null}
docker-compose -f docker-compose.yml down -v
```

### Rebuild Services

```bash theme={null}
docker-compose -f docker-compose.yml up --build
```

### Restart Specific Service

```bash theme={null}
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

```bash theme={null}
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:

  ```bash theme={null}
  docker-compose -f docker-compose.yml down -v
  docker-compose -f docker-compose.yml up --build
  ```

### Debugging Services

```bash theme={null}
# 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:

  ```bash theme={null}
  docker-compose -f docker-compose.yml down -v && docker-compose -f docker-compose.yml up
  ```

***

## 🔑 Environment Variables

Defined in `docker-compose.yml`:

```env theme={null}
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](http://localhost:3000)
* Test API endpoints via Postman or browser at [http://localhost:3001](http://localhost:3001)
* Check RAG API status at [http://localhost:4003](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! 🎉