> ## 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 hosted Deployment

> Deploy the Rapida Voice AI Platform on infrastructure your team or clients control

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

<Tip>
  **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.
</Tip>

***

## Quickstart

### Requirements

* [Docker Desktop](https://www.docker.com/products/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

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

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

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

      ```bash theme={null}
      mkdir -p ~/rapida-data/assets/{db,redis,opensearch}
      ```
    </Note>
  </Step>

  <Step title="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](/opensource/configuration) for a full reference of all variables.
  </Step>

  <Step title="Build images">
    <Tabs>
      <Tab title="Voice Only (recommended)">
        ```bash theme={null}
        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).
      </Tab>

      <Tab title="With Knowledge Base">
        ```bash theme={null}
        make build-all-with-knowledge
        ```

        Builds everything above **plus** `document-api` (Python image). Requires 8–16 GB RAM.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Start Rapida">
    <Tabs>
      <Tab title="Voice Only (recommended)">
        ```bash theme={null}
        make up-all
        ```

        Starts: `postgres`, `redis`, `web-api`, `assistant-api`, `integration-api`, `endpoint-api`, `ui`, `nginx`.
      </Tab>

      <Tab title="With Knowledge Base">
        ```bash theme={null}
        make up-all-with-knowledge
        ```

        Starts everything above **plus** `opensearch` and `document-api`.
      </Tab>
    </Tabs>
  </Step>

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

    Check container status with:

    ```bash theme={null}
    make status
    ```
  </Step>
</Steps>

***

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

```bash theme={null}
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:

```bash theme={null}
make up-all-with-knowledge
```

***

## Next Steps

* [Installation guide](/opensource/installation) — detailed Docker and manual setup
* [Overview](/opensource/overview) — architecture and service descriptions
* [Configuration](/opensource/configuration) — all environment variable references