> ## Documentation Index
> Fetch the complete documentation index at: https://help.emergent.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<CardGroup cols={3}>
  <Card title="First Deploy" icon="circle-plus" color="#10b981">
    Brand new app

    **Fresh database**
  </Card>

  <Card title="Redeploy" icon="arrows-rotate" color="#3b82f6">
    Update existing app

    **Data preserved**
  </Card>

  <Card title="Replace Deployment" icon="right-left" color="#f59e0b">
    Swap apps

    **Optional data transfer**
  </Card>
</CardGroup>

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

<Steps>
  <Step title="New App Identity">
    A unique app record is created
  </Step>

  <Step title="Empty Database">
    A brand new, empty MongoDB database is provisioned
  </Step>

  <Step title="Production Secrets">
    Values from your development `.env` file are saved as production secrets
  </Step>

  <Step title="Live URL">
    A unique URL is generated (like `https://your-app.emergentworks.app`)
  </Step>

  <Step title="Container Image">
    Your code is built and stored in Google Container Registry
  </Step>
</Steps>

### Data State

**Everything is NEW:**

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

<Note>
  **Perfect for:** Launching a brand new app for the first time.
</Note>

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

<CardGroup cols={2}>
  <Card title="MongoDB Data" icon="database" color="#10b981">
    **100% PRESERVED**

    * Same database connection
    * All existing data intact
    * No data loss
    * Users unchanged
    * Records preserved
  </Card>

  <Card title="Secrets" icon="key" color="#3b82f6">
    **PRESERVED + MERGED**

    * Existing secrets preserved
    * Not overwritten
    * Only new keys added
    * Old values kept
  </Card>
</CardGroup>

### 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`

<Warning>
  **Important:** Changing `.env` values won't update existing production secrets. Only new keys are added.
</Warning>

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

<CardGroup cols={2}>
  <Card title="Without Data Persistence" icon="xmark" color="#ef4444">
    **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
  </Card>

  <Card title="With Data Persistence" icon="check" color="#10b981">
    **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
  </Card>
</CardGroup>

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

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

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

<Note>
  **Key Point:** Preview and Production use **completely different databases**. They never share data!
</Note>

## 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>
  **Warning:** Without keeping old database, old data is NOT deleted but becomes orphaned (can't access it from new app).
</Warning>

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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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
  </Accordion>
</AccordionGroup>

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

<Warning>
  **Most important:** Redeploy for updates (data safe), Replace only when necessary (check data option!).
</Warning>

## 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
```

<Info>
  **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!
</Info>