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

# Deployment

> Production deployment guide for OLIVE

# Deployment Reference

Complete guide to deploying OLIVE in development, staging, and production environments.

## Prerequisites

<CardGroup cols={3}>
  <Card title="Docker" icon="docker">
    Docker 20.10+ and Docker Compose v2
  </Card>

  <Card title="Go" icon="code">
    Go 1.21+ (for local builds)
  </Card>

  <Card title="Node.js" icon="node-js">
    Node.js 18+ (for Agent-TS)
  </Card>
</CardGroup>

***

## Local Development

### Docker Compose (Recommended)

The fastest way to get OLIVE running locally:

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

# Copy environment file
cp .env.example .env

# Start all services
docker compose up -d --build gateway wallet-core agent
```

### Verify Services

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

  ```bash Agent Health theme={null}
  curl http://localhost:8000/health
  ```

  ```bash View Logs theme={null}
  docker compose logs -f gateway wallet-core agent
  ```
</CodeGroup>

### Manual Setup

For development without Docker:

<Steps>
  <Step title="Start Wallet-Core">
    ```bash theme={null}
    cd wallet-core
    go run cmd/server/main.go -config config.yaml
    ```
  </Step>

  <Step title="Start Gateway">
    ```bash theme={null}
    cd gateway
    go run cmd/server/main.go -config config.yaml
    ```
  </Step>

  <Step title="Start Agent-TS">
    ```bash theme={null}
    cd agent-ts
    npm install
    npm run dev
    ```
  </Step>
</Steps>

***

## Production Deployment

### Kubernetes

<Steps>
  <Step title="Create Namespace">
    ```bash theme={null}
    kubectl apply -f deployment/kubernetes/namespace.yaml
    ```
  </Step>

  <Step title="Create TLS Secrets">
    ```bash theme={null}
    ./scripts/generate-certs.sh

    kubectl create secret generic wallet-core-certs \
      --from-file=certs/wallet-core.crt \
      --from-file=certs/wallet-core.key \
      --from-file=certs/ca.crt \
      -n olive
    ```
  </Step>

  <Step title="Create ConfigMaps">
    ```bash theme={null}
    kubectl create configmap wallet-core-config \
      --from-file=wallet-core/config.production.yaml \
      -n olive

    kubectl create configmap gateway-config \
      --from-file=gateway/config.production.yaml \
      -n olive
    ```
  </Step>

  <Step title="Deploy Services">
    ```bash theme={null}
    kubectl apply -f deployment/kubernetes/
    ```
  </Step>

  <Step title="Verify Deployment">
    ```bash theme={null}
    kubectl get pods -n olive
    kubectl get services -n olive
    ```
  </Step>
</Steps>

### Render (Cloud)

Deploy using the included `render.yaml`:

```bash theme={null}
# Push to GitHub and connect to Render
# render.yaml configures services automatically
```

***

## Environment Variables

### Required Variables

| Variable          | Service  | Description                    |
| ----------------- | -------- | ------------------------------ |
| `DATABASE_URL`    | All      | PostgreSQL connection string   |
| `JWT_SECRET`      | Gateway  | JWT signing secret (32+ chars) |
| `OPENAI_API_KEY`  | Agent-TS | OpenAI API key                 |
| `GATEWAY_API_KEY` | Agent-TS | Internal service key           |

### Optional Variables

| Variable              | Service  | Default           | Description              |
| --------------------- | -------- | ----------------- | ------------------------ |
| `PORT`                | All      | 8080/8000/50051   | Service port             |
| `LOG_LEVEL`           | All      | `info`            | Logging level            |
| `WALLET_CORE_ADDRESS` | Gateway  | `localhost:50051` | Wallet-Core gRPC address |
| `AWS_S3_BUCKET_NAME`  | Agent-TS | -                 | KYC document storage     |

<Warning>
  Never commit secrets to version control. Use environment variables or a secrets manager.
</Warning>

***

## TLS/mTLS Configuration

### Enable TLS on Wallet-Core

```yaml theme={null}
# wallet-core/config.production.yaml
tls:
  enabled: true
  cert_file: /certs/wallet-core.crt
  key_file: /certs/wallet-core.key
  ca_file: /certs/ca.crt
```

### Enable TLS on Gateway

```yaml theme={null}
# gateway/config.production.yaml
tls:
  enabled: true
  cert_file: /certs/gateway.crt
  key_file: /certs/gateway.key
  
wallet_core:
  address: wallet-core:50051
  use_tls: true
  tls_cert_path: /certs/ca.crt
```

### Generate Certificates

```bash theme={null}
# Use the provided script
./scripts/generate-certs.sh

# Or use your own CA
openssl req -x509 -newkey rsa:4096 \
  -keyout ca.key -out ca.crt \
  -days 365 -nodes
```

***

## Health Checks

| Service     | Endpoint      | Protocol |
| ----------- | ------------- | -------- |
| Gateway     | `GET /health` | HTTP     |
| Agent-TS    | `GET /health` | HTTP     |
| Wallet-Core | gRPC Health   | gRPC     |

### Health Check Response

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

***

## Scaling

### Horizontal Scaling

```bash theme={null}
# Scale Gateway (stateless - unlimited)
kubectl scale deployment gateway --replicas=5 -n olive

# Scale Agent-TS (stateless - unlimited)
kubectl scale deployment agent --replicas=3 -n olive
```

### Resource Limits

```yaml theme={null}
# Kubernetes deployment
resources:
  requests:
    memory: "512Mi"
    cpu: "500m"
  limits:
    memory: "1Gi"
    cpu: "1000m"
```

### Database Scaling

* Use connection pooling (PgBouncer)
* Add read replicas for queries
* Consider sharding for high write volume

***

## Monitoring

### Prometheus Metrics

All services expose Prometheus-compatible metrics:

| Service     | Endpoint                          |
| ----------- | --------------------------------- |
| Gateway     | `http://gateway:9090/metrics`     |
| Wallet-Core | `http://wallet-core:9091/metrics` |

### Key Metrics

* `http_requests_total` - Request count by status
* `http_request_duration_seconds` - Latency histogram
* `grpc_server_handled_total` - gRPC call count
* `wallet_transactions_total` - Transaction count

***

## Backup and Recovery

### Database Backup

```bash theme={null}
# PostgreSQL backup
pg_dump -h localhost -U olive -d olive_db > backup.sql

# Restore
psql -h localhost -U olive -d olive_db < backup.sql
```

### Backup Schedule

| Type             | Frequency  | Retention |
| ---------------- | ---------- | --------- |
| Full backup      | Daily      | 30 days   |
| Transaction logs | Continuous | 7 days    |
| Point-in-time    | Enabled    | 24 hours  |

***

## Security Checklist

<Warning>
  Complete this checklist before production deployment.
</Warning>

* [ ] TLS/mTLS enabled on all services
* [ ] Strong JWT secrets configured (32+ chars)
* [ ] Rate limiting enabled and tuned
* [ ] Database encrypted (at-rest and in-transit)
* [ ] Audit logging enabled
* [ ] Firewall rules configured
* [ ] Network policies in Kubernetes
* [ ] Regular backups configured
* [ ] Monitoring and alerting active

***

## Related

<CardGroup cols={2}>
  <Card title="Security Reference" icon="shield" href="/reference/security">
    Security configuration details
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/reference/troubleshooting">
    Common issues and solutions
  </Card>
</CardGroup>