import { InlineIcon } from "docs-ui"
import { EllipsisHorizontal, ChevronUpDown } from "@medusajs/icons"

export const metadata = {
  title: `Long-Lived Environments`,
}

# {metadata.title}

In this guide, you'll learn about long-lived environments in Cloud and how to manage them.

Long-lived environments are stable environments that you create for specific branches in your GitHub repository, such as Production or Staging. They allow you to test changes in a production-like environment before deploying them to the live application.

<Note>

Learn more about what environments are and their types in the [Environments](../page.mdx) guide.

</Note>

## Long-Lived Environments Infrastructure

Production and long-lived environments are stable and scalable, making them ideal for hosting your Medusa applications. Medusa ensures that they're:

- **Always available with zero-downtime deployments**: Your application will always be available for users, even during deployments. Medusa automatically handles rolling updates without interrupting your users.
- **Automatically scaled to meet peak traffic**: Medusa automatically scales your servers to handle traffic spikes, such as during flash sales or marketing campaigns. Your application can handle sudden increases in traffic without manual intervention.
- **Equipped with server and worker instances**: Your application runs on multiple server instances that handle incoming HTTP requests, while worker instances handle background tasks like scheduled jobs and subscribers. This separation allows your application to handle both web traffic and background processing efficiently.

---

## Create a Long-Lived Environment on Cloud

It's recommended to create long-lived environments for different stages of your project's development.

For example, you can create a Staging environment to test new features and updates before deploying them to Production. That way, you can test changes in a production-like environment without affecting the live application.

This section explains how to create a long-lived environment in Cloud.

### Prerequisites: Create Environment Branch

A long-lived environment is associated with a specific branch in your GitHub repository. So, before creating an environment, make sure you have the necessary branch for it in your repository.

For example, if you're creating a Staging environment, create and push a `staging` branch in your repository:

```bash
git checkout -b staging # create branch
git push origin staging # push branch to remote
```

### Steps to Create a Long-Lived Environment

To create a long-lived environment:

