deployment.md

Deployment Guide

This guide covers deploying the ILN Indexer in various environments.

Prerequisites

• Node.js 20+
• npm or yarn
• SQLite (bundled with better-sqlite3)
• Stellar RPC node access

Local Development

# Clone the repository
git clone https://github.com/Invoice-Liquidity-Network/Invoice-Liquidity-Network.git
cd Invoice-Liquidity-Network

# Install dependencies
npm install

# Navigate to indexer
cd indexer

# Copy environment template
cp .env.example .env

# Edit .env with your configuration
# At minimum, set CONTRACT_ID and RPC_URL

# Start in development mode (with hot reload)
npm run dev

Production Deployment

Option 1: Direct Node.js

# Build the project
npm run build

# Start the server
npm start

Option 2: Docker

Create a Dockerfile in the indexer directory:

FROM node:20-alpine

WORKDIR /app

# Copy package files
COPY package*.json ./

# Install production dependencies
RUN npm ci --only=production

# Copy built files
COPY dist/ ./dist/

# Copy database path
RUN mkdir -p /data

# Set environment variables
ENV DB_PATH=/data/indexer.db
ENV PORT=3001

# Expose port
EXPOSE 3001

# Health check
HEALTHCHECK --interval=30s --timeout=3s \
  CMD curl -f http://localhost:3001/health || exit 1

# Start the server
CMD ["node", "dist/index.js"]

Build and run:

# Build the Docker image
docker build -t iln-indexer .

# Run the container
docker run -d \
  --name iln-indexer \
  -p 3001:3001 \
  -v indexer-data:/data \
  -e CONTRACT_ID=YOUR_CONTRACT_ID \
  -e RPC_URL=YOUR_RPC_URL \
  -e NETWORK_PASSPHRASE="Test SDF Network ; September 2015" \
  iln-indexer

Option 3: Docker Compose

Create docker-compose.yml:

version: '3.8'

services:
  indexer:
    build: .
    ports:
      - "3001:3001"
    volumes:
      - indexer-data:/data
    environment:
      - CONTRACT_ID=${CONTRACT_ID}
      - RPC_URL=${RPC_URL}
      - NETWORK_PASSPHRASE=${NETWORK_PASSPHRASE:-Test SDF Network ; September 2015}
      - REDIS_URL=redis://redis:6379
    depends_on:
      - redis
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redis-data:/data
    restart: unless-stopped

volumes:
  indexer-data:
  redis-data:

Run:

# Create .env file
cat > .env << EOF
CONTRACT_ID=your_contract_id
RPC_URL=https://soroban-testnet.stellar.org
NETWORK_PASSPHRASE=Test SDF Network ; September 2015
EOF

# Start services
docker-compose up -d

Option 4: Railway

The project includes railway.toml for Railway deployment:

# Install Railway CLI
npm install -g @railway/cli

# Login
railway login

# Link to project
railway link

# Set environment variables
railway variables set CONTRACT_ID=your_contract_id
railway variables set RPC_URL=https://soroban-testnet.stellar.org

# Deploy
railway up

Environment Variables

See Configuration for complete environment variable reference.

Production Considerations

Database

1. Backup Strategy: Regularly backup the SQLite database
2. Storage: Use persistent storage (volume mount or managed disk)
3. Location: Keep database on fast storage (SSD preferred)

Networking

1. RPC Access: Ensure reliable access to Stellar RPC nodes
2. Rate Limits: Be aware of RPC rate limits
3. Fallback: Consider multiple RPC endpoints for redundancy

Monitoring

1. Health Checks: Monitor /health endpoint
2. Logs: Aggregate logs for analysis
3. Alerts: Set up alerts for:
   • Service downtime
   • High error rates
   • Database issues
   • Sync delays

Scaling

The indexer is designed for single-instance deployment due to:

• SQLite single-writer constraint
• Cursor management
• Event deduplication

For high-traffic scenarios:

1. Use Redis for caching
2. Consider read replicas for API queries
3. Monitor database size and prune old events

Updating

# Pull latest changes
git pull

# Rebuild
npm run build

# Restart the service
# For direct Node.js:
pkill -f "node dist/index.js"
npm start

# For Docker:
docker-compose down
docker-compose up -d --build

# For Railway:
railway up

Troubleshooting

See Troubleshooting Guide for common issues and solutions.