Installation

Get Rapida up and running - Choose your setup method

Choose deployment mode

Select one mode before running commands:

Voice Only (Recommended)

• Use this for voice assistants that call LLM providers directly.
• 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 assistants need document retrieval (RAG).
• 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)

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

1. Install Docker and Docker Compose

   macOS

   # 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.
   
2. 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
   
3. Clone Repository

   git clone https://github.com/rapidaai/voice-ai.git
   cd voice-ai
   
4. 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)
5. Run preflight checks (recommended)

   make doctor
   

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

6. Start Rapida

   Voice Only (recommended)

   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
   

   With Knowledge Base

   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
   
7. Optional: pre-build images separately

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

   Voice Only (recommended)

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

   make build-all
   

   With Knowledge Base

   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.

8. 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 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:

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

Manual Setup

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

macOS

# 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

macOS

# 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

macOS

# 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.

macOS

# 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.

macOS

# 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:

Web Api

go run cmd/web/web.go

Optional — only needed for knowledge base:

Document Api (optional)

# 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

1. Check if ports are available:

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

2. Check PostgreSQL logs:

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

# Linux
sudo journalctl -u postgresql -f

Connection Issues

1. Verify PostgreSQL is running:

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

2. Verify Redis is running:

redis-cli ping

3. Verify OpenSearch is running:

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

Next Steps

After installation:

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