diff --git a/PROXMOX_DEPLOYMENT.md b/PROXMOX_DEPLOYMENT.md new file mode 100644 index 0000000..5fcd0a8 --- /dev/null +++ b/PROXMOX_DEPLOYMENT.md @@ -0,0 +1,292 @@ +# 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 +CHAIN_138_RPC_URL="http://192.168.11.250: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.120:6379` (Cache) +- **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](../../../scripts/deployment/create-dbis-core-containers.sh)