Advanced Configuration

Environment Variables

QuranBot uses a dual-environment system with development.env and production.env. The active environment is determined by NODE_ENV in the base .env file.

Core Variables (Required)

Environment-Specific Variables

Environment Switcher

The src/config/envSwitcher.js module handles environment selection at startup:

require('pathlra-aliaser')();

const path = require('path');
const dotenv = require('dotenv');
const logger = require('@logging/logger');
const fs = require('fs');

const baseEnvFilePath = path.resolve(__dirname, '../../.env');
let baseEnvConfig = {};

if (fs.existsSync(baseEnvFilePath)) {
    const rawBaseEnv = fs.readFileSync(baseEnvFilePath, 'utf8');
    baseEnvConfig = dotenv.parse(rawBaseEnv);
}

const activeEnv = baseEnvConfig.NODE_ENV;
const targetedEnvPath = path.resolve(__dirname, `../../${activeEnv}.env`);

const loadResult = dotenv.config({ path: targetedEnvPath });

if (loadResult.error) {
    logger.error(`Could Not Load ${activeEnv} Env File`, loadResult.error.message);
    process.exit(1);
} else {
    logger.info(`Loaded ${activeEnv} Env`);
}

// Remove TOPGG_TOKEN in development to prevent accidental use of production API key during dev
if (activeEnv === 'development') {
    if (process.env.TOPGG_TOKEN) {
        delete process.env.TOPGG_TOKEN;
        logger.info('Development Mode TOPGG_TOKEN Removed');
    }
}

module.exports.isDevelopment = activeEnv === 'development';
module.exports.isProduction = activeEnv === 'production';
module.exports.currentEnv = activeEnv;

Setup Steps:

1. Copy development.env.example → development.env
2. Copy production.env.example → production.env
3. Set NODE_ENV=production (or development) in base .env

Lavalink Configuration

QuranBot uses Lavalink v4 for scalable, low-latency audio processing. Configuration is managed via LAVALINK_NODES_ environment variable.

JSON Format (Recommended)

# Lavalink Audio Server
LAVALINK_NODES_='[
  {
    "host": "ip",
    "port": 2022,
    "password": "123",
    "secure": false,
    "maxPlayers": 60,
    "location": "India, Pune",
    "flag": "🇮🇳",
    "playerCreateDelay": 100
  },
  {
    "host": "ip",
    "port": 2022,
    "password": "123",
    "secure": false,
    "maxPlayers": 500,
    "location": "Mexico, Santiago de Querétaro",
    "flag": "🇲🇽",
    "playerCreateDelay": 100
  }
]'

Node Selection Logic

The bot selects nodes using getBestNode() in src/startup/botSetup.js:

1. Filter nodes: connected + under maxPlayers limit
2. Sort by current player count (least loaded first)
3. Return first available node; null if all full

Node Management & Failover

Runtime Node Switching

Users can manually select nodes via the control panel. The select_lavalink_node menu handler in src/interactions/menus/lavalinkNodes.js manages migration:

// Key steps during node switch:
const currentPosition = guildState.player.position || 0;
const wasPaused = guildState.player.paused || false;

// 1. Reconnect to new node
await initializeConnection(guildId, guildState, targetChannel, adapter);

// 2. Recreate audio resource
const track = await createSurahResource(guildState, index);

// 3. Resume playback at exact position
await guildState.player.play({ track });
if (currentPosition > 0) {
    await guildState.player.seek(currentPosition);
}
if (wasPaused) await guildState.player.pause(true);

Automatic Failover

If a node disconnects during playback:

• Lavalink client auto-reconnects per retryAmount/retryDelay
• Bot listens for nodeManager.on('disconnect') events
• State persistence ensures playback resumes after reconnection

Redis Setup

Redis provides hot caching for guild states, enabling stateless sharding and sub-millisecond lookups.

Configuration

Connection String Examples

# Local development
REDIS_URL=redis://localhost:6379

# With password authentication
REDIS_URL=redis://:my_password@localhost:6379

# Redis Cloud / Managed service
REDIS_URL=rediss://default:password@redis-12345.c1.us-east-1-2.ec2.redns.redis-cloud.com:12345

