> ## Documentation Index
> Fetch the complete documentation index at: https://doc.rapida.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Self-Hosting Rapida

> Run the full Rapida Voice AI platform on your own infrastructure. Docker Compose gets agencies and enterprise teams to a working deployment quickly while keeping control of data, credentials, and runtime boundaries.

## Choose your setup

Rapida supports two self-hosted deployment modes. Pick the one that matches how much retrieval and infrastructure footprint you need before you start.

<Tabs>
  <Tab title="Voice Assistant Only (Recommended)">
    **Best for most users.** Build and run AI voice assistants — inbound/outbound calls, real-time STT/LLM/TTS, webhooks, and telephony integrations.

    No OpenSearch or Python services required. Lower RAM, simpler setup, faster to get started.

    **Services started:** web-api · assistant-api · integration-api · endpoint-api · UI · PostgreSQL · Redis · Nginx

    **Services skipped:** document-api · OpenSearch

    **RAM needed:** 4 GB minimum

    ```bash theme={null}
    # Build images
    make build-all

    # Start all services
    make up-all
    ```

    That's it — open [http://localhost:3000](http://localhost:3000) and create your first assistant in an environment you control.
  </Tab>

  <Tab title="Voice Assistant + Knowledge Base">
    **Add this when you need RAG.** Everything in Voice Only, plus the ability to upload documents (PDF, DOCX, CSV, etc.) and have the assistant search and answer questions from your own content using vector embeddings.

    Requires OpenSearch (memory-intensive) and the Python `document-api` service.

    **Extra services added:** document-api · OpenSearch

    **RAM needed:** 8–16 GB (OpenSearch alone uses 4–8 GB)

    ```bash theme={null}
    # Build images (includes document-api Python image)
    make build-all-with-knowledge

    # Start all services including document-api and opensearch
    make up-all-with-knowledge
    ```

    After starting, go to **Knowledge** in the dashboard to create a knowledge base and upload documents.
  </Tab>
</Tabs>

<Info>
  **Not sure which to pick?** Start with Voice Only (`make up-all`). You can add the knowledge base at any time later — just run `make up-all-with-knowledge`. No existing data is lost and you keep the same deployment model.
</Info>

***

## What is the knowledge base?

The knowledge base lets your voice assistant answer questions grounded in your own documents. When a caller asks something, the assistant searches your uploaded content and injects the most relevant passages into the LLM prompt before generating a response. This is called Retrieval-Augmented Generation (RAG).

| Feature                              | Without knowledge base | With knowledge base |
| ------------------------------------ | ---------------------- | ------------------- |
| Voice calls (STT → LLM → TTS)        | ✅                      | ✅                   |
| Inbound / outbound telephony         | ✅                      | ✅                   |
| Webhooks & callbacks                 | ✅                      | ✅                   |
| LLM provider integrations            | ✅                      | ✅                   |
| Upload documents (PDF, DOCX, CSV…)   | ✗                      | ✅                   |
| Answer questions from your documents | ✗                      | ✅                   |
| Semantic / vector search             | ✗                      | ✅                   |
| OpenSearch required                  | ✗                      | ✅                   |
| RAM requirement                      | \~4 GB                 | \~8–16 GB           |

***

## What you are deploying

Rapida is a microservices platform. Self-hosting means running all services on your own infrastructure so you control the runtime boundary, network path, and operational model.

| Service           | Port        | Role                                                                          |
| ----------------- | ----------- | ----------------------------------------------------------------------------- |
| `nginx`           | 8080        | Reverse proxy, WebSocket upgrade, SSL/TLS termination                         |
| `web-api`         | 9001        | Auth, organizations, credential vault, gRPC proxy                             |
| `assistant-api`   | 9007 · 4573 | Voice orchestration, STT/LLM/TTS pipeline, telephony                          |
| `integration-api` | 9004        | LLM, STT, TTS provider integrations                                           |
| `endpoint-api`    | 9005        | Webhook delivery and event routing                                            |
| `document-api`    | 9010        | Document ingestion, embeddings, RAG search *(optional — knowledge base only)* |
| `ui`              | 3000        | React dashboard                                                               |
| `postgres`        | 5432        | Relational data (4 databases)                                                 |
| `redis`           | 6379        | Cache, sessions, job queue                                                    |
| `opensearch`      | 9200        | Conversation search, document indexing *(optional — knowledge base only)*     |

<Info>
  The recommended path for self-hosting is Docker Compose. All services, infrastructure, and Nginx are wired together in `docker-compose.yml`. No manual network or volume configuration is needed.
