agmission/Development/server/docs/SCALEGRID_CONFIG.md

ScaleGrid MongoDB Connection Configuration

This document provides guidance on configuring the MongoDB connection for ScaleGrid hosting, including solutions for common issues encountered during setup.

Environment Variables

When using ScaleGrid MongoDB hosting, configure the following environment variables in your environment_test_ScaleGrid.env file:

Required Settings

# Enable ScaleGrid connection mode
DB_USE_SCALEGRID=true

# ScaleGrid cluster hosts (provided by ScaleGrid)
DB_HOSTS='SG-AGN-Mongo-74082.servers.mongodirector.com:27017,SG-AGN-Mongo-74083.servers.mongodirector.com:27017'

# Database name
DB_NAME=agmission

# ScaleGrid credentials (from ScaleGrid dashboard)
DB_USR='test.agm'
DB_PWD='ThuXem-123.7212_25'

# Authentication source (the target database, not "admin" for ScaleGrid)
DB_AUTH_SOURCE=agmission

# Replica set name (provided by ScaleGrid)
DB_REPLSET='RS-AGN-Mongo-0'

# Enable TLS/SSL for secure connections (required for ScaleGrid)
DB_USE_TLS=true

# Path to CA Certificate file provided by ScaleGrid
DB_TLS_CA_FILE='/home/trung/Documents/AgMission/ScaleGrid/agn-mongo.cert'

Node.js v16 TLS Workaround Settings (REQUIRED)

# These settings are REQUIRED to work around Node.js v16 TLS assertion bugs
# Disable SSL validation to prevent "The assertion 'num_locks_held_by_this_thread > 0' failed."
DB_DISABLE_SSL_VALIDATE=true

# Disable hostname verification (required with ScaleGrid certificates)
DB_DISABLE_HOSTNAME_VERIFY=true

Additional Settings

# Connection pool size
DB_MAX_POOLSIZE=8

# Disable X509 authentication (use SCRAM-SHA-256 instead)
DB_USE_X509=false

Connection String Format

When DB_USE_SCALEGRID=true, the connection string is automatically formatted as:

mongodb://test.agm:ThuXem-123.7212_25@SG-AGN-Mongo-74082.servers.mongodirector.com:27017,SG-AGN-Mongo-74083.servers.mongodirector.com:27017/agmission

The connection options include:

• replicaSet: 'RS-AGN-Mongo-0'
• authSource: 'agmission'
• authMechanism: 'SCRAM-SHA-256'
• tls: true
• tlsInsecure: true (when SSL validation is disabled for Node.js v16 compatibility)

Implementation Details

The implementation automatically detects ScaleGrid configuration and applies appropriate settings:

ScaleGrid Connection Pattern

// When DB_USE_SCALEGRID=true
const options = {
  tls: true,
  tlsInsecure: true,  // Complete TLS bypass for Node.js v16 compatibility
  replicaSet: 'RS-AGN-Mongo-0',
  authSource: 'agmission',
  authMechanism: 'SCRAM-SHA-256',
  maxPoolSize: 8,
  connectTimeoutMS: 40000,
  socketTimeoutMS: 1800000
};

mongoose.connect('mongodb://username:password@hosts/database', options);

Key Implementation Features

1. Node.js v16 TLS Workaround:

   • Uses tlsInsecure: true to bypass all TLS validation
   • Prevents "assertion 'num_locks_held_by_this_thread > 0' failed" error
   • No conflicting TLS options that cause MongoAPIError

2. Modern MongoDB Driver Compatibility:

   • Uses replicaSet instead of deprecated replset
   • Employs SCRAM-SHA-256 authentication mechanism
   • Proper credential encoding in connection string

3. Error Handling:

   • Validates required environment variables before connection
   • Provides detailed debug logging for connection diagnostics
   • Graceful handling of certificate file reading errors

VS Code Debug Configuration

A pre-configured debug launch configuration is available for testing ScaleGrid connections:

{
  "name": "Node 16- AGM DEBUG ScaleGrid",
  "type": "node",
  "runtimeVersion": "16.20.2",
  "envFile": "${workspaceFolder}/environment_test_ScaleGrid.env",
  "env": { "DEBUG": "agm:*" }
}

This configuration:

• Uses Node.js v16.20.2 (matches production environment)
• Loads ScaleGrid-specific environment variables
• Enables full debug logging for connection diagnostics

Troubleshooting

Node.js v16 TLS Assertion Error

Problem: node: ../deps/openssl/openssl/crypto/rsa/rsa_lib.c:1152: rsa_multip_cap: Assertion 'num_locks_held_by_this_thread > 0' failed.

Solution: This is a known bug in Node.js v16 with TLS connections. The implementation uses tlsInsecure: true to bypass all TLS validation:

DB_DISABLE_SSL_VALIDATE=true
DB_DISABLE_HOSTNAME_VERIFY=true

MongoAPIError: conflicting TLS options

Problem: The 'tlsInsecure' option cannot be used with the 'tlsAllowInvalidCertificates' option

Solution: The implementation now uses only tlsInsecure: true when SSL validation is disabled, avoiding conflicting options.

MongoParseError: option replset is not supported

Problem: MongoParseError: option replset is not supported

Solution: The implementation now uses the modern replicaSet option instead of the deprecated replset:

// Modern approach (current implementation)
options.replicaSet = 'RS-AGN-Mongo-0';

// Old deprecated approach (removed)
// options.replset = 'RS-AGN-Mongo-0';

Authentication Errors

Problem: MongoServerError: Authentication failed

Solutions:

1. Verify credentials are correct in ScaleGrid dashboard
2. Ensure DB_AUTH_SOURCE=agmission (not "admin")
3. Check that the user has proper permissions on the target database
4. Verify the connection string format is correct

Current working configuration:

DB_USR='test.agm'
DB_PWD='ThuXem-123.7212_25'
DB_AUTH_SOURCE=agmission

Certificate File Errors

Problem: Cannot read certificate file

Solutions:

1. Verify the certificate file path is correct:

   DB_TLS_CA_FILE='/home/trung/Documents/AgMission/ScaleGrid/agn-mongo.cert'
   

2. Check file permissions are readable by the application
3. If using DB_DISABLE_SSL_VALIDATE=true, certificate file reading is skipped

Connection Timeouts

Problem: Connection timeouts to ScaleGrid servers

Solutions:

1. Check network connectivity to ScaleGrid hosts:

   telnet SG-AGN-Mongo-74082.servers.mongodirector.com 27017
   

2. Verify firewall rules allow outbound traffic on port 27017
3. Check if VPN or proxy is interfering with connections
4. Contact ScaleGrid support for network troubleshooting

Debug Connection Issues

Enable debug logging to diagnose connection problems:

DEBUG=agm:*

Or use the VS Code debug configuration "Node 16- AGM DEBUG ScaleGrid" which automatically:

• Loads the ScaleGrid environment file
• Enables comprehensive debug logging
• Uses Node.js v16.20.2 for compatibility

Current Status

As of the latest implementation:

• ✅ TLS Compatibility: Fixed Node.js v16 TLS assertion errors
• ✅ Modern Driver: Uses current MongoDB driver options
• ✅ Authentication: Proper SCRAM-SHA-256 authentication setup
• ✅ Error Handling: Comprehensive error handling and validation
• ✅ Debug Support: Full debug logging and VS Code integration
• ⚠️ Credentials: Requires verification of actual ScaleGrid credentials

The connection reaches the authentication stage successfully, indicating that TLS/SSL and network connectivity issues have been resolved. The remaining step is ensuring the correct username and password are configured in the ScaleGrid environment file.