Deployment

This guide covers deployment options for SupaScan, including self-hosted installation and access methods.

Self-Hosted Installation

SupaScan provides enterprise-grade self-hosted deployment options for organizations requiring full control over their blockchain data infrastructure.

System Requirements

  • Node.js: Version 18 or higher
  • ClickHouse: Version 22.8 or higher
  • Redis: Version 6 or higher
  • RAM: Minimum 16GB, recommended 32GB+
  • Storage: Minimum 1TB SSD, recommended 5TB+ for full indexing
  • CPU: 8+ cores recommended
  • OS: Linux (Ubuntu 20.04+ recommended)

Network Requirements

  • Outbound HTTPS access to Solana RPC endpoints
  • Outbound HTTP/HTTPS access to ClickHouse cluster
  • Inbound access for API endpoints (ports 3000, 8123)
  • Stable high-bandwidth internet connection

Installation

1. Clone the Repository

git clone https://github.com/supascan/supascan-selfhosted.git
cd supascan-selfhosted

2. Install Dependencies

npm install

3. Configure Environment

# Copy example configuration
cp .env.example .env

# Edit configuration
nano .env

Add your configuration:

# SupaScan Configuration
NODE_ENV=production
LOG_LEVEL=info

# ClickHouse Configuration
CLICKHOUSE_HOST=localhost
CLICKHOUSE_PORT=9000
CLICKHOUSE_DATABASE=supascan
CLICKHOUSE_USERNAME=default
CLICKHOUSE_PASSWORD=your_password

# Solana RPC Configuration
SOLANA_RPC_URL=https://api.mainnet-beta.solana.com
SOLANA_RPC_URLS=https://api.mainnet-beta.solana.com,https://solana-api.projectserum.com
SOLANA_COMMITMENT=confirmed

# Redis Configuration
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=your_redis_password

# API Configuration
API_PORT=3000
API_HOST=0.0.0.0
CORS_ORIGINS=*

# Indexing Configuration
INDEXING_BATCH_SIZE=1000
INDEXING_INTERVAL_MS=1000
INDEXING_WORKERS=4

4. Setup ClickHouse Cluster

# Install ClickHouse
curl https://clickhouse.com/ | sh
sudo ./clickhouse install

# Start ClickHouse
sudo clickhouse start

# Create database and tables
npm run init-clickhouse

5. Setup Redis

# Install Redis
sudo apt update
sudo apt install redis-server

# Start Redis
sudo systemctl start redis-server
sudo systemctl enable redis-server

6. Build and Start

# Build TypeScript
npm run build

# Start SupaScan
npm start

Deployment Options

Option 1: Docker Compose (Recommended)

The easiest way to deploy SupaScan with all dependencies:

# Clone repository
git clone https://github.com/supascan/supascan-selfhosted.git
cd supascan-selfhosted

# Configure environment
cp .env.example .env
nano .env

# Start all services
docker-compose up -d

Option 2: PM2 (Node.js Only)

For existing ClickHouse/Redis infrastructure:

# Install PM2
npm install -g pm2

# Start SupaScan
pm2 start ecosystem.config.js

PM2 Ecosystem File

Create ecosystem.config.js:

module.exports = {
  apps: [{
    name: 'supascan-api',
    script: './dist/api.js',
    instances: 4,
    autorestart: true,
    watch: false,
    max_memory_restart: '4G',
    env: {
      NODE_ENV: 'production'
    },
    error_file: './logs/pm2-error.log',
    out_file: './logs/pm2-out.log',
    log_file: './logs/pm2-combined.log',
    time: true
  }, {
    name: 'supascan-indexer',
    script: './dist/indexer.js',
    instances: 1,
    autorestart: true,
    watch: false,
    max_memory_restart: '8G',
    env: {
      NODE_ENV: 'production'
    }
  }]
};

PM2 Commands

# View status
pm2 status

# View logs
pm2 logs supascan-api
pm2 logs supascan-indexer

# Restart services
pm2 restart supascan-api
pm2 restart supascan-indexer

# Monitor
pm2 monit

# Save configuration
pm2 save
pm2 startup

Access Methods

1. REST API

SupaScan provides comprehensive REST API endpoints:

# Base URL
https://your-supascan.com/api/v1

# Authentication
Authorization: Bearer sk_your_api_key

