dbis_core/DEPLOYMENT_PLAN.md

# DBIS Core Banking System - Proxmox Deployment Plan

## Overview

This document outlines the VMID allocation and LXC container specifications for deploying the DBIS Core Banking System on Proxmox VE infrastructure.

## System Architecture

The DBIS Core Banking System consists of:

1. **Backend API Server** - Node.js/Express application (port 3000)
2. **Frontend Admin Console** - React/Vite application (port 3001)
3. **PostgreSQL Database** - Primary database for Prisma ORM
4. **Redis Cache** (Optional) - For caching and session management
5. **HSM Integration** (Optional) - Hardware Security Module for cryptographic operations

## VMID Allocation

Based on the existing Proxmox VMID allocation strategy, DBIS Core services will use the **Sovereign Cloud Band** range (10000-13999), which is specifically designated for DBIS/SMOM/ICCC services.

### VMID Ranges

| Service Category | VMID Range | Count | Description |
|-----------------|------------|-------|-------------|
| **DBIS Core Services** | 10000-10099 | 100 | Primary DBIS Core Banking System services |
| **DBIS Core Database** | 10100-10119 | 20 | PostgreSQL databases (primary + replicas) |
| **DBIS Core Cache** | 10120-10129 | 10 | Redis cache instances |
| **DBIS Core Frontend** | 10130-10149 | 20 | Frontend admin console instances |
| **DBIS Core API** | 10150-10199 | 50 | Backend API server instances |
| **DBIS Core Expansion** | 10200-13999 | 3,800 | Reserved for future expansion |

### Initial Deployment VMIDs

| Service | VMID | Hostname | IP Address | Description |
|---------|------|----------|------------|-------------|
| **PostgreSQL Primary** | 10100 | dbis-postgres-primary | 192.168.11.105 | Primary database server |
| **PostgreSQL Replica 1** | 10101 | dbis-postgres-replica-1 | 192.168.11.106 | Database replica (optional) |
| **Redis Cache** | 10120 | dbis-redis | 192.168.11.120 | Redis cache server |
| **Backend API (Primary)** | 10150 | dbis-api-primary | 192.168.11.155 | Main API server |
| **Backend API (Secondary)** | 10151 | dbis-api-secondary | 192.168.11.156 | Secondary API server (HA) |
| **Frontend Admin Console** | 10130 | dbis-frontend | 192.168.11.130 | Admin console web interface |

## LXC Container Specifications

### PostgreSQL Database Containers

**Primary Database (VMID 10100)**
- **Memory**: 8 GB (8192 MB)
- **CPU Cores**: 4
- **Disk**: 200 GB
- **OS Template**: `ubuntu-22.04-standard`
- **Network**: Bridge `vmbr0`
- **IP Address**: 192.168.11.105
- **Hostname**: `dbis-postgres-primary`
- **Unprivileged**: Yes
- **Features**: `nesting=1`

**Replica Database (VMID 10101)** - Optional
- **Memory**: 8 GB (8192 MB)
- **CPU Cores**: 4
- **Disk**: 200 GB
- **OS Template**: `ubuntu-22.04-standard`
- **Network**: Bridge `vmbr0`
- **IP Address**: 192.168.11.106
- **Hostname**: `dbis-postgres-replica-1`
- **Unprivileged**: Yes
- **Features**: `nesting=1`

### Redis Cache Container

**Redis Server (VMID 10120)**
- **Memory**: 4 GB (4096 MB)
- **CPU Cores**: 2
- **Disk**: 50 GB
- **OS Template**: `ubuntu-22.04-standard`
- **Network**: Bridge `vmbr0`
- **IP Address**: 192.168.11.120
- **Hostname**: `dbis-redis`
- **Unprivileged**: Yes
- **Features**: `nesting=1`

### Backend API Containers

**Primary API Server (VMID 10150)**
- **Memory**: 8 GB (8192 MB)
- **CPU Cores**: 4
- **Disk**: 100 GB
- **OS Template**: `ubuntu-22.04-standard`
- **Network**: Bridge `vmbr0`
- **IP Address**: 192.168.11.155
- **Hostname**: `dbis-api-primary`
- **Unprivileged**: Yes
- **Features**: `nesting=1`

**Secondary API Server (VMID 10151)** - High Availability
- **Memory**: 8 GB (8192 MB)
- **CPU Cores**: 4
- **Disk**: 100 GB
- **OS Template**: `ubuntu-22.04-standard`
- **Network**: Bridge `vmbr0`
- **IP Address**: 192.168.11.156
- **Hostname**: `dbis-api-secondary`
- **Unprivileged**: Yes
- **Features**: `nesting=1`

### Frontend Admin Console Container

