Rapida Voice AI Platform - Developer Guide

Welcome to Rapida! This guide will help you set up and run the complete Rapida Voice AI Platform on your machine. Whether you prefer Docker or manual setup, we’ve got you covered.

What is Rapida?

Rapida is an open-source, end-to-end voice orchestration platform for building, deploying, and managing voice agents at scale. It provides:

Voice Agents: Build intelligent voice bots with LLM integration
Real-time Audio Processing: Stream audio with low-latency processing
Orchestration: Manage complex voice workflows and interactions
Integration: Connect with 50+ LLM, STT, TTS, and telephony providers
Observable: Deep insights into calls, metrics, and performance

Architecture Overview

Rapida consists of several microservices working together:

web-api (9001) - Dashboard backend and core orchestration
assistant-api (9007) - Voice agent management and conversation handling
integration-api (9004) - Third-party service integrations
endpoint-api (9005) - Webhook and callback management
document-api (9010) - Knowledge base and RAG capabilities
ui (3000) - React dashboard
nginx (8080) - Reverse proxy and load balancer

Supporting infrastructure:

PostgreSQL (5432) - Primary database (relational data)
Redis (6379) - Cache and message queue
OpenSearch (9200) - Full-text search and analytics

Quick Start - Docker (Recommended)

The fastest way to get Rapida running is with Docker Compose.

Prerequisites

Docker Desktop or Docker Engine
Docker Compose (v2.0+)
~4GB available RAM
macOS, Linux, or Windows with WSL2

Step 1: Clone the Repository

git clone https://github.com/rapidaai/voice-ai.git
cd voice-ai

Step 2: Initial Setup

Create the required directories and set permissions:

make setup-local

This command creates:

~/rapida-data/assets/db - PostgreSQL data
~/rapida-data/assets/redis - Redis data
~/rapida-data/assets/opensearch - OpenSearch data

Step 3: Start All Services

make up-all

This starts all services including:

PostgreSQL database
Redis cache
OpenSearch search engine
All API services (web, assistant, integration, endpoint, document)
UI dashboard
Nginx reverse proxy

Step 4: Verify Services

Check that all services are running:

make ps-all

You should see all containers with status Up.

Step 5: Access the Dashboard

Open your browser and navigate to: Dashboard: http://localhost:3000 You should see the Rapida dashboard login page.

Viewing Logs

To monitor service logs:

# All services
make logs-all

# Specific service
make logs-web          # Web API logs
make logs-assistant    # Assistant API logs
make logs-integration  # Integration API logs
make logs-endpoint     # Endpoint API logs

Services Overview

Core Services

web-api (Port 9001)

Purpose: Core platform orchestration and dashboard backend

User and organization management
Workspace and project management
Authentication and authorization
Dashboard API endpoints

Environment Variables:

SERVICE_NAME: web-api
PORT: 9001
LOG_LEVEL: debug/info/warn/error
ENV: development/production
SECRET: Encryption secret

Database: web_db in PostgreSQL

assistant-api (Port 9007)

Purpose: Voice agent and conversation management

Create and manage voice assistants
Handle real-time conversations
Process audio streams
Integrate with LLMs
Audio processing (VAD, STT, TTS)

Environment Variables:

SERVICE_NAME: workflow-api
PORT: 9007
OPENSEARCH__HOST: opensearch
OPENSEARCH__PORT: 9200

Database: assistant_db in PostgreSQL Search Index: OpenSearch Features:

Real-time audio streaming
Voice activity detection (VAD)
Speech-to-text integration
LLM interaction
Text-to-speech synthesis

integration-api (Port 9004)

Purpose: Third-party integrations and credential management

Manage provider credentials (OpenAI, Anthropic, etc.)
Handle OAuth flows
Integration configuration
Provider management

Environment Variables:

PORT: 9004
INTEGRATION_CRYPTO_KEY: Encryption key for credentials

Database: integration_db in PostgreSQL Integrated Providers:

