defi-arbitrage/PROXMOX_DEPLOYMENT.md

# Proxmox VE Deployment Guide - Deal Orchestration Tool

## Overview

This document describes how the Deal Orchestration Tool (arbitrage module) is deployed and runs within the Proxmox VE infrastructure as part of the DBIS Core Banking System.

## Deployment Architecture

### Container Assignment

The arbitrage orchestration service runs within the **DBIS Core API containers**:

| Service | VMID | Hostname | IP Address | Role |
|---------|------|----------|------------|------|
| **Primary API** | 10150 | dbis-api-primary | 192.168.11.150 | Main API + Arbitrage Orchestrator |
| **Secondary API** | 10151 | dbis-api-secondary | 192.168.11.156 | HA API + Arbitrage Orchestrator |

### Container Specifications

- **Memory**: 8 GB (8192 MB)
- **CPU Cores**: 4
- **Disk**: 100 GB
- **OS Template**: `ubuntu-22.04-standard`
- **Network**: Bridge `vmbr0`
- **Unprivileged**: Yes
- **Features**: `nesting=1`, `keyctl=1`

## Integration with DBIS Core

### Service Architecture

```
┌─────────────────────────────────────────┐
│  Proxmox VE Host (192.168.11.10)      │
│                                         │
│  ┌───────────────────────────────────┐ │
│  │ LXC Container: dbis-api-primary  │ │
│  │ VMID: 10150                       │ │
│  │ IP: 192.168.11.150                │ │
│  │                                    │ │
│  │  ┌──────────────────────────────┐  │ │
│  │  │ DBIS Core API Server        │  │ │
│  │  │ (Node.js/Express)           │  │ │
│  │  │ Port: 3000                  │  │ │
│  │  └──────────────────────────────┘  │ │
│  │                                    │ │
│  │  ┌──────────────────────────────┐  │ │
│  │  │ Deal Orchestrator Service   │  │ │
│  │  │ (Arbitrage Module)           │  │ │
│  │  │ - Step Execution            │  │ │
│  │  │ - Risk Control              │  │ │
│  │  │ - Redemption Testing        │  │ │
│  │  └──────────────────────────────┘  │ │
│  │                                    │ │
│  │  ┌──────────────────────────────┐  │ │
│  │  │ Database Connection         │  │ │
│  │  │ (Prisma ORM)                │  │ │
│  │  │ → PostgreSQL (VMID 10100)   │  │ │
│  │  └──────────────────────────────┘  │ │
│  │                                    │ │
│  │  ┌──────────────────────────────┐  │ │
│  │  │ Blockchain RPC Client        │  │ │
│  │  │ → ChainID 138 RPC Nodes     │  │ │
│  │  │ (VMID 2500-2502)            │  │ │
│  │  └──────────────────────────────┘  │ │
│  └───────────────────────────────────┘ │
│                                         │
│  ┌───────────────────────────────────┐ │
│  │ LXC Container: dbis-api-secondary│ │
│  │ VMID: 10151                       │ │
│  │ IP: 192.168.11.156                │ │
│  │ (Same structure as primary)       │ │
│  └───────────────────────────────────┘ │
└─────────────────────────────────────────┘
```

## Deployment Steps

### 1. Prerequisites

- Proxmox VE host with LXC support
- DBIS Core containers already deployed (see [DEPLOYMENT_PLAN.md](../../../../DEPLOYMENT_PLAN.md))
- PostgreSQL database running (VMID 10100)
- ChainID 138 RPC nodes accessible (VMID 2500-2502)

### 2. Install Dependencies

SSH into the API container and install Node.js dependencies:

```bash
# SSH to Proxmox host
ssh root@192.168.11.10

# Enter API container
pct enter 10150

# Navigate to project
cd /opt/dbis-core

# Install dependencies (if not already done)
pnpm install

# Build the project
pnpm build
```

### 3. Configure Environment

Set environment variables in the container:

```bash
# In container 10150
nano /opt/dbis-core/.env
```

