smom-dbis-138/services/token-aggregation/PROXMOX_DEPLOYMENT.md

# Proxmox Deployment Guide

## Overview

This guide explains how to deploy the Token Aggregation Service with Control Panel to a Proxmox VM.

## Prerequisites

1. Proxmox VE host with LXC support
2. Ubuntu 22.04 template available
3. Network access to database
4. Root access on Proxmox host

## Quick Deployment

```bash
cd smom-dbis-138/services/token-aggregation
./scripts/deploy-to-proxmox.sh
```

## Manual Deployment Steps

### 1. Create LXC Container

```bash
VMID=3600
pct create $VMID local:vztmpl/ubuntu-22.04-standard_22.04-1_amd64.tar.zst \
  --hostname token-aggregation \
  --memory 4096 \
  --cores 2 \
  --rootfs local-lvm:40 \
  --net0 bridge=vmbr0,name=eth0,ip=dhcp \
  --unprivileged 1 \
  --features nesting=1,keyctl=1
```

### 2. Start Container

```bash
pct start $VMID
```

### 3. Install Dependencies

```bash
pct exec $VMID -- bash -c "apt-get update && apt-get install -y curl wget git build-essential postgresql-client nginx"
pct exec $VMID -- bash -c "curl -fsSL https://deb.nodesource.com/setup_20.x | bash - && apt-get install -y nodejs"
```

### 4. Deploy Service

```bash
# Copy service files
pct push $VMID /path/to/token-aggregation /opt/token-aggregation --recursive

# Install and build
pct exec $VMID -- bash -c "cd /opt/token-aggregation && npm install && npm run build"
pct exec $VMID -- bash -c "cd /opt/token-aggregation/frontend && npm install && npm run build"
```

### 5. Configure Services

```bash
# Create systemd service (see deploy script for full config)
pct exec $VMID -- systemctl enable token-aggregation
pct exec $VMID -- systemctl start token-aggregation

# Configure nginx (see deploy script for full config)
pct exec $VMID -- systemctl restart nginx
```

## Configuration

### Environment Variables

Edit `/opt/token-aggregation/.env` in the container:

```bash
pct exec $VMID -- nano /opt/token-aggregation/.env
```

Required variables:
- `DATABASE_URL`
- `CHAIN_138_RPC_URL` (`http://192.168.11.221:8545` for LAN/explorer deployments; not the operator core RPC `http://192.168.11.211:8545`)
- `CHAIN_651940_RPC_URL`

### Database Migration

Run the migration in your database:

```bash
# From your database host
psql $DATABASE_URL -f explorer-monorepo/backend/database/migrations/0011_token_aggregation_schema.up.sql
psql $DATABASE_URL -f explorer-monorepo/backend/database/migrations/0012_admin_config_schema.up.sql
```

### Create Admin User

```bash
pct exec $VMID -- bash -c "cd /opt/token-aggregation && ./scripts/create-admin-user.sh"
```

## Access

After deployment:

- **Control Panel**: `http://<container-ip>`
- **API**: `http://<container-ip>/api/v1`
- **Health Check**: `http://<container-ip>/health`

## Service Management

```bash
# Start service
pct exec $VMID -- systemctl start token-aggregation

# Stop service
pct exec $VMID -- systemctl stop token-aggregation

# View logs
pct exec $VMID -- journalctl -u token-aggregation -f

# Restart service
pct exec $VMID -- systemctl restart token-aggregation
```

## Network Configuration

The service runs on:
- **Port 3000**: API server (internal)
- **Port 80**: Nginx (serves frontend, proxies API)

To expose externally, configure Proxmox firewall or reverse proxy.

## Troubleshooting

### Service Not Starting

```bash
# Check logs
pct exec $VMID -- journalctl -u token-aggregation -n 50

# Check database connection
pct exec $VMID -- bash -c "cd /opt/token-aggregation && node -e \"require('dotenv').config(); const { Pool } = require('pg'); const pool = new Pool({ connectionString: process.env.DATABASE_URL }); pool.query('SELECT 1').then(() => console.log('DB OK')).catch(e => console.error(e));\""
```

### Frontend Not Loading

```bash
# Check nginx status
pct exec $VMID -- systemctl status nginx

# Check nginx logs
pct exec $VMID -- tail -f /var/log/nginx/error.log

# Verify frontend build exists
pct exec $VMID -- ls -la /opt/token-aggregation/frontend/dist
```

### API Not Responding

```bash
# Check API service
pct exec $VMID -- systemctl status token-aggregation

# Test API directly
pct exec $VMID -- curl http://localhost:3000/health
```

## Integration with Other Services

The service can run alongside other services in the same Proxmox environment:

- Share database with explorer backend
- Use same RPC endpoints
- Integrate with existing monitoring

## Scaling

For high availability:

1. Deploy multiple containers with different VMIDs
2. Use load balancer (nginx, HAProxy)
3. Share database across instances
4. Use shared storage for frontend assets (optional)