Deploy and Manage › Deployment

Deployment Information

Understanding Deployment Costs

Emergent charges a discounted rate for each deployment - significantly below the actual infrastructure costs we incur. Here's how we manage to offer this pricing:

Behind the Scenes:

Each deployment step uses dedicated cloud resources (compute, storage, networking)
We optimize costs by intelligently distributing multiple users per shared MongoDB cluster
Apps are grouped based on resource needs and usage patterns
This shared infrastructure model allows us to pass savings directly to you

What you get with deployment:

Complete build pipeline with optimized compilation
Managed database migrations and indexing
Secure environment variable handling
Production-grade Kubernetes deployment
Load balancing and health monitoring
Monthly hosting for your deployed app

Deployment Pipeline Stages

1. Building Package

What happens:

Compiles your React frontend code
Installs all JavaScript/Node dependencies (from package.json)
Installs Python backend dependencies (from requirements.txt)
Creates optimized production builds
Bundles all assets and code into a deployable package

Environment Differences:

Preview Environment: Higher compute and memory resources for testing
Production Environment: Optimized resources for live deployment

Warning

Heavy libraries that work in preview may fail in production due to lower resource limits. Consider using external APIs instead of installing large packages directly.

Build Type Compatibility:

Emergent's agent automatically detects your build type (Next.js, Expo, FARM stack, etc.)
The agent ensures compilation matches your original build configuration
Cross-stack builds are not supported - you cannot build a Next.js app as a FARM stack app or vice versa

Common Errors:

Missing dependencies in package.json or requirements.txt
Syntax errors in JavaScript/Python code
Build compilation failures (TypeScript errors, import issues)
Memory/timeout issues during large builds
Incompatible package versions
Heavy libraries exceeding production resource limits

How to fix:

Test your app in preview mode first
Ensure all dependencies are properly declared
Replace heavy libraries with API-based alternatives
Check for code syntax errors

2. Migrate Database

What happens:

Connects to your MongoDB instance
Creates necessary collections and indexes
Applies database schema migrations
Validates data models and structures

Tip

Prompt the Emergent agent to streamline database migrations with optimized queries. Non-optimized queries may fail during deployment.

Large Assets: MongoDB's built-in storage has limitations for heavy assets. Consider connecting external databases like Supabase or PostgreSQL for smoother deployments with large files
Shared Resources: Since cluster resources are shared among multiple users, apps consuming excessive resources may affect others. Emergent monitors for this and will temporarily block deployments if your app causes resource issues - contact support to resolve

Common Errors:

MongoDB connection failures
Invalid database credentials
Schema validation errors
Collection creation failures
Migration script errors
Heavy asset storage failures
Non-optimized queries timing out

How to fix:

Verify MONGO_URL in your .env file
Optimize database queries before deployment
Use external databases for large files/assets
Ensure database models are properly defined

3. Export Secrets

What happens:

Transfers environment variables (.env files) to production
Encrypts and securely stores API keys
Validates secret formats and values
Configures production environment variables

Info

Environment variables are the secure way to store sensitive information like API keys, database URLs, and other credentials. Never hardcode these values directly in your code.

Common Errors:

Missing required environment variables
Invalid API key formats
Hardcoded URLs or secrets in code (instead of env variables)
Special characters in environment variables causing parsing issues

How to fix:

Ensure all required keys are in .env files
Never hardcode secrets in your codebase
Validate that API keys are active and properly formatted

4. Deploy

What happens:

Provisions infrastructure on Kubernetes cluster
Deploys frontend and backend containers
Sets up load balancing and networking
Configures ingress rules and routing
Allocates compute resources

Note

This step typically takes 10-15 minutes to complete. Please be patient while the infrastructure is being set up.

Common Errors:

Infrastructure provisioning failures
Container startup crashes
Resource allocation issues (memory/CPU limits)
Port binding conflicts
Network configuration problems

How to fix:

Wait for the full process to complete
Check for startup errors in your code
Contact support if infrastructure issues persist

5. Run Health Check

What happens:

Tests if your application is responding
Verifies API endpoints are accessible
Checks frontend loads correctly
Validates database connectivity in production
Confirms all services are running

Warning

If health checks fail, your deployment won't go live. This protects you from deploying broken applications.

Common Errors:

Application crashes on startup
API endpoints returning error codes (500/502/503)
Frontend not loading (white screen)
Database connection failures in production
CORS or routing issues

How to fix:

Ensure preview works perfectly before deployment
Verify production environment variables are correct
Check that all services start properly in production environment

Replacing Existing Deployments

If you've forked (branched) a previous deployment and want to replace it, you can avoid paying for multiple active deployments:

Scenario 1: No Traffic on Previous Deployment

Simply replace the existing deployment with your new job
This avoids duplicate monthly hosting costs
The replacement process is seamless with no traffic disruption

Scenario 2: Active Traffic on Previous Deployment

Use MongoDB's export tool to download your existing database
Attach the downloaded database to your new job
Replace the existing deployment once migration is complete
This optimizes your credit usage while preserving your data

Benefits:

Save on monthly hosting costs
Maintain continuity for active applications
Optimize your Emergent credit usage

Best Practices to Avoid Deployment Errors

Catch issues before committing to a deployment. Preview mode gives you higher resources to test thoroughly.

Never hardcode URLs, API keys, or port numbers. Use .env files for all configuration values.

Ensure requirements.txt and package.json list every package your app needs. Missing dependencies are a common cause of build failures.

Test third-party integrations work before deployment. Expired or invalid keys will cause deployment failures.

Use the Emergent agent to help streamline database migrations. Slow queries can timeout during deployment.

For apps with large assets or heavy data loads, use external database services like Supabase or PostgreSQL instead of MongoDB's built-in storage.

Production has lower resource limits than preview. Use external API services instead of installing large packages when possible.

Be mindful that you're sharing cluster resources with other users. Excessive resource consumption can affect others and result in deployment blocks.

Check supervisor logs regularly for backend errors. Early detection prevents deployment issues.

Deployment involves multiple complex steps and typically takes 10-15 minutes. Don't interrupt the process.

When to Contact Support

Reach out to our support team when you encounter:

Deployment fails at the same step multiple times
Infrastructure or provisioning errors
Resource blocking issues due to cluster constraints
Database migration optimization help
Issues that aren't related to your code
Production-specific problems that don't occur in preview
Questions about replacing or managing deployments

Support: support@emergent.sh
Please include your job ID when contacting support for faster assistance

Understanding Resource Environments

Environment	Resources	Best For
Preview	Higher compute & memory	Testing, development, heavy libraries
Production	Optimized resources	Live apps, efficient code

Shared Infrastructure:

Multiple users share MongoDB clusters for cost efficiency
Apps are intelligently distributed based on resource needs
Resource monitoring prevents any single app from affecting others
Cost savings from shared infrastructure are passed to you

Tip

Always validate your app works flawlessly in preview before deploying. This ensures a smooth production launch and helps you avoid common deployment issues.