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.

**Fresh database**

**Data preserved**

**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

Data State

Everything is NEW:

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

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

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

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

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

Data Survival Guide

Here's what survives in each scenario:

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

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!

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

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

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