Long-Lived Environments

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.

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#

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:

Terminal
❯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, click on the "Add environment" button at the top right.
2. In the side window that opens:
   • Enter the name of the environment. For example, Staging.
   • 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.
   • Set the custom subdomain for the environment. All environments are subdomains of medusajs.app. So, if you set the subdomain to staging-my-project, the environment's URL will be staging-my-project.medusajs.app.
     • Refer to the Subdomain Restrictions guide for reserved subdomains and restrictions.
3. Once you're done, click the "Create" button.

The created environment will appear in the project's dashboard as a card.

Trigger Environment Deployment#

After creating the environment, you need to trigger its deployment by pushing a commit to the environment's branch (in this example, staging).

The first time you push a commit, Medusa will:

• Deploy the environment from the associated branch.
• Set 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 need to set the email and password for the environment's Medusa Admin user.

To set the email and password for the admin user:

1. In the project's 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:

Code
1USER_INITIAL_EMAIL=admin@test.com2USER_INITIAL_PASSWORD=secret

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

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

Redeploy Environment#

After adding the 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.

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

Find Environment Details#

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

1. Environment URL: The URL to access the environment. You can find it below the environment's name.
2. Environment Status: The current status of the environment, such as "Live" or "Deploying". You can find it at the top right of the environment's dashboard.
3. 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.

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 environment's name at the top of the Cloud dashboard, next to the project name.
2. Choose the environment you want to switch to from the dropdown.

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

View Environment Logs#

You can view build and 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.

Manage Environment Variables#

In the environment's "Settings" tab, you can manage the environment variables for the environment. 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 guide.

Change Environment's Branch#

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, click on the "Settings" tab.
2. In the "Deployment rules" section, click the icon at the right side of the branch rule.
3. Choose "Edit" from the dropdown menu.
4. In the side window that opens, you can change the branch associated with the environment.
5. 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.

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

Delete an Environment#

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. Scroll down to the "Delete environment" section.
3. Click the "Delete Environment" button.