Installation

Before you start — voice only or with knowledge base?

Rapida has two deployment modes. Choose before running any commands.

	Voice Assistant Only	Voice + Knowledge Base
What it does	Build voice assistants that call LLMs directly	Everything in Voice Only, plus upload documents and answer questions from your own content
Extra services	—	`document-api` (Python) + `opensearch`
RAM	4 GB minimum	8–16 GB (OpenSearch is memory-intensive)
Build command	`make build-all`	`make build-all-with-knowledge`
Start command	`make up-all`	`make up-all-with-knowledge`
Best for	Most users — calling bots, IVR, voice agents	Assistants that answer questions from your PDFs, docs, or CSVs

Start with Voice Only. You can add the knowledge base later at any time by running make up-all-with-knowledge. No existing data is affected.

Docker (Recommended)
Manual Setup

The fastest way to get Rapida running with all services configured automatically.

Prerequisites

Docker Desktop or Docker Engine (v20.10+)
Docker Compose (v2.0+) - included with Docker Desktop
4GB+ RAM available
10GB free disk space

Apple Silicon (M1/M2/M3/M4): Rapida’s base images are built for linux/amd64. The Makefile automatically sets DOCKER_DEFAULT_PLATFORM=linux/amd64 so all make commands work correctly without any extra configuration. Always use make build-all rather than running docker compose build directly.

Installation Steps

Install Docker and Docker Compose

# Using Homebrew
brew install --cask docker

# Or download from Docker website
# https://www.docker.com/products/docker-desktop

# Then open Docker.app from Applications folder.

Verify Installation

# Check Docker
docker --version
# Expected: Docker version 20.10+

# Check Docker Compose
docker compose version
# Expected: version 2.0+

# Test Docker
docker run hello-world

Clone Repository

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

Run Setup

# Create data directories and set permissions
make setup-local

This creates:

~/rapida-data/assets/db - PostgreSQL
~/rapida-data/assets/redis - Redis
~/rapida-data/assets/opensearch - OpenSearch (only used with the knowledge base profile)

Build images

Voice Only (recommended)
With Knowledge Base

Builds all core services. Does not include document-api or opensearch.

make build-all

Builds everything, including document-api (Python image) and pulls the OpenSearch image. Requires 8–16 GB RAM due to OpenSearch.

make build-all-with-knowledge

Initial build takes 5–10 minutes depending on your network speed.

Start Rapida

Voice Only (recommended)
With Knowledge Base

Starts all core services: web-api, assistant-api, integration-api, endpoint-api, UI, PostgreSQL, Redis, and Nginx. document-api and opensearch are not started.

make up-all

Starts everything above plus document-api and opensearch. Use this if you want to upload documents and use RAG / vector search in your assistants.

make up-all-with-knowledge

Access Dashboard

Open your browser:

Dashboard: http://localhost:3000
API Gateway: http://localhost:8080

Verify Services Are Running

make ps-all

All containers should show Up status.

Enabling Knowledge Base Later

Started with Voice Only and want to add knowledge base support? No reinstall needed:

# Build the document-api image (first time only)
make build-all-with-knowledge

# Start document-api and opensearch alongside existing services
make up-all-with-knowledge

Your existing data (PostgreSQL, Redis) is untouched. The new services simply start alongside what’s already running.

View Logs

# All services
make logs-all

# Specific service
make logs-web
make logs-assistant
make logs-db

Stop Services

# Stop all services
make down-all

# Stop specific service
docker compose stop web-api

Using Existing Infrastructure

If you already have PostgreSQL, Redis, or OpenSearch running, you can skip those services.

Example: Use Existing PostgreSQL

Edit docker-compose.yml and comment out or remove the postgres service:

# postgres:
#   image: postgres:15
#   ...

Update PostgreSQL environment variables in docker/web-api/.web.env:

POSTGRES__HOST=host.docker.internal  # Point to host machine
POSTGRES__PORT=5432
POSTGRES__DB_NAME=web_db
POSTGRES__AUTH__USER=your_user
POSTGRES__AUTH__PASSWORD=your_password

Example: Use Existing Redis

Comment out Redis in docker-compose.yml:

# redis:
#   image: redis:7
#   ...

Update Redis settings in service .env files:

REDIS__HOST=host.docker.internal  # Your Redis host
REDIS__PORT=6379

Example: Use Existing OpenSearch

OpenSearch is only required for the knowledge base. If you don’t need knowledge base features, simply run make up-all (without the with-knowledge profile) and OpenSearch is not started at all.If you do need knowledge base support and want to use an existing OpenSearch instance, comment out the opensearch service in docker-compose.knowledge.yml:

