solace-bg-dubai/deployment/proxmox/README.md

# Proxmox VE Deployment Guide

This guide explains how to deploy the Solace Treasury DApp on Proxmox VE using LXC containers.

## Overview

The DApp is deployed across multiple LXC containers:
- **Frontend** (VMID 3000): Next.js application
- **Backend** (VMID 3001): API server
- **Database** (VMID 3002): PostgreSQL database
- **Indexer** (VMID 3003): Blockchain event indexer

## Prerequisites

1. **Proxmox VE Host**
   - LXC support enabled
   - Sufficient resources (minimum 10GB RAM, 4 CPU cores, 120GB disk)
   - Network access to Chain 138 RPC nodes

2. **OS Template**
   - Ubuntu 22.04 LTS template downloaded
   - Available in Proxmox storage

3. **Network Configuration**
   - VLAN 103 (Services network) configured
   - IP addresses available: 192.168.11.60-63
   - Access to Chain 138 RPC nodes (192.168.11.250-252)

## Quick Start

### 1. Configure Deployment

Edit `config/dapp.conf` to match your Proxmox environment:

```bash
cd deployment/proxmox
nano config/dapp.conf
```

Key settings to configure:
- `PROXMOX_STORAGE`: Storage pool name (default: local-lvm)
- `PROXMOX_BRIDGE`: Network bridge (default: vmbr0)
- `DATABASE_PASSWORD`: PostgreSQL password
- IP addresses if different from defaults

### 2. Deploy All Components

```bash
sudo ./deploy-dapp.sh
```

This will deploy all components in the correct order:
1. Database (must be first)
2. Backend (depends on database)
3. Indexer (depends on database and RPC)
4. Frontend (depends on backend)

### 3. Deploy Individual Components

If you prefer to deploy components individually:

```bash
# Database first
sudo ./deploy-database.sh

# Then backend
sudo ./deploy-backend.sh

# Then indexer
sudo ./deploy-indexer.sh

# Finally frontend
sudo ./deploy-frontend.sh
```

## Configuration

### Environment Variables

After deployment, you need to configure environment variables for each service.

#### Frontend Configuration

Create `frontend/.env.production`:

```env
NEXT_PUBLIC_CHAIN138_RPC_URL=http://192.168.11.250:8545
NEXT_PUBLIC_CHAIN138_WS_URL=ws://192.168.11.250:8546
NEXT_PUBLIC_CHAIN_ID=138
NEXT_PUBLIC_TREASURY_WALLET_ADDRESS=<deployed_address>
NEXT_PUBLIC_SUB_ACCOUNT_FACTORY_ADDRESS=<deployed_address>
NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID=<your_project_id>
NEXT_PUBLIC_API_URL=http://192.168.11.61:3001
```

Copy to container:
```bash
pct push 3000 frontend/.env.production /opt/solace-frontend/.env.production
```

#### Backend Configuration

Create `backend/.env`:

```env
DATABASE_URL=postgresql://solace_user:password@192.168.11.62:5432/solace_treasury
RPC_URL=http://192.168.11.250:8545
CHAIN_ID=138
CONTRACT_ADDRESS=<deployed_address>
PORT=3001
NODE_ENV=production
```

Copy to container:
```bash
pct push 3001 backend/.env /opt/solace-backend/.env
```

#### Indexer Configuration

Create `backend/.env.indexer`:

```env
DATABASE_URL=postgresql://solace_user:password@192.168.11.62:5432/solace_treasury
RPC_URL=http://192.168.11.250:8545
CHAIN_ID=138
CONTRACT_ADDRESS=<deployed_address>
START_BLOCK=0
```

Copy to container:
```bash
pct push 3003 backend/.env.indexer /opt/solace-indexer/.env.indexer
```

## Post-Deployment Steps

### 1. Deploy Contracts

Deploy contracts to Chain 138:

```bash
cd contracts
pnpm run deploy:chain138
```

