Self hosted Deployment

Choose Your Deployment Mode

Rapida ships as two Docker Compose configurations. Self-hosted is the right starting point for agencies that need client ownership and enterprise teams that need scale, governance, and infrastructure control.

	Voice Assistant Only	Voice + Knowledge Base
What it does	Build voice assistants that call LLMs directly on infrastructure you own	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`

Start with Voice Only. You can add the knowledge base at any time by running make up-all-with-knowledge — no data is lost and your ownership model does not change.

Quickstart

Requirements

Docker Desktop (Mac / Windows) or Docker Engine v20.10+ with Docker Compose v2.0+ (Linux)
Voice Only: 4 GB RAM, 10 GB free disk
With Knowledge Base: 8–16 GB RAM, 20 GB free disk

Steps

Clone the repository

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

Create data directories

make setup-local

This creates ~/rapida-data/assets/db, ~/rapida-data/assets/redis, and ~/rapida-data/assets/opensearch and sets the correct permissions.

On macOS, setup-local calls sudo setfacl which requires the acl package. If it fails, create the directories manually:

mkdir -p ~/rapida-data/assets/{db,redis,opensearch}

Configure YAML files

Each service has a YAML config file under docker/<service>/. Edit them with your API keys and settings:

docker/web-api/web.yml
docker/assistant-api/assistant.yml
docker/integration-api/integration.yml
docker/endpoint-api/endpoint.yml

This is where you define provider keys, networking, runtime behavior, and client- or environment-specific settings.See Configuration for a full reference of all variables.

Build images

Voice Only (recommended)
With Knowledge Base

make build-all

Builds: web-api, assistant-api, integration-api, endpoint-api, ui. Does not include document-api or opensearch.Initial build takes 10–25 minutes (the assistant-api uses CGO with the Azure Speech SDK).

make build-all-with-knowledge

Builds everything above plus document-api (Python image). Requires 8–16 GB RAM.

Start Rapida

Voice Only (recommended)
With Knowledge Base

make up-all

Starts: postgres, redis, web-api, assistant-api, integration-api, endpoint-api, ui, nginx.

make up-all-with-knowledge

Starts everything above plus opensearch and document-api.

Open the dashboard

Navigate to http://localhost:3000 in your browser.Check container status with:

make status

Common Issues

Port conflicts

If you see “port is already in use”, another service on your machine is using one of Rapida’s ports (5432, 6379, 9001, 9004, 9005, 9007, 8080, 3000). Stop the conflicting service or edit the port mapping in docker-compose.yml.

Container name conflicts

Rapida containers use common names (postgres, redis, opensearch). If you run other projects with the same names, stop them first:

docker stop postgres redis opensearch
docker rm postgres redis opensearch

Out of memory

If containers are killed during startup (exit code 137), Docker does not have enough memory allocated.

Docker Desktop → Settings → Resources → Memory: set to 8 GB (Voice Only: 4 GB minimum)
Tip: Stop all services before rebuilding — make down-all then make build-all — to avoid OOM during builds.

`document-api` unhealthy on first boot

On first startup, document-api can take 30–60 seconds to connect to OpenSearch. If make up-all-with-knowledge exits with a dependency error, wait a moment and run it again:

make up-all-with-knowledge

Next Steps

Installation guide — detailed Docker and manual setup
Overview — architecture and service descriptions
Configuration — all environment variable references

Assistants

Knowledge

LLM Endpoint

Activity & Logs

External Integrations

Credentials

Workspace

Governance

Deployment Options

Choose Your Deployment Mode

Quickstart

Requirements

Steps

Common Issues

Port conflicts

Container name conflicts

Out of memory

`document-api` unhealthy on first boot

Next Steps

​Choose Your Deployment Mode

​Quickstart

​Requirements

​Steps

​Common Issues

​Port conflicts

​Container name conflicts

​Out of memory

​document-api unhealthy on first boot

​Next Steps

Choose Your Deployment Mode

Quickstart

Requirements

Steps

Common Issues

Port conflicts

Container name conflicts

Out of memory

`document-api` unhealthy on first boot

Next Steps