228 lines
7.1 KiB
Markdown
228 lines
7.1 KiB
Markdown
# 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
|
|
```env
|
|
# 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)
|
|
```env
|
|
# 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
|
|
```env
|
|
# 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
|
|
```javascript
|
|
// 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:
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```env
|
|
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`:
|
|
|
|
```javascript
|
|
// 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:
|
|
```env
|
|
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:
|
|
```env
|
|
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:
|
|
```bash
|
|
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:
|
|
|
|
```env
|
|
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.
|