Deployment Types

Understanding Deploy, Redeploy, and Replace Deployment

Overview

Emergent has three types of deployments, each handling your code and data differently. Understanding these is crucial to avoid data loss.

First Deploy

Brand new app

Fresh database

Redeploy

Update existing app

Data preserved

Replace Deployment

Swap apps

Optional data transfer

1. First Deploy (New App)

When It Happens

You click “Deploy” for the very first time on a project that has never been deployed.

What Gets Created

1. New App Identity

   A unique app record is created

2. Empty Database

   A brand new, empty MongoDB database is provisioned

3. Production Secrets

   Values from your development .env file are saved as production secrets

4. Live URL

   A unique URL is generated (like https://your-app.emergentworks.app)

5. Container Image

   Your code is built and stored in Google Container Registry

Data State

Everything is NEW:

• Fresh database (empty apart from preview data)
• New secrets from .env
• New URL

Perfect for: Launching a brand new app for the first time.

2. Redeploy (Update Existing)

When It Happens

You click “Deploy” on an app that’s already live.

What Gets Updated

Code Changes:

• Latest code from development pod -not data (images, files, data do not show up)
• Updated application

What Stays the SAME:

• Database (with ALL data preserved!)
• Existing secrets (not overwritten!)
• Same URL
• Same app identity

How Data is Handled

MongoDB Data

100% PRESERVED

• Same database connection
• All existing data intact
• No data loss
• Users unchanged
• Records preserved

Secrets

PRESERVED + MERGED

• Existing secrets preserved
• Not overwritten
• Only new keys added
• Old values kept

Important Secret Behavior

Existing secrets are NEVER overwritten!

Example: [to be revisited]

First Deploy (.env):
STRIPE_KEY=sk_test_123
API_KEY=old_value

(Secrets saved to production)

Later, you change .env:
STRIPE_KEY=sk_test_456  ❌ Won't update!
API_KEY=old_value
NEW_KEY=new_value       ✅ Will be added

After Redeploy:
STRIPE_KEY=sk_test_123  (still old value!)
API_KEY=old_value
NEW_KEY=new_value       (newly added)

To update existing secrets: You must change them in the platform’s secret management, NOT just in .env

Important: Changing .env values won’t update existing production secrets. Only new keys are added.

3. Replace Existing Deployment

When It Happens

You fork a project and choose to replace an existing deployed app when deploying the fork.

**Use Cases: **Replacing app 1 with app 2 or app 1 with app 1.2

_Why does a user need to replace deployment? _
- auto forking
- manual forked therefore new job ID and separate application on backend.
- or a completely new app that you want deployed instead of a discarded app.

What It Does

This deploys a completely NEW app and removes the previously deployed app.

Flow:

1. Build new app from forked code or a completely new app
2. (Optional) Transfer data from old app (Refer to the two options for data handling)
3. Switch traffic to new app and the old app is deleted.
4. New app is live for users.
5. The new app uses the deployment fees from the next cycle onwards.

Two Options for Data Handling

Without Data Persistence

Fresh Start

• New empty database
• Old data NOT transferred
• Preview data from the new app is copied to the new deployment
• New app’s secret values are added to the existing app’s .env file - old keys are not auto-updated.

Use when: Starting completely fresh

With Data Persistence

Keep Your Data

• Database connection copied
• All data preserved
• Same database used
• New app’s secret values are added to the existing app’s .env file - old keys are not auto-updated.

Use when: Keeping existing data

What Gets Created (New App)

Always NEW:

• New app identity
• New deployment

Depends on Choice:

• Database: New (no persist) or Same (with persist)
• Secrets: Copied from old app + appended with new .env

What Gets DELETED (Old App):

• Old app identity
• Old deployment
• Old service and resources
• Old app record

When to Replace

Replace deployment when:

• Forked to fix issues, want to swap
• Want to upgrade with major changes

Don’t replace if:

• Just updating code in the same job→ Use Redeploy instead!
• Want to keep both versions → Deploy as separate app

Be careful - If you replace without keeping old database, your old database becomes orphaned and you lose access to that data!

Data Survival Guide

Here’s what survives in each scenario:

What	First Deploy	Redeploy	Replace (Fresh Database)	Replace (Keeping Old Database)
Source Code	New	Updated	New from fork	New from fork
MongoDB Data	Empty	PRESERVED	Lost	PRESERVED
Database URL	New	Same	New	Copied from old
Secrets	From .env	PRESERVED	Copied from old	Copied from old
App URL	New	Same	New/Transferred	New/Transferred
Container Image	New	New version	New	New

Preview vs Production

Development Pod (Preview)

What it is:

• Your testing environment
• Where you build and preview
• Temporary workspace

Database:

• Separate test database
• NOT connected to production
• Data here is NOT production data
• Can be deleted anytime

Purpose:

• Writing code
• Testing features
• Seeing changes

Access:

• Only you (developer)

Production Deployment (Live)

What it is:

• Your live, public app
• What customers use
• Real production environment

Database:

• Production MongoDB - Managed via Cloud
• Real user data
• Persistent across redeploys
• Connected to always live URL

Purpose:

• Serving real users
• Storing real data
• Running your business

Access:

• Your customers

Key Point: Preview and Production use completely different databases. They never share data!

How Secrets Work

First Deploy

1. Read .env from development pod
2. Save all values as production secrets
3. Use these secrets in production

Redeploy

1. Read .env from development pod
2. Check existing production secrets
3. Keep all existing secrets (don't overwrite!)
4. Only add NEW keys from .env
5. Use merged secrets in production

Replace Deployment

1. Copy secrets from OLD app
2. Read .env from forked project
3. Merge: old secrets + new .env
4. Existing secrets retained (not overwritten)
5. Use merged secrets in NEW app

To Update Existing Secret:

Can't do it via .env on redeploy!

Must update directly in platform:
1. Go to deployment settings
2. Find secret management in the Deployment Pane.
3. Update secret value there
4. Or contact support

Common Scenarios

Scenario 1: Fixing a Bug

Situation: Your live app has a bug

1. Fix bug in development
2. Test in preview
3. Click "Deploy"
4. Redeploy updates code
5. All data preserved

What to do: Redeploy

Result: Bug fixed, data safe!

Scenario 2: Adding Major Features after Forking

Situation: Forked to rebuild, want to replace old app

1. Build in forked project
2. Test thoroughly
3. Deploy and choose "Replace existing"
4. Check "Preserve data"
5. Old app removed, new one live

What to do: Replace while keeping old database

Result: New code, old data preserved!

Scenario 3: Starting Completely Fresh

Situation: Want to wipe everything and start over

1. Fork or create new
2. Deploy and choose "Replace existing"
3. Don't check "Preserve data"
4. Old data becomes inaccessible

What to do: Replace without Persistence

Result: Brand new app, empty database!

Warning: Without keeping old database, old data is NOT deleted but becomes orphaned (can’t access it from new app).

Scenario 4: First Time Going Live

Situation: Built app, ready to launch

What to do: First Deploy
1. Build your app
2. Test in preview
3. Click "Deploy" for first time
4. App goes live with new URL

Result: Live app with empty database!

Decision Tree

Should I Deploy, Redeploy, or Replace?

Is this your first time deploying?
→ YES → Use "Deploy" (First Deploy)
→ NO → ↓

Do you just have code changes to push?
→ YES → Use "Redeploy"
→ NO → ↓

Did you fork to rebuild/fix major issues?
→ YES → ↓
  Do you need to keep your data?
  → YES → Replace with "Preserve data" ✅
  → NO → Replace without "Preserve data" ❌

Best Practices

Do This

For Regular Updates:

1. Make changes in development
2. Test in preview
3. Redeploy
4. Data automatically preserved

For Major Changes:

1. Fork if needed
2. Test thoroughly in preview
3. Decide: keep data or start fresh?
4. Deploy accordingly

For Secrets:

1. Set initial secrets in .env before first deploy
2. Update secrets via platform, not .env
3. New secrets can be added via .env on redeploy

Avoid This

Don’t:

• Forget to check “preserve data” if you need it
• Expect .env changes to update existing secrets
• Delete production app without backing up data

Data Safety Checklist

Before deploying:

• Know which deployment method you’re using
• Understand if data will be preserved
• If replacing, decided on whether to keep data or not
• Backed up important data (if starting fresh)
• Tested thoroughly in preview
• Checked secrets are correct
• Ready for production traffic

Common Questions

Will redeploy delete my database?

No! Redeploy NEVER deletes your data.

Your database and all data are 100% preserved on redeploy.

Only code changes are deployed.

How do I update a secret in production?

You can’t update existing secrets via .env on redeploy.

To update an existing secret:

1. Access deployment settings
2. Find secret management section
3. Update the secret value directly

Or contact support for help.

What happens to old data when I replace deployment?

Depends on your choice:

With “Preserve data” checked:

• Data is transferred to new app
• All data accessible

Without “Preserve data” checked:

• Old database becomes orphaned
• New app gets empty database
• Old data still exists but inaccessible

Can I deploy a fork as a separate app?

Yes! Just deploy without choosing “Replace existing.”

This creates a completely separate app with:

• New URL
• New database
• Independent from original

Is preview data the same as production data?

No! They use completely different databases.

Preview: Test database (local to development pod) Production: Real database (MongoDB Atlas)

Changes in preview don’t affect production data.

How do I backup my production data?

Currently, backups are handled by the platform’s MongoDB hosting.

For manual backup:

• Export data via your app’s admin interface
• Use database export tools
• Contact support for database snapshot

Quick Reference

First Deploy

• When: First time deploying
• Creates: Everything new
• Data: Empty database
• Use for: Initial launch

Redeploy

• When: Updating live app
• Updates: Code only
• Data: ✅ Preserved
• Use for: Regular updates

Replace (with persist)

• When: Swapping apps, keep data
• Creates: New app
• Data: ✅ Transferred
• Use for: Major refactor with data

Replace (without persist)

• When: Fresh start
• Creates: New app
• Data: ❌ Not transferred
• Use for: Complete reset

Remember

✅ Redeploy is safe - Data always preserved

✅ Preview ≠ Production - Different databases

✅ Secrets persist - Existing ones not overwritten

✅ Choose carefully - Replacement with/without data

✅ Test in preview first - Before production deploy

❌ Can’t update secrets via .env - Use platform settings

Most important: Redeploy for updates (data safe), Replace only when necessary (check data option!).

Need Help?

Unsure Which to Use?

Ask yourself:
1. Is this my first deploy? → First Deploy
2. Just updating code? → Redeploy
3. Major changes via fork? → Replace (decide on data)

Lost Data After Deployment?

If you replaced without "preserve data":
- Old database still exists (orphaned)
- Contact support to recover
- They may be able to restore connection

Secret Not Updating?

Remember:
- Redeploying doesn't update existing secrets
- Must update via platform settings
- Only NEW secrets get added from .env

Best practice: For 99% of updates, just use Redeploy. It’s safe, preserves all data, and updates your code. Only use Replace when you have a specific reason!