# 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.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](../../../../DEPLOYMENT_PLAN.md)