</Info>

***

## Prerequisites

| Requirement    | Version                      | Notes                                                                                   |
| -------------- | ---------------------------- | --------------------------------------------------------------------------------------- |
| Docker Engine  | 20.10+                       | [Install Docker](https://docs.docker.com/get-docker/)                                   |
| Docker Compose | v2.0+                        | Included with Docker Desktop                                                            |
| RAM            | 4 GB minimum                 | 8 GB recommended; 16 GB if running with knowledge base (OpenSearch is memory-intensive) |
| Disk           | 10 GB free                   | For images, volumes, and uploaded assets                                                |
| OS             | macOS · Linux · Windows WSL2 |                                                                                         |

***

## Quickstart

<Steps>
  <Step title="Clone the repository">
    ```bash theme={null}
    git clone https://github.com/rapidaai/voice-ai.git
    cd voice-ai
    ```
  </Step>

  <Step title="Create data directories">
    ```bash theme={null}
    make setup-local
    ```

    Creates `~/rapida-data/assets/{db,redis,opensearch}` with the correct ownership for Docker volume mounts. The `opensearch` directory is only used when running with the knowledge base profile.

    <Note>
      **macOS users:** `make setup-local` uses `setfacl`, which is a Linux utility. If the command fails, create the directories manually:

      ```bash theme={null}
      mkdir -p ~/rapida-data/assets/opensearch ~/rapida-data/assets/db ~/rapida-data/assets/redis
      sudo chown -R 1000:1000 ~/rapida-data/assets/opensearch
      ```
    </Note>
  </Step>

  <Step title="Configure YAML files">
    Each service reads from a YAML config file in `docker/<service>/`. The defaults work for a local deployment with no external providers. You do not need any API keys to start the platform.

    ```
    docker/web-api/web.yml
    docker/assistant-api/assistant.yml
    docker/integration-api/integration.yml
    docker/endpoint-api/endpoint.yml
    docker/document-api/config.yaml
    ```

    <Warning>
      Before going to production, change `secret: "rpd_pks"` to a strong random value in every service config. All services share the same secret for JWT signing. Generate one with `openssl rand -hex 32`.
    </Warning>
  </Step>

  <Step title="Build all service images">
    ```bash theme={null}
    # Without knowledge base (recommended for most users)
    make build-all

    # With knowledge base (includes document-api and opensearch)
    make build-all-with-knowledge
    ```

    Builds Docker images for all Go services. Initial build takes 5–10 minutes depending on your network.
  </Step>

  <Step title="Start all services">
    ```bash theme={null}
    # Without knowledge base — voice assistants only
    make up-all

    # With knowledge base — includes document-api and opensearch
    make up-all-with-knowledge
    ```

    <Note>
      The default `make up-all` starts all core services (web-api, assistant-api, integration-api, endpoint-api, UI, PostgreSQL, Redis, Nginx). `document-api` and `opensearch` are **optional** and only started with the `with-knowledge` variant. You can always add knowledge base support later by running `make up-all-with-knowledge`.
    </Note>
  </Step>

  <Step title="Verify all services are healthy">
    ```bash theme={null}
    make status
    ```

    All containers should show `Up` or `Up (healthy)`. If any container is in `Exited` state, check its logs:

    ```bash theme={null}
    make logs-all
    ```
  </Step>

  <Step title="Open the dashboard">
    Navigate to **[http://localhost:3000](http://localhost:3000)** in your browser. You should see the Rapida login page.

    The Nginx gateway is accessible at **[http://localhost:8080](http://localhost:8080)**.
  </Step>
</Steps>

***

## Service Endpoints

| Service         | URL                                            | Health Check           | Required                       |
| --------------- | ---------------------------------------------- | ---------------------- | ------------------------------ |
| Dashboard       | [http://localhost:3000](http://localhost:3000) | —                      | Yes                            |
| Nginx Gateway   | [http://localhost:8080](http://localhost:8080) | —                      | Yes                            |
| Web API         | [http://localhost:9001](http://localhost:9001) | `GET /readiness/`      | Yes                            |
| Assistant API   | [http://localhost:9007](http://localhost:9007) | `GET /readiness/`      | Yes                            |
| Integration API | [http://localhost:9004](http://localhost:9004) | `GET /readiness/`      | Yes                            |
| Endpoint API    | [http://localhost:9005](http://localhost:9005) | `GET /readiness/`      | Yes                            |
| Document API    | [http://localhost:9010](http://localhost:9010) | `GET /readiness/`      | Optional (knowledge base only) |
| OpenSearch      | [http://localhost:9200](http://localhost:9200) | `GET /_cluster/health` | Optional (knowledge base only) |

```bash theme={null}
# Verify a specific service
curl http://localhost:9001/readiness/
```

***

## Working with Individual Services

### Start / stop specific services

```bash theme={null}
# Infrastructure only (postgres, redis, opensearch)
make deps

# Individual services
make up-web
make up-assistant
make up-integration
make up-endpoint
make up-document
make up-ui
```

### Logs

```bash theme={null}
make logs-all           # All services
make logs-web           # web-api only
make logs-assistant     # assistant-api only
make logs-integration   # integration-api only
make logs-endpoint      # endpoint-api only
make logs-document      # document-api only
```

### Rebuild after code changes

```bash theme={null}
make rebuild-web        # Rebuild web-api (no cache)
make rebuild-assistant  # Rebuild assistant-api (no cache)
make rebuild-all        # Rebuild all services (no cache)
```

### Shell access

```bash theme={null}
make shell-web          # Shell into web-api container
make shell-assistant    # Shell into assistant-api container
make shell-db           # psql shell → PostgreSQL (rapida_user / web_db)
```

***

## Connecting Your First Provider

The platform runs without any external provider keys. To place a voice call, you need to add at least one LLM, one STT, and one TTS provider credential through the dashboard.

<Steps>
  <Step title="Open the dashboard">
    Navigate to [http://localhost:3000](http://localhost:3000) and create an account.
  </Step>

  <Step title="Create an organization and project">
    Every resource in Rapida is scoped to an organization and project.
  </Step>

  <Step title="Add provider credentials">
    Go to **Settings → Integrations** and add API keys for your LLM (e.g., OpenAI), STT (e.g., Deepgram), and TTS (e.g., ElevenLabs) providers.

    Credentials are encrypted with AES-256-GCM before storage. See [Integration API](/opensource/services/integration-api) for details.
  </Step>

  <Step title="Create an assistant">
    Go to **Assistants → New Assistant** and configure the system prompt, LLM, STT, TTS, and (optionally) a knowledge base.
  </Step>

  <Step title="Test the call">
    Use the built-in call tester in the dashboard or connect via the [rapida-react SDK](https://github.com/rapidaai/rapida-react).
  </Step>
</Steps>

***

## Make Command Reference

| Command                           | Description                                              |
| --------------------------------- | -------------------------------------------------------- |
| `make setup-local`                | Create data directories with correct permissions         |
| `make build-all`                  | Build all Docker images (without knowledge base)         |
| `make build-all-with-knowledge`   | Build all Docker images including document-api           |
| `make rebuild-all`                | Rebuild all images (no cache, without knowledge base)    |
| `make rebuild-all-with-knowledge` | Rebuild all images including document-api (no cache)     |
| `make rebuild-<service>`          | Rebuild a single service (no cache)                      |
| `make up-all`                     | Start all services (without knowledge base)              |
| `make up-all-with-knowledge`      | Start all services including document-api and opensearch |
| `make down-all`                   | Stop all services                                        |
| `make restart-all`                | Restart all services                                     |
| `make deps`                       | Start infrastructure only (postgres, redis)              |
| `make status`                     | Show container status and port mappings                  |
| `make logs-all`                   | Tail all service logs                                    |
| `make logs-<service>`             | Tail logs for a specific service                         |
| `make shell-<service>`            | Open a shell inside a service container                  |
| `make shell-db`                   | Open psql shell in the PostgreSQL container              |
| `make clean`                      | Remove all containers, volumes, and images               |
| `make ps-all`                     | List container status                                    |

***

## Stopping and Resetting

```bash theme={null}
# Stop all services (preserve volumes)
make down-all

# Full reset — removes containers, volumes, and images
make clean
```

<Warning>
  `make clean` deletes all Docker volumes, including the PostgreSQL data directory and (if used) the OpenSearch data directory. All database content and indexed documents will be lost.
</Warning>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Architecture" icon="network" href="/opensource/architecture">
    System topology, service communication, and data flow diagrams.
  </Card>

  <Card title="Configuration Reference" icon="sliders" href="/opensource/configuration">
    Complete environment variable reference for all services.
  </Card>

  <Card title="Services Overview" icon="server" href="/opensource/services">
    Per-service documentation — components, routing, configuration.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/opensource/troubleshooting">
    Common issues and solutions for Docker and local setup.
  </Card>
</CardGroup>