Skip to main content

TwinSpires Deployment Guide

This guide covers deploying Bike4Mind for TwinSpires using AWS DocumentDB.

Prerequisites​

  1. AWS account access for TwinSpires (staging and production)
  2. DocumentDB cluster created in each environment
  3. VPC and security groups properly configured
  4. SST CLI installed (npm install -g sst)

Certificate Setup​

Before deploying, you need to prepare the DocumentDB certificate:

# Download and prepare the certificate
./scripts/update-documentdb-cert.sh

# Option 1: Set as environment variable (recommended for CI/CD)
export DOCUMENTDB_CA_BUNDLE_BASE64=$(cat global-bundle-base64.txt)

# Option 2: Update the code directly (for testing)
# Replace the certificate in b4m-core/packages/core/database/src/certs/documentdb-cert-manager.ts

Environment Configuration​

Staging Deployment​

  1. Set DocumentDB connection string:

    npx sst secrets set MONGODB_URI "mongodb://username:password@twinspires-staging-docdb.cluster-xxxxx.us-east-1.rds.amazonaws.com:27017/bike4mind?ssl=true&replicaSet=rs0&readPreference=secondaryPreferred&retryWrites=false" --stage twinspires-staging

  2. Set other required secrets:

    # Example - replace with actual values
    npx sst secrets set SESSION_SECRET "your-session-secret" --stage twinspires-staging
    npx sst secrets set JWT_SECRET "your-jwt-secret" --stage twinspires-staging
    # ... set other secrets as needed

  3. Deploy with DocumentDB support:

    MAIN_DB_TYPE=DocumentDB npx sst deploy --stage twinspires-staging

Production Deployment​

Same process as staging, but use --stage twinspires-production and production DocumentDB connection string.

VPC Configuration​

Ensure your sst.config.ts includes VPC configuration for DocumentDB access:

// The VPC is already configured in your sst.config.ts
// Just ensure VPC_ID is set for TwinSpires environments
export VPC_ID=vpc-xxxxx  # TwinSpires VPC ID

Post-Deployment Verification​

  1. Check Lambda logs:

    • Look for "Detected DocumentDB connection" in CloudWatch logs
    • Verify no certificate errors

  2. Test basic connectivity:

    # Check if the application is running
    curl https://app.twinspires-staging.bike4mind.com/health

  3. Monitor for errors:

    • Check CloudWatch logs for any connection failures
    • Verify Lambda functions can connect to DocumentDB

Troubleshooting​

Common Issues​

  1. Certificate not found:

    • Ensure DOCUMENTDB_CA_BUNDLE_BASE64 is set or certificate is embedded
    • Check Lambda has write permissions to /tmp

  2. Connection timeouts:

    • Verify Lambda functions are in the correct VPC
    • Check security group rules allow connection to DocumentDB

  3. Authentication failures:

    • Verify DocumentDB username/password in connection string
    • Check DocumentDB user permissions

Debug Commands​

# Check secret values (without exposing them)
npx sst secrets list --stage twinspires-staging

# View Lambda function logs
aws logs tail /aws/lambda/twinspires-staging-frontend --follow

# Test DocumentDB connectivity from bastion host
mongo --ssl --host docdb-cluster.xxxxx.rds.amazonaws.com:27017 \
      --sslCAFile global-bundle.pem \
      --username your-username --password

Rollback Procedure​

If issues occur:

  1. Quick rollback to previous version:

    npx sst deploy --stage twinspires-staging --rollback

  2. Switch back to MongoDB Atlas (if needed):

    # Update connection string to Atlas
    npx sst secrets set MONGODB_URI "mongodb+srv://..." --stage twinspires-staging

    # Deploy without DocumentDB flag
    npx sst deploy --stage twinspires-staging

Security Considerations​

  1. Certificate Management:

    • Never commit the actual certificate to the repository
    • Use environment variables or AWS Secrets Manager for production

  2. Network Security:

    • DocumentDB should only be accessible from within VPC
    • Use security groups to restrict access to Lambda functions only

  3. Encryption:

    • DocumentDB enforces encryption in transit (TLS)
    • Enable encryption at rest in DocumentDB settings

Maintenance​

Certificate Updates​

When AWS updates the DocumentDB certificate:

  1. Download new certificate:

    ./scripts/update-documentdb-cert.sh

  2. Update deployment with new certificate

  3. Redeploy all environments

Monitoring​

Set up CloudWatch alarms for:

  • DocumentDB CPU and memory usage
  • Connection count
  • Failed connection attempts
  • Lambda errors related to database connectivity