**Frontend Server (VMID 10130)**
- **Memory**: 4 GB (4096 MB)
- **CPU Cores**: 2
- **Disk**: 50 GB
- **OS Template**: `ubuntu-22.04-standard`
- **Network**: Bridge `vmbr0`
- **IP Address**: 192.168.11.130
- **Hostname**: `dbis-frontend`
- **Unprivileged**: Yes
- **Features**: `nesting=1`

## Network Configuration

### IP Address Allocation

All containers will use the `vmbr0` bridge with static IP addresses in the range `192.168.11.100-192.168.11.199`:

- **Database Range**: 192.168.11.105-119 (adjusted to avoid conflicts with blockchain validators at .100-104)
- **Cache Range**: 192.168.11.120-129
- **Frontend Range**: 192.168.11.130-149
- **API Range**: 192.168.11.155-199 (adjusted to avoid conflicts with blockchain sentries at .150-154)

### Port Mappings

| Service | Container Port | Protocol | Description |
|---------|---------------|----------|-------------|
| PostgreSQL | 5432 | TCP | Database connection |
| Redis | 6379 | TCP | Cache connection |
| Backend API | 3000 | TCP | API server |
| Frontend | 80, 443 | TCP | Web interface (HTTP/HTTPS) |

## Service Dependencies

```
Frontend (10130)
  └── Backend API (10150, 10151)

Backend API (10150, 10151)
  ├── PostgreSQL (10100, 10101)
  ├── Redis (10120)
  └── HSM (if available)

PostgreSQL (10100)
  └── PostgreSQL Replica (10101) [optional]
```

## Deployment Order

1. **PostgreSQL Primary** (10100) - Foundation service
2. **PostgreSQL Replica** (10101) - Optional, for HA
3. **Redis Cache** (10120) - Caching layer
4. **Backend API Primary** (10150) - Core application
5. **Backend API Secondary** (10151) - High availability
6. **Frontend Admin Console** (10130) - User interface

## Resource Requirements Summary

### Minimum Deployment (Single Instance)
- **Total Memory**: 20 GB (PostgreSQL 8GB + API 8GB + Frontend 4GB)
- **Total CPU Cores**: 10 (PostgreSQL 4 + API 4 + Frontend 2)
- **Total Disk**: 350 GB (PostgreSQL 200GB + API 100GB + Frontend 50GB)

### Recommended Deployment (High Availability)
- **Total Memory**: 32 GB (PostgreSQL 8GB + Replica 8GB + Redis 4GB + API 8GB + API Secondary 8GB + Frontend 4GB)
- **Total CPU Cores**: 18 (PostgreSQL 4 + Replica 4 + Redis 2 + API 4 + API Secondary 4 + Frontend 2)
- **Total Disk**: 500 GB (PostgreSQL 200GB + Replica 200GB + Redis 50GB + API 100GB + API Secondary 100GB + Frontend 50GB)

## Environment Variables

Each container will require specific environment variables. See `dbis_core/.env.example` for the complete list.

### Critical Environment Variables

**Backend API Containers:**
- `DATABASE_URL` - PostgreSQL connection string
- `JWT_SECRET` - JWT signing secret (min 32 characters)
- `ALLOWED_ORIGINS` - CORS allowed origins
- `NODE_ENV=production`
- `LOG_LEVEL` - Logging level (info/warn/error)
- `HSM_ENABLED` - HSM integration flag

**Frontend Container:**
- `VITE_API_BASE_URL` - Backend API URL
- `VITE_APP_NAME` - Application name
- `VITE_REAL_TIME_UPDATE_INTERVAL` - Update interval in ms

## Security Considerations

1. **Unprivileged Containers**: All containers use unprivileged mode
2. **Network Isolation**: Consider VLANs for production
3. **HSM Integration**: Required for production cryptographic operations
4. **SSL/TLS**: Frontend should use HTTPS (port 443)
5. **Firewall Rules**: Restrict database and Redis ports to internal network only
6. **Backup Strategy**: Daily database backups recommended

## Monitoring & Logging

- **Health Checks**: All services expose `/health` endpoints
- **Logging**: Winston logger configured for structured logging
- **Metrics**: Prometheus metrics collection (if monitoring stack available)
- **Database Monitoring**: PostgreSQL metrics and query performance

## Next Steps

1. Create Proxmox configuration file for DBIS Core services
2. Create deployment scripts for each service type
3. Set up database initialization and migration scripts
4. Configure load balancer for API servers (if needed)
5. Set up SSL certificates for frontend
6. Configure backup automation for PostgreSQL

## References

- [DBIS Core README](../dbis_core/README.md)
- [DBIS Core Deployment Guide](../dbis_core/docs/deployment.md)
- [Proxmox Configuration](../../docs/03-deployment/DEPLOYMENT_READINESS.md)