Self hosted Deployment

Deploy the Rapida Voice AI Platform on your own infrastructure using Docker Compose

Choose Your Deployment Mode

Rapida ships as two Docker Compose configurations. Pick one before you start.

	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

Start with Voice Only. You can add the knowledge base at any time by running make up-all-with-knowledge — no data is lost.

---

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

1. Clone the repository

   git clone https://github.com/rapidaai/voice-ai.git
   cd voice-ai
   
2. 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}
   
3. Configure environment files

   Each service has an env file under docker/<service>/. Edit them with your API keys and settings:

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

   See Configuration for a full reference of all variables.

4. Build images

   Voice Only (recommended)

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

   With Knowledge Base

   make build-all-with-knowledge
   

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

5. Start Rapida

   Voice Only (recommended)

   make up-all
   

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

   With Knowledge Base

   make up-all-with-knowledge
   

   Starts everything above plus opensearch and document-api.

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