This will create `contracts/deployments/chain138.json` with deployed addresses.

### 2. Update Environment Files

Update the environment files with the deployed contract addresses from the deployment JSON file.

### 3. Run Database Migrations

```bash
pct exec 3001 -- bash -c 'cd /opt/solace-backend && pnpm run db:migrate'
```

### 4. Start Services

Start all services:

```bash
pct exec 3001 -- systemctl start solace-backend
pct exec 3003 -- systemctl start solace-indexer
pct exec 3000 -- systemctl start solace-frontend
```

### 5. Enable Auto-Start

Enable services to start on boot:

```bash
pct exec 3001 -- systemctl enable solace-backend
pct exec 3003 -- systemctl enable solace-indexer
pct exec 3000 -- systemctl enable solace-frontend
```

## Service Management

### Check Service Status

```bash
pct exec 3000 -- systemctl status solace-frontend
pct exec 3001 -- systemctl status solace-backend
pct exec 3003 -- systemctl status solace-indexer
```

### View Logs

```bash
# Frontend logs
pct exec 3000 -- journalctl -u solace-frontend -f

# Backend logs
pct exec 3001 -- journalctl -u solace-backend -f

# Indexer logs
pct exec 3003 -- journalctl -u solace-indexer -f
```

### Restart Services

```bash
pct exec 3000 -- systemctl restart solace-frontend
pct exec 3001 -- systemctl restart solace-backend
pct exec 3003 -- systemctl restart solace-indexer
```

## Network Access

### Internal Access

Services are accessible on the internal network:
- Frontend: http://192.168.11.60:3000
- Backend API: http://192.168.11.61:3001
- Database: 192.168.11.62:5432 (internal only)

### Public Access

For public access, set up Nginx reverse proxy:

1. Install Nginx on a separate container or the frontend container
2. Use the template: `templates/nginx.conf`
3. Configure SSL/TLS certificates
4. Update firewall rules to allow ports 80 and 443

## Troubleshooting

### Container Not Starting

```bash
# Check container status
pct status 3000

# View container logs
pct logs 3000

# Check container configuration
pct config 3000
```

### Service Not Running

```bash
# Check service status
pct exec 3000 -- systemctl status solace-frontend

# Check service logs
pct exec 3000 -- journalctl -u solace-frontend -n 50

# Check if port is listening
pct exec 3000 -- netstat -tlnp | grep 3000
```

### Database Connection Issues

```bash
# Test database connection from backend container
pct exec 3001 -- psql -h 192.168.11.62 -U solace_user -d solace_treasury

# Check PostgreSQL status
pct exec 3002 -- systemctl status postgresql

# View PostgreSQL logs
pct exec 3002 -- journalctl -u postgresql -f
```

### RPC Connection Issues

```bash
# Test RPC connection from backend container
pct exec 3001 -- curl -X POST -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' \
  http://192.168.11.250:8545
```

## Backup and Maintenance

### Database Backup

```bash
# Create backup
pct exec 3002 -- pg_dump -U solace_user solace_treasury > backup_$(date +%Y%m%d).sql

# Restore backup
pct exec 3002 -- psql -U solace_user solace_treasury < backup_20240101.sql
```

### Container Backup

Use Proxmox backup functionality or:

```bash
# Stop container
pct stop 3000

# Create backup (using vzdump or Proxmox backup)
vzdump 3000 --storage local

# Start container
pct start 3000
```

## Security Considerations

1. **Firewall Rules**: Restrict access to only necessary ports
2. **SSL/TLS**: Use HTTPS for all public-facing services
3. **Database Security**: Use strong passwords and restrict network access
4. **Environment Variables**: Never commit .env files to version control
5. **Container Isolation**: Use unprivileged containers when possible

## Support

For issues or questions:
1. Check service logs
2. Review container status
3. Verify network connectivity
4. Check environment variable configuration