Installation - rapida.ai documentation

Choose deployment mode

Select one mode before running commands:

Voice Only (Recommended)

Use this for voice assistants that call LLM providers directly and you want the smallest controlled deployment footprint.
Services started: ui, nginx, web-api, assistant-api, integration-api, endpoint-api, postgres, redis
Minimum RAM: 4 GB
Start command (builds and starts): make up-all
Optional pre-build command: make build-all

make up-all

Voice + Knowledge Base

Use this if teams or clients need private document retrieval (RAG) in the same controlled environment.
Adds: document-api and opensearch
Minimum RAM: 8 to 16 GB
Start command (builds and starts): make up-all-with-knowledge
Optional pre-build command: make build-all-with-knowledge

make up-all-with-knowledge

You can start with Voice Only and switch later by running make up-all-with-knowledge. Existing PostgreSQL and Redis data is not changed.

Docker (Recommended)
Manual Setup

The fastest way to get Rapida running on infrastructure your team controls. Best for agencies, internal platform teams, and enterprise environments that need ownership of keys, networking, and runtime behavior.

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 base images are built for linux/amd64. The Makefile sets DOCKER_DEFAULT_PLATFORM=linux/amd64 automatically for all make commands. Use make commands instead of 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)

Run preflight checks (recommended)

make doctor

This validates Docker daemon access, Docker Compose availability, memory/disk constraints, and common local port conflicts.

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. This command also builds required images in low-memory mode.

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. This command also builds required images in low-memory mode.

make up-all-with-knowledge

Optional: pre-build images separately

If you want to pre-build before startup or use CI cache warming:

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.

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 + 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
make down-web

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 settings in docker/web-api/web.yml:

postgres:
  host: host.docker.internal
  port: 5432
  db_name: web_db
  auth:
    user: your_user
    password: your_password

Example: Use Existing Redis

Comment out Redis in docker-compose.yml:

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

Update Redis settings in the service YAML files:

redis:
  host: host.docker.internal
  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 update docker/assistant-api/assistant.knowledge.yml:

opensearch:
  schema: http
  host: host.docker.internal
  port: 9200
  auth:
    user: admin
    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

Documentation Index

​Choose deployment mode

​Voice Only (Recommended)

​Voice + 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

Choose deployment mode

Voice Only (Recommended)

Voice + 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