Required variables:
```bash
# Database
DATABASE_URL="postgresql://user:pass@192.168.11.100:5432/dbis_core"

# ChainID 138 RPC (admin/deployment: RPC_CORE_1)
CHAIN_138_RPC_URL="http://192.168.11.211:8545"
CHAIN_138_RPC_URL_BACKUP="http://192.168.11.251:8545"

# Risk Parameters (optional, defaults in config.ts)
MAX_LTV=0.30
MAX_USDTZ_EXPOSURE=0.25
USDTZ_DISCOUNT_RATE=0.40

# Logging
LOG_LEVEL="info"
```

### 4. Run as Service

Create a systemd service for the arbitrage orchestrator:

```bash
# In container 10150
cat > /etc/systemd/system/dbis-arbitrage.service << 'EOF'
[Unit]
Description=DBIS Deal Orchestration Service
After=network.target postgresql.service

[Service]
Type=simple
User=dbis
WorkingDirectory=/opt/dbis-core
Environment=NODE_ENV=production
ExecStart=/usr/bin/node dist/src/core/defi/arbitrage/cli.js execute \
  --totalEthValue 10000000 \
  --participantBankId BANK001 \
  --moduleId MODULE001
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

# Enable and start
systemctl enable dbis-arbitrage
systemctl start dbis-arbitrage
```

### 5. Integration with API Server

The arbitrage service can also be called via the DBIS Core API:

```typescript
// In your API route handler
import { dealOrchestratorService } from '@/core/defi/arbitrage';

app.post('/api/deals/execute', async (req, res) => {
  const result = await dealOrchestratorService.executeDeal({
    totalEthValue: req.body.totalEthValue,
    participantBankId: req.body.participantBankId,
    moduleId: req.body.moduleId,
  });
  
  res.json(result);
});
```

## Network Configuration

### Internal Network (Container-to-Container)

- **Database**: `192.168.11.100:5432` (PostgreSQL)
- **Redis**: `192.168.11.125:6379` (Cache, VMID 10120)
- **RPC Nodes**: `192.168.11.250-252:8545` (ChainID 138)

### External Network (Blockchain)

- **ChainID 138**: Public blockchain network
- **Smart Contracts**: Deployed on ChainID 138
- **RPC Endpoints**: Accessible via internal RPC nodes

## Monitoring

### Logs

```bash
# View service logs
journalctl -u dbis-arbitrage -f

# View application logs
tail -f /opt/dbis-core/logs/arbitrage.log
```

### Health Checks

The service exposes health endpoints (if integrated with API):

```bash
# Check service status
curl http://192.168.11.150:3000/api/health/arbitrage

# Check deal status
curl http://192.168.11.150:3000/api/deals/{dealId}/status
```

## High Availability

### Primary/Secondary Setup

- **Primary (10150)**: Active arbitrage execution
- **Secondary (10151)**: Standby for failover
- **Load Balancer**: Routes requests between containers

### Failover

If primary container fails:
1. Load balancer detects failure
2. Routes traffic to secondary (10151)
3. Secondary takes over deal execution
4. Database state is shared (PostgreSQL replication)

## Security Considerations

### Container Isolation

- **Unprivileged containers**: Reduced security risk
- **Network isolation**: Containers on private bridge
- **Resource limits**: CPU and memory caps enforced

### Key Management

- **Private keys**: Stored in secure key management service
- **API credentials**: Environment variables (not in code)
- **Database credentials**: Rotated regularly

## Troubleshooting

### Container Access

```bash
# SSH to Proxmox host
ssh root@192.168.11.10

# Enter container
pct enter 10150

# Check service status
systemctl status dbis-arbitrage

# View logs
journalctl -u dbis-arbitrage -n 100
```

### Common Issues

1. **Database Connection Failed**
   - Verify PostgreSQL container (10100) is running
   - Check network connectivity: `ping 192.168.11.100`
   - Verify DATABASE_URL in .env

2. **RPC Connection Failed**
   - Verify RPC nodes (2500-2502) are running
   - Check RPC endpoint URLs
   - Test: `curl http://192.168.11.250:8545`

3. **Service Won't Start**
   - Check logs: `journalctl -u dbis-arbitrage`
   - Verify dependencies: `pnpm install`
   - Check file permissions

## References

- [DBIS Core Deployment Plan](../../../../DEPLOYMENT_PLAN.md)
- [Arbitrage Module README](./README_SUBMODULE.md)
- [Proxmox Container Creation Script](../../../../DEPLOYMENT_PLAN.md)