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

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

Manual Deployment Steps

1. Create LXC Container

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

pct start $VMID

3. Install Dependencies

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

# 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

# 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:

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:

# 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

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

# 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

# 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

# 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

# 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)