d-bis/defi-arbitrage
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
6598c93adce58a7e5efec138038314e30e833706
defi-arbitrage/PROXMOX_DEPLOYMENT.md
DBIS Core Team be32cf8d5f Add Proxmox VE deployment documentation 
- Document container architecture (VMID 10150, 10151)
- Integration with DBIS Core API servers
- Network configuration and service setup
- High availability and monitoring
- Troubleshooting guide
2026-01-27 14:51:26 -08:00

293 lines
8.8 KiB
Markdown
Raw Blame History

# 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)
Reference in New Issue View Git Blame Copy Permalink