LLMs: OpenAI, Anthropic, Cohere, Google AI, Azure OpenAI, AWS Bedrock, Mistral, HuggingFace
STT: Google Speech, Deepgram, Cartesia, AssemblyAI, Sarvam AI
TTS: Azure Speech, Google TTS, ElevenLabs, Deepgram, Cartesia, Sarvam AI
Telephony: Twilio, Vonage, Exotel

endpoint-api (Port 9005)

Purpose: Webhook and callback management

Webhook configuration
Callback handling
Event routing
External API integration

Environment Variables:

PORT: 9005

Database: endpoint_db in PostgreSQL

document-api (Port 9010)

Purpose: Knowledge base and RAG (Retrieval Augmented Generation)

Document upload and processing
Text chunking and embedding
Similarity search
Knowledge base management

Technology: Python/FastAPI Database: PostgreSQL + OpenSearch Features:

Support for multiple file formats (PDF, DOCX, XLSX, CSV, MD, HTML)
Automatic chunking and embedding
Entity extraction
Full-text search

ui (Port 3000)

Purpose: Web dashboard for managing Rapida

React-based single-page application
Tailwind CSS styling
Real-time updates via WebSocket
Responsive design

Features:

Assistant management
Conversation viewing
Analytics and monitoring
Credential management
Knowledge base management

nginx (Port 8080)

Purpose: Reverse proxy and load balancing

Route traffic to appropriate services
SSL/TLS termination (when configured)
Static file serving (UI)
Load balancing

Main Entry Point: http://localhost:8080

Infrastructure Services

PostgreSQL (Port 5432)

Purpose: Primary relational database Databases:

web_db - Web API data (users, organizations, projects, credentials)
assistant_db - Assistant and conversation data
integration_db - Integration configurations
endpoint_db - Webhook and endpoint data

Credentials:

Username: rapida_user
Password: rapida_db_password

Connection:

# From host
psql -h localhost -U rapida_user -d web_db

# From docker
make db-shell

Data Location: ~/rapida-data/assets/db

Redis (Port 6379)

Purpose: Cache and message queue Features:

Session caching
Rate limiting
Job queue (Celery for document processing)
Real-time data
Database query caching

Database Slots:

DB 0: General cache
DB 1: Session cache
DB 2+: Reserved for future use

Data Location: ~/rapida-data/assets/redis Connection:

redis-cli -h localhost -p 6379

OpenSearch (Port 9200)

Purpose: Full-text search and analytics Features:

Conversation search
Log analysis
Metrics aggregation
Document indexing
Real-time search

Admin Port: 9600 (metrics) Indices:

assistant-conversations - Conversation transcripts
logs-* - Service logs
documents-* - Knowledge base documents

Data Location: ~/rapida-data/assets/opensearch Health Check:

curl http://localhost:9200/_cluster/health

Configuration

Environment Configuration

Each service has environment variables defined in docker/{service}/.{service}.env:

Common Variables

SERVICE_NAME=service-name
HOST=0.0.0.0
PORT=9001
LOG_LEVEL=debug
SECRET=rpd_pks
ENV=development

Database Configuration

POSTGRES__HOST=postgres
POSTGRES__PORT=5432
POSTGRES__DB_NAME=web_db
POSTGRES__AUTH__USER=rapida_user
POSTGRES__AUTH__PASSWORD=rapida_db_password
POSTGRES__SSL_MODE=disable
POSTGRES__MAX_OPEN_CONNECTION=10
POSTGRES__MAX_IDEAL_CONNECTION=5

Redis Configuration

REDIS__HOST=redis
REDIS__PORT=6379
REDIS__MAX_CONNECTION=10
REDIS__DB=0

OpenSearch Configuration

OPENSEARCH__SCHEMA=http
OPENSEARCH__HOST=opensearch
OPENSEARCH__PORT=9200
OPENSEARCH__MAX_RETRIES=3
OPENSEARCH__MAX_CONNECTION=10

