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

# Quickstart

> Get OLIVE up and running in minutes

# Quickstart Guide

This guide will help you set up and run OLIVE locally using Docker Compose.

## Prerequisites

* Docker and Docker Compose installed
* At least 4GB of available memory
* Git to clone the repository

## Setup

### 1. Clone the Repository

```bash theme={null}
git clone https://github.com/EmmanuelKeifala/olive.git
cd olive
```

### 2. Configure Environment

Copy the example environment file and configure your settings:

```bash theme={null}
cp .env.example .env
```

Edit `.env` with your configuration:

```env theme={null}
# Database
DATABASE_URL=postgres://user:password@localhost:5432/olive

# JWT Secret (generate a strong secret)
JWT_SECRET=your-secure-jwt-secret-minimum-32-chars

# OpenAI (for agent-ts)
OPENAI_API_KEY=sk-...

# AWS S3 (for KYC document storage)
AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...
AWS_S3_BUCKET_NAME=olive-kyc-documents
AWS_REGION=us-east-1
```

### 3. Start Services

```bash theme={null}
docker compose up -d --build gateway wallet-core agent
```

### 4. Verify Health

<CodeGroup>
  ```bash Gateway theme={null}
  curl http://localhost:8080/health
  ```

  ```bash Agent theme={null}
  curl http://localhost:8000/health
  ```
</CodeGroup>

Expected response:

```json theme={null}
{
  "service": "gateway",
  "version": "1.0.0",
  "healthy": true,
  "wallet_core": {
    "healthy": true,
    "version": "1.0.0"
  }
}
```

## Your First API Call

### Check Balance

```bash theme={null}
curl -X GET "http://localhost:8080/api/v1/balance/user123" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Create a Payment

```bash theme={null}
curl -X POST "http://localhost:8080/api/v1/payments" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user123",
    "recipient": "merchant456",
    "amount": 5000,
    "currency": "SLE",
    "memo": "Payment for goods"
  }'
```

## Service Ports

| Service     | Port  | Protocol  |
| ----------- | ----- | --------- |
| Gateway     | 8080  | HTTP/REST |
| Agent       | 8000  | HTTP/REST |
| Wallet-Core | 50051 | gRPC      |
| PostgreSQL  | 5432  | TCP       |

## Viewing Logs

```bash theme={null}
# All services
docker compose logs -f

# Specific service
docker compose logs -f gateway
docker compose logs -f wallet-core
docker compose logs -f agent
```

## Stopping Services

```bash theme={null}
docker compose down
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Subscriber Registration" icon="user-plus" href="/guides/subscriber-registration">
    Learn how to register users and complete KYC
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/overview">
    Explore all available endpoints
  </Card>

  <Card title="Agent-TS" icon="robot" href="/agent-ts/overview">
    Set up the WhatsApp conversational agent
  </Card>

  <Card title="Security" icon="shield" href="/reference/security">
    Configure authentication and TLS
  </Card>
</CardGroup>