# With database selection
REDIS_URL=redis://localhost:6379/2

async function get(key) {
    try {
        if (clientManager.isRedisReady && client) {
            const result = await client.get(key);
            return result ? JSON.parse(result) : result;
        }
    } catch (error) {
        logger.error(`Redis get failed: ${error.message}`);
    }
    
    // Fallback to memory
    return memoryFallbackMap.get(key) || null;
}

Firebase Integration

Firebase Realtime Database serves as the cold storage layer for persistent state, complaints, and statistics.

Service Account Setup

1. Go to Firebase Console → Project Settings → Service Accounts
2. Generate new private key → Download JSON file
3. Extract values into environment variables (see table below)

Required Firebase Variables

Database Rules

Ensure your firebase.rules.json denies public access:

{
  "rules": {
    ".read": false,
    ".write": false
  }
}

The bot uses server-side firebase-admin with service account credentials, which bypasses these rules for authenticated operations.

Deployment with PM2

QuranBot is optimized for process management via PM2, supporting auto-restart, logging, and clustering.

PM2 Configuration (ecosystem.config.js)

module.exports = {
  apps: [{
    name: 'QuranBot',
    script: 'src/bot/core.js',
    node_args: '--trace-warnings --trace-deprecation --unhandled-rejections=strict --enable-source-maps',
    autorestart: true,
    watch: false,
    ignore_watch: ['node_modules', 'storage/logs', 'logs', '.git', '.test'],
    instances: 1,
    exec_mode: 'fork',
    env: {
      merge_logs: true,
      log_date_format: 'YYYY-MM-DD HH:mm:ss Z',
      error_file: 'storage/pm2/logs/pm2-error.log',
      out_file: 'storage/pm2/logs/pm2-out.log',
      restart_delay: 7000,
    },
  }],
};

Deployment Commands

Production Startup Script

#!/bin/bash
# deploy.sh - Production deployment script
set -e

# Load environment
export NODE_ENV=production
source .env

# Install dependencies
pnpm install --prod

# Run database migrations if needed
# pnpm run migrate

# Start with PM2
pnpm run pm2:start

# Save PM2 process list for auto-start on reboot
pm2 save

echo "QuranBot deployed successfully"

Sharding Strategy

For large-scale deployments, QuranBot supports Discord's sharding via discord-hybrid-sharding.

Shard Configuration Variables

Example: Multi-Instance Setup

For a bot serving 10,000+ servers, you might run 4 instances with 2 shards each:

# Instance 1 (.env.cluster1)
NODE_ENV=production
TOTAL_SHARDS=8
SHARD_LIST=0,1
SHARDS_PER_CLUSTER=2

# Instance 2 (.env.cluster2)
NODE_ENV=production
TOTAL_SHARDS=8
SHARD_LIST=2,3
SHARDS_PER_CLUSTER=2

# ... instances 3 and 4 for shards 4-7

# Start each with:
NODE_ENV=production pnpm run run:shard

Health Checks & Monitoring

Built-in Health Endpoint

The bot exposes a lightweight HTTP health check on port HH_CH_PORT (default: 3000):

# Example request
curl http://localhost:3000/health

# Response
{
  "status": "ok",
  "voiceConnections": 42,
  "uptime": 86400.123,
  "memory": {
    "rss": 256000000,
    "heapTotal": 128000000,
    "heapUsed": 96000000
  },
  "timestamp": "2026-05-24T12:00:00.000Z"
}

Key Metrics to Monitor

• Memory Usage: Alert if heapUsed > 1.5GB (triggers aggressive GC)
• Voice Connections: Sudden drops may indicate Lavalink issues
• Uptime: Track restarts via pm2 logs or health endpoint
• Log Volume: Spike in error logs may indicate external API failures

Log Rotation

Logs are automatically archived daily at Cairo midnight:

• Location: storage/logs/archive/
• Format: logs-general-YYYY-MM-DD.zip
• Retention: 60 days (configurable in logging_config)

Troubleshooting Guide

Diagnostic Commands