export const metadata = { title: Preview Environments, }

{metadata.title}

A preview environment is a short-lived Cloud environment that is automatically created for each pull request (PR) opened towards a branch with a long-lived environment in Cloud.

Preview environments facilitate testing a PR's changes in a live environment before merging them. They allow you to test changes in an environment that closely resembles the target long-lived environment.

Each preview environment has its own Medusa backend, admin dashboard, and storefront, along with separate resources like a database and server instance.

<Note>

Learn more about what environments are and their types in the Environments guide.

</Note>

Preview (Short-Lived) Environment Infrastructure

Preview environments are designed for testing changes before merging them into production. So, they have a simpler setup compared to production environments:

Medusa automatically scales preview environments to zero after ten minutes of inactivity. So, if no one is using the preview environment, it will automatically shut down to save resources.
Preview environments run on a single server instance, which is sufficient for testing changes.

Preview Environment Inactivity

Since Preview environments are only meant for testing, they are put to sleep after ten minutes of inactivity.

So, if you're testing scheduled jobs or events, they may not work as expected in preview environments. They will work as expected in long-lived environments, such as Staging or Production.

View Preview Environments

To view the preview environments for a project, go to the project's dashboard. You'll see a "Previews" card with all the preview environments for the project.

Create Preview Environment

To create a new preview environment, create a PR towards a branch that has a long-lived environment in Cloud, such as Production.

Medusa will automatically create a preview environment for the PR and deploy the changes to that environment. Everytime you push a new commit to the PR, Medusa will redeploy the preview environment with the latest changes.

You can also view the preview deployment and its status in the comment made on your PR in GitHub.

Increase Preview Environment Limits

Based on your plan, you may have limits on the number of active preview environments you can have at a time across all projects in your organization.

For example, if your plan allows for one active preview environment, you can only have one open PR with a preview environment at a time. If you open a second PR in any project, the preview environment for that PR will fail to deploy.

You can increase this limit either from the Billing settings or on the project dashboard.

To increase the concurrent previews limit from the project dashboard:

Go to the project's dashboard.
In the "Previews" card, click the "Provision" button.
In the pop-up that opens, you can see how much it would cost to increase the limit.
Click the "Increase limit and deploy preview" button to confirm.

This will increase the concurrent previews limit across projects in your organization, and you can view your updated bill in the Invoices settings.

Open Preview Environment Dashboard

Similar to long-lived environments, you can open a preview environment's dashboard to view its details, logs, and edit its settings.

To open a preview environment's dashboard:

Go to its project's dashboard.
In the "Previews" card, click on the preview environment you want to view.

Then, you can manage the preview environment just like any other long-lived environment. You can manage its environment variables and import/export its database dump.

Access Deployed Preview Environment

Once the preview environment has finished deploying, you can access its Medusa Admin and storefront (if applicable) from the preview environment's dashboard. You can click on the URL of the backend or storefront to open them in a new tab.

To log into the Medusa Admin of the preview environment, use the admin credentials of the Production or associated long-lived environment. If you configured the shared previews settings to use a different environment's database, you can log in with the admin credentials of that environment instead.

You can also send requests to the preview deployment's API.

Preview URL Format

Medusa generates the preview environment URL for the Medusa application by:

Taking the first 42 characters of the PR's branch name.
Appending a dash (-) followed by the project's handle.
- You can find the project's handle in the project dashboard's URL, which is of the format cloud.medusajs.com/:org_id/projects/:project_handle.
Removing unsafe characters.
Adding the medusajs.app subdomain.

For example, if your PR's branch name is feat/product-review and the project's handle is m1234, the URL of the deployed preview environment would be https://featproduct-review-m1234.medusajs.app.

For the storefront, the same format is used, but with a medusajs.site subdomain. For example, the storefront URL could be https://featproduct-review-m1234.medusajs.site.

Manage Domains

Your preview environment has two types of domains:

Medusa-provided subdomains: The default medusajs.app (backend) and medusajs.site (storefront) subdomains assigned to the environment. For example, acme.medusajs.app and acme.medusajs.site.
Custom domains: Your own domain names to serve the backend and storefront instead of the Medusa-provided subdomains. For example, acme.com.

To update these domains, see the Subdomains and Custom Domains guides.

Manage Shared Previews Settings

While you can manage each preview environment's settings individually, you can also manage shared settings between all preview environments in the project. By using the shared settings, you don't need to replicate the same settings for each preview environment.

For example, you can define environment variables that are common to all preview environments.

To manage the shared settings for preview environments:

In a project's dashboard, click on the "Settings" tab.
Choose the "Previews" tab from the sidebar.
In the Previews settings, you can:
- Manage environment variables, as explained in the Manage Environment Variables guide. All preview environments created after making changes will inherit these variables.
- Specify which database to create the preview environment's database from. By default, a new database will be created from the Production environment's database. You can change this to use a different environment's database, such as Staging.

<Note>

Making changes to the shared settings will affect all preview environments created after the changes. Existing preview environments will not be affected by the changes.

</Note>

Preview Environment's Database

Each preview environment has its own resources, including its own database, separate from the production environment.

By default, the preview environment's database will be replicated from the Production environment's database. This means you can test changes in the preview environment with the same data in production, without actually affecting the production database.

You can change the environment from which the preview environment's database is replicated in the shared Previews settings.

Delete Preview Environment

Preview environments are automatically deleted when their PR is merged or closed. However, you can also delete them manually if needed.

To delete a preview environment, you can follow the same steps in the Long-Lived Environment section.