Modifying Configuration

Edit the environment file:
```
vi docker/web-api/.web.env
```
Restart the service:
```
make restart-web
```

Common Docker Commands

Service Management

# Start specific services
make up-web              # Start only web-api
make up-assistant        # Start only assistant-api
make up-db              # Start only PostgreSQL

# Stop services
make down-web           # Stop web-api
make down-all           # Stop all services

# Restart services
make restart-web        # Restart web-api
make restart-all        # Restart all services

Viewing Status

# Show running containers and ports
make ps-all

# Show service status
docker ps

# Show container logs
make logs-web
make logs-all -f        # Follow logs in real-time

Database Management

# Open PostgreSQL shell
make db-shell

# View database contents
psql -h localhost -U rapida_user -d web_db

# Common queries
\dt                     # List tables
\du                     # List users
SELECT * FROM table;    # Query table

Cleaning Up

# Stop and remove all containers
make clean

# Remove only volumes (data)
make clean-volumes

# Remove images
docker rmi $(docker images -q)

Manual Setup (Without Docker)

For development or if you prefer not to use Docker, follow these steps:

Prerequisites

Go 1.25 or later
Python 3.9+
Node.js 22+
PostgreSQL 15+
Redis 7+
OpenSearch 2.11+

Step 1: Install Dependencies

macOS

# Using Homebrew
brew install go postgresql redis
brew install --cask docker  # Optional: for OpenSearch

# Install Node.js
nvm install 22
nvm use 22

# Install Python
python3 -m venv venv
source venv/bin/activate

Linux (Ubuntu/Debian)

# Install system dependencies
sudo apt-get update
sudo apt-get install -y golang-go postgresql redis-server git build-essential

# Install Node.js
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

# Install Python
sudo apt-get install -y python3 python3-pip python3-venv

Step 2: Configure Databases

PostgreSQL Setup

# Start PostgreSQL
brew services start postgresql    # macOS
sudo service postgresql start     # Linux

# Create user and databases
psql postgres -c "CREATE USER rapida_user WITH PASSWORD 'rapida_db_password';"
psql postgres -c "CREATE DATABASE web_db OWNER rapida_user;"
psql postgres -c "CREATE DATABASE assistant_db OWNER rapida_user;"
psql postgres -c "CREATE DATABASE integration_db OWNER rapida_user;"
psql postgres -c "CREATE DATABASE endpoint_db OWNER rapida_user;"

# Grant privileges
psql postgres -c "ALTER ROLE rapida_user WITH CREATEDB;"

Redis Setup

# Start Redis
brew services start redis         # macOS
sudo service redis-server start   # Linux

# Verify Redis is running
redis-cli ping
# Should return: PONG

OpenSearch Setup

# Using Docker (simplest method)
docker run -d -p 9200:9200 -p 9600:9600 \
  -e "discovery.type=single-node" \
  -e "plugins.security.disabled=true" \
  opensearchproject/opensearch:2.11.1

# Or install from source (follow OpenSearch docs)

Step 3: Setup Environment Files

Copy environment template files and configure them:

# Copy environment files
cp docker/web-api/.web.env env/.web.env
cp docker/assistant-api/.assistant.env env/.assistant.env
cp docker/integration-api/.integration.env env/.integration.env
cp docker/endpoint-api/.endpoint.env env/.endpoint.env

# Edit for local environment
vi env/.web.env

# Change these values for local development:
POSTGRES__HOST=localhost        # Change from "postgres"
REDIS__HOST=localhost           # Change from "redis"
OPENSEARCH__HOST=localhost      # Change from "opensearch"

Step 4: Build Go Services

Build each microservice:

# Create output directory
mkdir -p bin

# Build each service
go build -o bin/web-api ./cmd/web/web.go
go build -o bin/assistant-api ./cmd/assistant/assistant.go
go build -o bin/integration-api ./cmd/integration/integration.go
go build -o bin/endpoint-api ./cmd/endpoint/endpoint.go