# opensearch:
#   image: opensearchproject/opensearch:2.11
#   ...

Then set the OpenSearch vars in docker/assistant-api/.assistant.env:

OPENSEARCH__SCHEMA=http
OPENSEARCH__HOST=host.docker.internal
OPENSEARCH__PORT=9200
OPENSEARCH__USER=admin
OPENSEARCH__PASSWORD=admin

And run with the knowledge profile:

make up-all-with-knowledge

Next Steps

After installation:

Configure Services - Set up API keys and integrations
Services Overview - Understand what each service does
Troubleshooting - Fix common issues

For developers who prefer not to use Docker. This requires installing each component individually.

Same choice applies here: Voice Only (PostgreSQL + Redis only) or With Knowledge Base (PostgreSQL + Redis + OpenSearch + Python). If you only need voice assistants, skip the OpenSearch and Python/document-api sections below.

Prerequisites

# Install Homebrew first (if not installed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install required tools
brew install go@1.25 python@3.11 node@22 postgresql@15 redis opensearch

# Verify installations
go version      # go1.25+
python --version # python3.11+
node --version  # node22+

PostgreSQL

# Start PostgreSQL
brew services start postgresql@15

# Verify it's running
psql --version

Create databases:

# Connect to PostgreSQL
psql postgres

# Run these SQL commands:
CREATE USER rapida_user WITH PASSWORD 'rapida_db_password';
CREATE DATABASE web_db OWNER rapida_user;
CREATE DATABASE assistant_db OWNER rapida_user;
CREATE DATABASE integration_db OWNER rapida_user;
CREATE DATABASE endpoint_db OWNER rapida_user;
GRANT ALL PRIVILEGES ON DATABASE web_db TO rapida_user;
GRANT ALL PRIVILEGES ON DATABASE assistant_db TO rapida_user;
GRANT ALL PRIVILEGES ON DATABASE integration_db TO rapida_user;
GRANT ALL PRIVILEGES ON DATABASE endpoint_db TO rapida_user;
\q

Redis

# Start Redis
brew services start redis

# Verify it's running
redis-cli ping
# Should return: PONG

OpenSearch (Optional — Knowledge Base Only)

OpenSearch is only needed if you want to use knowledge base / RAG features. Skip this section if you only need voice assistant functionality.

# Install OpenSearch (requires Java)
brew tap opensearch-project/opensearch
brew install opensearch

# Start OpenSearch
opensearchctl start

# Verify it's running
curl -s http://localhost:9200/_cluster/health | jq .

Clone Repository

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

Install Assistant API Dependencies

The Assistant API requires RNNoise and Azure Speech SDK for audio processing.

# Install RNNoise
brew install autoconf automake libtool pkg-config
git clone https://github.com/rapidaai/rnnoise.git
cd rnnoise
./autogen.sh
./configure --prefix=/usr/local
make -j$(sysctl -n hw.ncpu)
sudo make install
cd ..

# Install Azure Speech SDK
wget -O SpeechSDK-macOS.tar.gz https://aka.ms/csspeech/macosbinary
mkdir -p ~/opt/azure-speech-sdk
tar --strip 1 -xzf SpeechSDK-macOS.tar.gz -C ~/opt/azure-speech-sdk
rm SpeechSDK-macOS.tar.gz

# Add to shell profile (~/.zprofile or ~/.bash_profile)
export LD_LIBRARY_PATH="$HOME/opt/azure-speech-sdk/lib:$LD_LIBRARY_PATH"
export DYLD_LIBRARY_PATH="$HOME/opt/azure-speech-sdk/lib:$DYLD_LIBRARY_PATH"

Set Up Go Services

# Build all Go services
make build-all

# Or build individually
make build-web
make build-assistant
make build-integration
make build-endpoint

Set Up Python Services (Optional — Knowledge Base Only)

The document-api is only needed if you want to use the knowledge base / RAG features. Skip this step if you only need voice assistant functionality.

# Create Python virtual environment
cd api/document-api
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Note: rn_noise is included in requirements

Set Up Frontend

cd ui

# Install dependencies
yarn install

# Build CSS
yarn build:css

Start Services (in separate terminals)

Required for both modes — start these four services first:

go run cmd/web/web.go

Optional — only needed for knowledge base:

# Requires OpenSearch running and Python venv activated
cd api/document-api
source venv/bin/activate
cd ../..
PYTHONPATH=api/document-api uvicorn app.main:app --host 0.0.0.0 --port 9010

