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
This commit is contained in:
DBIS Core Team
292
PROXMOX_DEPLOYMENT.md
Normal file
292
PROXMOX_DEPLOYMENT.md
Normal file
@@ -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)
|
||||
Reference in New Issue
Block a user