Step 5: Run Database Migrations

# Install migration tool
go install -tags 'postgres' github.com/golang-migrate/migrate/v4/cmd/migrate@latest

# Run migrations for each service
migrate -path api/web-api/migrations -database "postgresql://rapida_user:rapida_db_password@localhost:5432/web_db?sslmode=disable" up
migrate -path api/assistant-api/migrations -database "postgresql://rapida_user:rapida_db_password@localhost:5432/assistant_db?sslmode=disable" up
migrate -path api/integration-api/migrations -database "postgresql://rapida_user:rapida_db_password@localhost:5432/integration_db?sslmode=disable" up
migrate -path api/endpoint-api/migrations -database "postgresql://rapida_user:rapida_db_password@localhost:5432/endpoint_db?sslmode=disable" up

Step 6: Setup Frontend

# Navigate to UI directory
cd ui

# Install dependencies
yarn install

# Build CSS
yarn build:css

# Start development server
yarn start:dev

# This runs Tailwind watch and React dev server concurrently

Step 7: Start Services

Open separate terminal windows for each service:

Terminal 1: Web API

export $(cat env/.web.env | xargs)
go run ./cmd/web/web.go
# Or run the built binary
./bin/web-api

Terminal 2: Assistant API

export $(cat env/.assistant.env | xargs)
go run ./cmd/assistant/assistant.go

Terminal 3: Integration API

export $(cat env/.integration.env | xargs)
go run ./cmd/integration/integration.go

Terminal 4: Endpoint API

export $(cat env/.endpoint.env | xargs)
go run ./cmd/endpoint/endpoint.go

Terminal 5: Document API

cd api/document-api

# Create Python virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Run the service
python app/main.py

Terminal 6: UI (Already running from Step 6)

The UI should be running at http://localhost:3000

Step 8: Verify Services

Check that all services are running:

# API endpoints should respond
curl http://localhost:9001/health
curl http://localhost:9007/health
curl http://localhost:9004/health
curl http://localhost:9005/health
curl http://localhost:9010/health

# UI should be accessible
curl http://localhost:3000

# Database should be accessible
psql -h localhost -U rapida_user -d web_db -c "SELECT 1;"

# Redis should be accessible
redis-cli ping

# OpenSearch should be accessible
curl http://localhost:9200/_cluster/health

Troubleshooting

Service Won’t Start

Problem: Service container exits immediately Solution:

# Check logs
make logs-web

# Common causes:
# 1. Port already in use - change PORT in env file
# 2. Database not running - verify postgres is up
# 3. Invalid credentials - check env file

Database Connection Issues

Problem: connection refused errors Solution:

# Verify PostgreSQL is running
psql -h localhost -U rapida_user -d web_db -c "SELECT 1;"

# Check PostgreSQL logs
docker logs postgres

# Restart PostgreSQL
make down-db && make up-db

Memory Issues

Problem: OpenSearch or container running out of memory Solution:

# Increase Docker memory limit
# Docker Desktop -> Preferences -> Resources -> Memory: 8GB (minimum)

# Or reduce OpenSearch memory usage
# Edit docker-compose.yml
OPENSEARCH_JAVA_OPTS: "-Xms256m -Xmx256m"

Redis Connection Issues

Problem: Redis connection refused Solution:

# Check Redis is running
redis-cli ping

# Restart Redis
make down-redis && make up-redis

# Check Redis logs
docker logs redis

Performance Optimization

For Development

# Reduce resource allocation
# Edit docker-compose.yml and reduce limits

# Use only required services
make up-web
make up-db
make up-redis
# Skip assistant-api if not needed

For Production

Increase connection pools
Enable caching
Set LOG_LEVEL to info
Use managed databases (AWS RDS, Azure Database)
Configure OpenSearch for production
Use separate Redis instances for different purposes

Next Steps