1. In the [project's dashboard](../../projects/page.mdx#open-project-dashboard), click on the "Add environment" button at the top right.
2. In the side window that opens:
    - **Environment name**: Enter the name of the environment. For example, `Staging`.
    - **Branch**: Select the branch you want to associate with this environment. For example, `staging`.
        - If you don't see the branch you want to use, refresh the page to load the latest branches from your repository.
    - **Custom subdomain**: Set the custom subdomain for the Medusa application (and, subsequently, storefront). Medusa applications are a subdomain of `medusajs.app`, and their storefront is a subdomain of `medusajs.site`.
        - Refer to the [Subdomain Restrictions](../../projects/page.mdx#subdomain-restrictions) guide for reserved subdomains and restrictions.
3. Once you're done, click the "Create" button.

![Side window with the form to create an environment](https://res.cloudinary.com/dza7lstvk/image/upload/v1749812846/Cloud/CleanShot_2025-06-13_at_14.04.53_2x_apb634.png)

The created environment will appear in the [project's dashboard](../../projects/page.mdx) as a card.

### Trigger Environment Deployment

After creating the environment, Medusa will automatically trigger a deployment for the environment using the associated branch (for example, `staging`). This includes:

- Deploying the Medusa application and storefront (if applicable) from the associated branch.
- Setting up the database and resources for the environment. These are different from the resources of other environments.

After that, Medusa will automatically deploy the environment whenever you push a new commit to the associated branch.

### Create Medusa Admin User in Environment

After the environment is deployed, you can log in to the Medusa Admin either with:

1. Your Cloud account by clicking the "Log in with Medusa Cloud" button. A user will be created in the Medusa application with the same email as your Cloud account.
2. The email and password you set using environment variables.

<Note title="Can't find the Log in With Medusa Cloud Button?">

Refer to the [Access Deployment](../../deployments/access/page.mdx#cant-find-the-log-in-with-medusa-cloud-button) guide for troubleshooting steps.

</Note>

You can set the initial admin user's email and password only once if they aren't already set in the environment. Updating these environment variables later won't change the existing admin user's credentials.

To set the initial admin user's email and password:

1. In the [project's dashboard](../../projects/page.mdx#open-project-dashboard), click on the environment you just created.
2. In the environment's dashboard, click on the "Settings" tab.
3. In the "Add new environment variables" section, add the following environment variables:

```shell
USER_INITIAL_EMAIL=admin@test.com
USER_INITIAL_PASSWORD=secret
```

<Note title="Tip">

You can paste the above variables directly in the Key field and both environment variables will be filled.

</Note>

Make sure to replace the values with your desired email and password.

4. Click the "Save" button to save the environment variables.

#### Redeploy Environment

If you added the initial admin user's email and password environment variables, you need to redeploy the environment for the changes to take effect:

1. Go back to the environment's dashboard by clicking the "Overview" tab.
2. Click on the "Redeploy" button to redeploy the environment with the new environment variables.

This will redeploy the environment's live deployment with the new admin user credentials.

![Redeploy button at the top right of the environment's dashboard](https://res.cloudinary.com/dza7lstvk/image/upload/v1767787939/Cloud/CleanShot_2026-01-07_at_14.11.56_2x_bw5p1w.png)

Then, wait for the deployment to finish. You can check its status in the "Deployments" section. Once it's deployed, you can [access the environment](#access-deployed-environment) using its URL.

---

## Access Deployed Environment

Once an environment is deployed, you can access it through its URL.

Learn more about how to access an environment's deployment in the [Access Deployment](../../deployments/access/page.mdx) guide.

---

## Open Environment Dashboard

On the environment's dashboard, you can view its details, logs, and settings. You can also manage the environment's variables, deployment rules, and database dump.

To open an environment's dashboard:

1. Make sure you're viewing the [correct organization's dashboard in Cloud](../../organizations/page.mdx#switch-organization).
2. Click on the project that contains the environment you want to view.
3. In the project's dashboard, click on the environment you want to view.

This will open the environment's dashboard. You can see the environment's name at the top of the Cloud dashboard.

![Environment dashboard with the name at the top left](https://res.cloudinary.com/dza7lstvk/image/upload/v1767787987/Cloud/CleanShot_2026-01-07_at_14.12.59_2x_gocehp.png)

### Find Environment Details

On the environment's dashboard, you can find the following details:

![Environment dashboard with sections highlighted](https://res.cloudinary.com/dza7lstvk/image/upload/v1767788225/Cloud/CleanShot_2026-01-07_at_14.14.22_2x_o0at9s.png)

1. **Environment Medusa Backend URL**: The URL to access the environment. You can find it below the environment's name.
2. **Environment Storefront URL**: The URL to access the environment's storefront. You can find it below the "Storefront" title in the environment's card.
3. **Medusa Application's Deployment Status**: The current status of the latest Medusa application deployment, such as "Live" or "Deploying". You can find it next to the "Backend" title in the environment's card.
4. **Storefront's Deployment Status**: The current status of the latest storefront deployment, such as "Live" or "Deploying". You can find it next to the "Storefront" title in the environment's card.
5. **Environment Deployments**: The list of deployments for the environment, including the latest deployment. You can find it in the "Deployments" section of the environment's dashboard.

<Note title="Why are there two Medusa Backend URLs?">

Aside from the subdomain you set when [creating the environment](../../environments/long-lived/page.mdx#create-a-long-lived-environment), Medusa also provides a unique, randomly generated URL for each environment. Both of these URLs point to the same deployment.

</Note>

### Switch Environments

The environment's name at the top of the dashboard is also an environment switcher.

To switch to a different environment:

1. Click on the <InlineIcon Icon={ChevronUpDown} alt="switch environment" /> icon next to the environment's name at the top of the Cloud dashboard.
2. Choose the environment you want to switch to from the dropdown.

![Environment switcher dropdown at the top of the dashboard](https://res.cloudinary.com/dza7lstvk/image/upload/v1767788275/Cloud/CleanShot_2026-01-07_at_14.17.45_2x_nkemhm.png)

This will change the view to the selected environment, and you'll see its details, logs, and settings.

---

## View Environment Build Logs

You can view runtime logs for an environment in the "Logs" section of the environment's dashboard. These logs help you debug issues in your application.

Learn more in the [Logs guide](../../logs/page.mdx).

---

## Manage Environment Variables

In the environment's "Settings" tab, you can manage the environment variables for the environment's Medusa application and storefront. Environment variables are key-value pairs that store sensitive information, such as API keys, or configurations that your application needs to run.

Learn how to manage environment variables in the [Environment Variables](../environment-variables/page.mdx) guide.

---

## Change Environment's Branch

<Note>

You can't change the branch of preview environments. This section only applies to long-lived environments, such as Production or Staging.

</Note>

In an environment's "Settings" tab, you can manage the deployment rules for the environment. Deployment rules allow you to control how and when deployments are triggered for the environment.

To change the branch associated with an environment using deployment rules:

1. In the [environment's dashboard](#open-environment-dashboard), click on the "Settings" tab.
2. Choose the "Deployment rules" tab from the sidebar.
3. Click the <InlineIcon Icon={EllipsisHorizontal} alt="three-dots" /> icon at the right side of the `branch` rule.
4. Choose "Edit" from the dropdown menu.
5. In the side window that opens, you can change the branch associated with the environment.
6. Once you're done, click the "Save" button.

Changes will take effect the next time you push a commit to the new branch. The environment will be redeployed with the latest changes from the new branch.

![Change environment branch in the environment's settings tab](https://res.cloudinary.com/dza7lstvk/image/upload/v1750170517/Cloud/CleanShot_2025-06-17_at_17.28.25_2x_nfx79a.png)

---

## Import and Export Environment's Database Dump

In the environment's "Settings" tab, you can export a database dump of the environment. This is useful for backing up the environment's data, debugging issues, or migrating the data to another environment.

You can also import a database dump to use existing data that you have, or to restore the environment to a previous state.

Learn more in the [Database](../../database/page.mdx) guide.

---

## Delete an Environment

<Note title="Danger" type="warning">

Deleting an environment will delete all its resources and settings, including its database and environment variables. This action is irreversible. You won't be able to recover any data after deletion.

</Note>

You can delete any environment in your project, except for the Production environment.

To delete an environment:

1. In the environment's dashboard, click on the "Settings" tab.
2. Click the "Delete" button.