Core Endpoints

  • Transactions: /v1/transactions/{signature}
  • Token Data: /v1/tokens/{mint}/analysis
  • Wallet Analysis: /v1/wallets/{address}/profile
  • DEX Swaps: /v1/swaps?protocol=raydium&limit=100
  • Token Transfers: /v1/transfers?token={mint}&limit=100

Analytics Endpoints

  • Token Volume: /v1/analytics/tokens/volume?period=24h
  • Top Wallets: /v1/analytics/wallets/top?period=7d
  • DEX Fees: /v1/analytics/dex/fees?protocol=raydium
  • Market Metrics: /v1/analytics/market/overview

2. SQL API

Direct ClickHouse access for advanced queries:

# SQL API endpoint
POST https://your-supascan.com/api/v1/sql

# Example query
{
  "query": "SELECT token_mint, sum(ui_amount) as volume FROM token_transfers WHERE block_time > now() - INTERVAL 24 HOUR GROUP BY token_mint ORDER BY volume DESC LIMIT 10"
}

3. WebSocket API

Real-time data streaming:

// Connect to WebSocket
const ws = new WebSocket('wss://your-supascan.com/ws');

// Subscribe to token events
ws.send(JSON.stringify({
  type: 'subscribe',
  channel: 'token_transfers',
  filters: { token_mint: 'So111...' }
}));

// Receive real-time updates
ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('New transfer:', data);
};

4. Webhook API

Event-driven notifications:

# Create webhook subscription
POST https://your-supascan.com/api/v1/webhooks
{
  "webhook_url": "https://your-app.com/webhook",
  "filters": {
    "token_name_contains": ["PEPE", "DOGE"],
    "min_liquidity_usd": 10000
  }
}

5. GraphQL API

Flexible data querying:

# GraphQL endpoint
https://your-supascan.com/graphql

# Example query
query GetTokenAnalysis($mint: String!) {
  token(mint: $mint) {
    symbol
    name
    volume24h
    holders
    transfers(first: 10) {
      from
      to
      amount
      timestamp
    }
  }
}

6. SupaApps Interface

Specialized analysis tools:

  • Wallet Profiler: /supapps/wallet/{address}
  • KOL Watch: /supapps/kol/{influencer_id}
  • PnL Detective: /supapps/pnl/{wallet}?period=30d
  • Rebirth Monitor: /supapps/rebirth?tokens=active
  • Farmer Classifier: /supapps/farmer/{wallet}

Production Checklist

Before Deployment

  • Set NODE_ENV=production
  • Configure ClickHouse cluster
  • Setup Redis with persistence
  • Configure API rate limits
  • Test all endpoints
  • Setup SSL certificates
  • Configure monitoring

Security

  • Use strong API keys
  • Configure CORS properly
  • Setup firewall rules
  • Use non-root user
  • Enable HTTPS
  • Regular security updates

Monitoring

  • Setup ClickHouse monitoring
  • Configure API metrics
  • Setup indexing lag alerts
  • Monitor disk space
  • Track memory usage
  • Setup log aggregation

Post-Deployment

Verification

  1. Check services status:

    pm2 status
curl http://localhost:3000/health

  2. Test API endpoints:

    curl -H "Authorization: Bearer sk_test_123" \
  http://localhost:3000/v1/transactions/recent

  3. Verify indexing:

    curl http://localhost:3000/debug/indexing

Maintenance

Updates

# Stop services
pm2 stop all

# Pull updates
git pull
npm install
npm run build

# Restart services
pm2 start ecosystem.config.js

ClickHouse Maintenance

-- Optimize tables
OPTIMIZE TABLE transactions FINAL;
OPTIMIZE TABLE token_transfers FINAL;

-- Check cluster health
SELECT hostName(), uptime() FROM system.clusters;

Troubleshooting

Common Issues

  1. Indexing lag: Check RPC node connectivity
  2. API errors: Verify ClickHouse connection
  3. Memory issues: Increase Node.js heap size
  4. Slow queries: Check ClickHouse indexes

Debug Commands

# Check system status
curl http://localhost:3000/debug/status

# Monitor indexing
curl http://localhost:3000/debug/indexing

# Check ClickHouse
curl 'http://localhost:8123/?query=SELECT%201'
Previous
Testing
Next
Monitoring & Maintenance