Create Your First Assistant: See Assistant Documentation
Integrate LLMs: See LLM Integrations
Add Knowledge Base: See Knowledge Management
Deploy: See Deployment Options

Getting Help

GitHub Issues: https://github.com/rapidaai/voice-ai/issues
Documentation: https://rapida.ai/docs
Community: https://github.com/rapidaai/voice-ai/discussions
Support Email: prashant@rapida.ai

Getting Started

Services

​Rapida Voice AI Platform - Developer Guide

​What is Rapida?

​Architecture Overview

​Quick Start - Docker (Recommended)

​Prerequisites

​Step 1: Clone the Repository

​Step 2: Initial Setup

​Step 3: Start All Services

​Step 4: Verify Services

​Step 5: Access the Dashboard

​Viewing Logs

​Services Overview

​Core Services

​web-api (Port 9001)

​assistant-api (Port 9007)

​integration-api (Port 9004)

​endpoint-api (Port 9005)

​document-api (Port 9010)

​ui (Port 3000)

​nginx (Port 8080)

​Infrastructure Services

​PostgreSQL (Port 5432)

​Redis (Port 6379)

​OpenSearch (Port 9200)

​Configuration

​Environment Configuration

​Common Variables

​Database Configuration

​Redis Configuration

​OpenSearch Configuration

​Modifying Configuration

​Common Docker Commands

​Service Management

​Viewing Status

​Database Management

​Cleaning Up

​Manual Setup (Without Docker)

​Prerequisites

​Step 1: Install Dependencies

​macOS

​Linux (Ubuntu/Debian)

​Step 2: Configure Databases

​PostgreSQL Setup

​Redis Setup

​OpenSearch Setup

​Step 3: Setup Environment Files

​Step 4: Build Go Services

​Step 5: Run Database Migrations

​Step 6: Setup Frontend

​Step 7: Start Services

​Terminal 1: Web API

​Terminal 2: Assistant API

​Terminal 3: Integration API

​Terminal 4: Endpoint API

​Terminal 5: Document API

​Terminal 6: UI (Already running from Step 6)

​Step 8: Verify Services

​Troubleshooting

​Service Won’t Start

​Database Connection Issues

​Memory Issues

​Redis Connection Issues

​Performance Optimization

​For Development

​For Production

​Next Steps

​Getting Help

Rapida Voice AI Platform - Developer Guide

What is Rapida?

Architecture Overview

Quick Start - Docker (Recommended)

Prerequisites

Step 1: Clone the Repository

Step 2: Initial Setup

Step 3: Start All Services

Step 4: Verify Services

Step 5: Access the Dashboard

Viewing Logs

Services Overview

Core Services

web-api (Port 9001)

assistant-api (Port 9007)

integration-api (Port 9004)

endpoint-api (Port 9005)

document-api (Port 9010)

ui (Port 3000)

nginx (Port 8080)

Infrastructure Services

PostgreSQL (Port 5432)

Redis (Port 6379)

OpenSearch (Port 9200)

Configuration

Environment Configuration

Common Variables

Database Configuration

Redis Configuration

OpenSearch Configuration

Modifying Configuration

Common Docker Commands

Service Management

Viewing Status

Database Management

Cleaning Up

Manual Setup (Without Docker)

Prerequisites

Step 1: Install Dependencies

macOS

Linux (Ubuntu/Debian)

Step 2: Configure Databases

PostgreSQL Setup

Redis Setup

OpenSearch Setup

Step 3: Setup Environment Files

Step 4: Build Go Services

Step 5: Run Database Migrations

Step 6: Setup Frontend

Step 7: Start Services

Terminal 1: Web API

Terminal 2: Assistant API

Terminal 3: Integration API

Terminal 4: Endpoint API

Terminal 5: Document API

Terminal 6: UI (Already running from Step 6)

Step 8: Verify Services

Troubleshooting

Service Won’t Start

Database Connection Issues

Memory Issues

Redis Connection Issues

Performance Optimization

For Development

For Production

Next Steps

Getting Help