Step 7: Access Dashboard

Open your browser:

Dashboard: http://localhost:3000
API Gateway: http://localhost:8080 (requires Nginx setup)

Using Existing Infrastructure

If you already have PostgreSQL, Redis, or OpenSearch installed:

Skip PostgreSQL Installation

Just create the databases:

psql -h localhost -U your_user -d postgres
CREATE DATABASE web_db;
CREATE DATABASE assistant_db;
CREATE DATABASE integration_db;
CREATE DATABASE endpoint_db;

Skip Redis Installation

Just update the Redis URL:

export REDIS_URL="redis://your-redis-host:6379/0"

Skip OpenSearch Installation

OpenSearch is only required for the knowledge base. If you don’t need knowledge base features, you can skip OpenSearch entirely — just don’t set OPENSEARCH__HOST and the assistant-api will start without knowledge base support.If you do need knowledge base support, update the OpenSearch env vars in your assistant-api config:

export OPENSEARCH__SCHEMA=http
export OPENSEARCH__HOST=your-opensearch-host
export OPENSEARCH__PORT=9200

Troubleshooting

Services Won’t Start

Check if ports are available:

lsof -i :9001  # For web-api
lsof -i :5432  # For PostgreSQL

Check PostgreSQL logs:

# macOS
tail -f /usr/local/var/log/postgres.log

# Linux
sudo journalctl -u postgresql -f

Connection Issues

Verify PostgreSQL is running:

psql -h localhost -U rapida_user -d web_db -c "SELECT 1;"

Verify Redis is running:

redis-cli ping

Verify OpenSearch is running:

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

Next Steps

After installation:

Configure Services - Set up API keys and integrations
Services Overview - Understand what each service does
Troubleshooting - Fix common issues

Getting Started

Dashboard (UI)

Web API

Assistant API

Integration API

Endpoint API

Document API

Before you start — voice only or with knowledge base?

Prerequisites

Installation Steps

Verify Services Are Running

Enabling Knowledge Base Later

View Logs

Stop Services

Using Existing Infrastructure

Example: Use Existing PostgreSQL

Example: Use Existing Redis

Example: Use Existing OpenSearch

Next Steps

Prerequisites

PostgreSQL

Redis

OpenSearch (Optional — Knowledge Base Only)

Clone Repository

Install Assistant API Dependencies

Set Up Go Services

Set Up Python Services (Optional — Knowledge Base Only)

Set Up Frontend

Start Services (in separate terminals)

Step 7: Access Dashboard

Using Existing Infrastructure

Skip PostgreSQL Installation

Skip Redis Installation

Skip OpenSearch Installation

Troubleshooting

Services Won’t Start

Connection Issues

Next Steps

Getting Started

Dashboard (UI)

Web API

Assistant API

Integration API

Endpoint API

Document API

​Before you start — voice only or with knowledge base?

​Prerequisites

​Installation Steps

​Verify Services Are Running

​Enabling Knowledge Base Later

​View Logs

​Stop Services

​Using Existing Infrastructure

​Example: Use Existing PostgreSQL

​Example: Use Existing Redis

​Example: Use Existing OpenSearch

​Next Steps

​Prerequisites

​PostgreSQL

​Redis

​OpenSearch (Optional — Knowledge Base Only)

​Clone Repository

​Install Assistant API Dependencies

​Set Up Go Services

​Set Up Python Services (Optional — Knowledge Base Only)

​Set Up Frontend

​Start Services (in separate terminals)

​Step 7: Access Dashboard

​Using Existing Infrastructure

​Skip PostgreSQL Installation

​Skip Redis Installation

​Skip OpenSearch Installation

​Troubleshooting

​Services Won’t Start

​Connection Issues

​Next Steps

Before you start — voice only or with knowledge base?

Prerequisites

Installation Steps

Verify Services Are Running

Enabling Knowledge Base Later

View Logs

Stop Services

Using Existing Infrastructure

Example: Use Existing PostgreSQL

Example: Use Existing Redis

Example: Use Existing OpenSearch

Next Steps

Prerequisites

PostgreSQL

Redis

OpenSearch (Optional — Knowledge Base Only)

Clone Repository

Install Assistant API Dependencies

Set Up Go Services

Set Up Python Services (Optional — Knowledge Base Only)

Set Up Frontend

Start Services (in separate terminals)

Step 7: Access Dashboard

Using Existing Infrastructure

Skip PostgreSQL Installation

Skip Redis Installation

Skip OpenSearch Installation

Troubleshooting

Services Won’t Start

Connection Issues

Next Steps