Deployment Guide (Netlify)

Relevant source files

The following files were used as context for generating this wiki page:

• netlify.toml
• netlify/functions/package.json
• DEPLOYMENT_CHECKLIST.md
• package.json
• README.md
• CONTRIBUTING.md
• GEMINI.md

BMSview is deployed on Netlify, leveraging its platform for both the frontend application and serverless backend functions. The frontend is a React application built with Vite, and the backend consists of Node.js-based Netlify Functions. Deployment is automated through Netlify's continuous integration and deployment (CI/CD) pipeline, which triggers a new build and deploy upon every push to the connected GitHub repository.

This guide provides a comprehensive overview of the configuration, build process, and verification steps required for a successful deployment, based on the project's established procedures. For more information on system architecture, see the ARCHITECTURE.md and for AI integration details, refer to GEMINI.md.

Sources: README.md:111-115, DEPLOYMENT_CHECKLIST.md

1. Configuration

Proper configuration is critical for a successful deployment. This includes Netlify-specific settings in netlify.toml and environment variables for connecting to external services.

1.1. Netlify Configuration (netlify.toml)

The netlify.toml file defines the build commands, the functions directory, and the publish directory for the site.

[build]
  command = "npm run build"
  functions = "netlify/functions"
  publish = "dist"

[functions]
  node_bundler = "esbuild"

• build.command: Executes npm run build to create a production build of the React frontend.
• build.functions: Specifies that serverless functions are located in the netlify/functions directory.
• build.publish: The output directory for the built frontend assets, which Netlify will serve.
• functions.node_bundler: Uses esbuild for faster function bundling.

Sources: netlify.toml:1-8

1.2. Environment Variables

Environment variables are managed in the Netlify dashboard and are essential for the application to function. They must be set before deployment.

Variable	Description	Example Value	Source File
GEMINI_API_KEY	API key for Google Gemini AI services.	your_gemini_api_key	README.md:52
MONGODB_URI	Connection string for the MongoDB database.	your_mongodb_connection_string	README.md:53
MONGODB_DB_NAME	The name of the database to use.	your_database_name	README.md:54
DB_MAX_POOL_SIZE	Sets the maximum pool size for the database connection.	10	DEPLOYMENT_CHECKLIST.md:59
RATE_LIMIT_TOKENS_PER_MINUTE	Configures rate limiting for functions.	60	DEPLOYMENT_CHECKLIST.md:60
CIRCUIT_BREAKER_THRESHOLD	Sets the failure threshold for the circuit breaker pattern.	5	DEPLOYMENT_CHECKLIST.md:61
NETLIFY_FUNCTION_TIMEOUT_MS	Configures the timeout for Netlify functions (e.g., for Pro tier).	20000	FINAL_IMPLEMENTATION_SUMMARY.md:214

Sources: DEPLOYMENT_CHECKLIST.md:57-65, README.md:51-55, FINAL_IMPLEMENTATION_SUMMARY.md:212-215

2. Build and Deployment Workflow

The project uses npm for dependency management for both the frontend and the backend functions. The deployment process is automated by Netlify.

2.1. Dependencies

The project has two separate package.json files:

• Root package.json: Manages dependencies for the React frontend, including react, vite, and tailwindcss.
• netlify/functions/package.json: Manages dependencies for the serverless functions, such as the MongoDB driver and Google Gemini client.

Sources: package.json, netlify/functions/package.json

2.2. Automated Deployment Pipeline

The deployment process is triggered by a git push to the main branch on GitHub. Netlify's CI/CD pipeline then automates the build and deployment.

This diagram illustrates the automated deployment flow.

3. Deployment Checklist

The DEPLOYMENT_CHECKLIST.md provides a mandatory sequence of steps to ensure a stable deployment.

3.1. Pre-Deployment

Before deploying, several verification steps must be completed.

1. Environment Preparation: Verify all required environment variables are set correctly in the Netlify dashboard.
2. Database Setup: Back up the database and run any necessary migration scripts, such as node scripts/create-indexes.js to create database indexes.
3. Code Review: Ensure all new code has been reviewed, especially for error handling and proper logger integration.
4. Build Verification: This is a mandatory step. The build must succeed locally before pushing.
   • Run npm run build.
   • Check for CommonJS/ESM module conflicts.
   • Verify syntax of all .cjs function files with node -c netlify/functions/**/*.cjs.

Sources: DEPLOYMENT_CHECKLIST.md:5-28

3.2. Deployment Steps

The checklist outlines a safe deployment process, including backups.

This flowchart shows the manual deployment process.

Backup*: Create backups of current functions and environment variables. Tag the current commit in Git.

• Deploy Modules: Ensure shared utility modules (logger.js, dbClient.js, etc.) are present.
• Update Environment Variables: Add any new environment variables to the Netlify UI.
• Deploy Functions: Replace old function files with new or enhanced versions.
• Commit and Push: Commit all changes and push to the designated branch to trigger the Netlify deployment.

Sources: DEPLOYMENT_CHECKLIST.md:33-97

3.3. Post-Deployment Verification

After deployment, a series of tests must be run to verify the health of the application.

1. Function Deployment: Use netlify functions:list to confirm all serverless functions are deployed without errors.
2. Database Indexes: Connect to MongoDB and verify that the expected indexes exist on the jobs, history, and systems collections.
3. Function Testing: Use curl to test the primary API endpoints (analyze, get-job-status) and check for correct status codes and response times.
4. Log Verification: Use netlify logs --live to check for structured JSON logs and ensure there are no unexpected errors.
5. Performance Verification: Check database query performance to ensure indexes are being used (IXSCAN vs. COLLSCAN) and monitor function response times.
6. End-to-End Test: Perform a full workflow test by uploading an image, monitoring its status, and verifying the final result in the UI.

Sources: DEPLOYMENT_CHECKLIST.md:102-205

4. Rollback Plan

If a deployment introduces critical issues, a rollback plan is in place to restore the application to a stable state.

• Immediate Rollback: Use the netlify rollback command to instantly revert to the previous successful deployment.
• Partial Rollback: If only a specific function is problematic, restore it from the backup, commit, and push to trigger a new deployment with the fix.
• Database Rollback: If new indexes cause performance issues, they can be dropped manually. For data corruption, restore from the pre-deployment database backup.

Sources: DEPLOYMENT_CHECKLIST.md:231-251

5. Monitoring

After a successful deployment, ongoing monitoring is crucial.

• Alerts: Set up alerts for high function error rates (>5%), database query timeouts, and other key metrics.
• Dashboards: Configure dashboards to track function performance, database metrics, and API usage.
• Logging: Use a log aggregation service to retain, search, and filter logs for easier debugging.

Sources: DEPLOYMENT_CHECKLIST.md:209-228