Deployments

In this guide, you'll learn about deployments, how they're created, and how you can troubleshoot them in Cloud.

Deployments Overview#

Each environment has at least one deployment, which is publicly accessible at the environment's URL.

A deployment is created from the latest source code of an environment's branch. An environment can have only one live deployment at a time.

The latest deployment of an environment is the live version of that environment, unless you redeploy a previous deployment.

How are Deployments Created?#

For long-lived environments, Cloud creates a new deployment every time you push a new commit to the environment's branch. For example, if your Production environment is connected to the main branch, Cloud will create a new Production deployment every time you push a new commit to the main branch.

For short-lived preview environments, Cloud creates a new environment and deployment when you open a pull request. Cloud will redeploy the preview environment every time you push a new commit to the pull request branch.

Find Project Deployments#

You can find the deployments for a project in its dashboard.

To find the deployments for a project:

1. Make sure you're viewing the correct organization's dashboard in Cloud.
2. Click on the project you want to view its deployments.
3. Click on the "Deployments" tab in the project's dashboard.

You'll find all deployments for the project's environments in the "Deployments" tab, sorted in descending order. For each deployment, you can see its branch, environment, status, and more.

Find Environment Deployments#

You can find the deployments for an environment in the project and environment dashboards.

For example, to find the deployments for the Production environment:

1. Go to its project's dashboard.
2. You can go to the latest Production deployment's details by clicking the "Latest Deployment" link in the Production environment card.

3. To find a list of all deployments, click on the "Production" environment card to open the environment's dashboard.
   • The "Latest update" card shows details about the latest deployment.
   • The "Deployments" card shows the list of all previous deployments.

The last step applies to all environments in your project, including custom environments (like Staging) and preview environments.

Find Deployment Details#

You'll often need to check a deployment's details, such as its status, commit information, and logs.

To view a deployment's details:

1. Go to its project's dashboard.
2. If you're looking for the latest deployment:
   • Click the "Latest Deployment" link in its environment's card.
3. If you're looking for an older deployment:
   • Click on its environment's card to open its dashboard.
   • In the "Deployments" card, click on the deployment you want to view.

This will open the deployment's details page, where you can also see the deployment's commit at the top of the page.

On the deployment details page, you'll find:

1. Commit: The commit that the deployment was created from.
2. Status: The current status of the deployment. For example, "Live" or "Build Failed".
3. Author: The GitHub user who pushed the commit that created the deployment.
4. Build Logs: The logs from the build process. They are useful to understand why a deployment failed. Learn more in the Logs guide.

Switch Between Deployments#

The deployment's commit at the top of the Cloud dashboard is also a deployment switcher.

To switch to a different deployment:

1. Click on the deployment's commit at the top of the Cloud dashboard, next to the environment's name.
2. Choose the deployment you want to switch to from the dropdown.

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

Access Live Deployment#

You can only access a deployment once its status is "Live". You can access it through its environment's URL.

Find Environment's URL#

An environment's URL is in the format <subdomain>.medusajs.app, where <subdomain> is the subdomain you set either when creating its project or when creating the environment.

You can also find the URL of a deployment's environment through the Cloud dashboard:

1. Select a project from the organization's dashboard.
2. In the project's dashboard, find the URL in the environment's card under its name. For example, find the production URL in the Production environment card.

3. You can also click on the environment's name to open its dashboard, where you'll find the URL under the environment's name.

Access the Deployment's Medusa Admin#

To access the Medusa Admin of a live deployment, click on the environment's URL.

You can then log in using the email and password set either during project creation or in the environment's variables.

Send Requests to the Deployment#

You can send requests to a live deployment's API routes using its URL.

For example, to check the health of the live deployment, you can send a GET request to the /health endpoint:

Code
curl https://my-project.medusajs.app/health

Where my-project is the subdomain you set either when creating the project or when creating the environment.

Access Deployment's Server through SSH#

Cloud doesn't support SSH access to the server instance of a deployment. However, you can still access the server's runtime and build logs to debug issues in your application.

If this isn't sufficient for your use case, you can contact support to discuss alternatives.

Deployment Statuses and Lifecycle#

A deployment can have one of the following statuses:

So, the lifecycle of a successful deployment is Building → Awaiting deployment → Deploying → Live. Then, once a new deployment is created, the previous deployment's status changes to Ready.

Troubleshooting Failed Deployments#

Troubleshooting Build Failures#

If a deployment's status is "Build failed", you can check the build logs to understand why it failed. The build logs will show you the errors that occurred during the build process, which can help you fix the issue in your code.

You can also contact support for help with the issue, if necessary.

Troubleshooting Deployment Failures#

If a deployment's status is "Deploy failed", you can check the runtime logs to understand why it failed. The runtime logs will show you the errors that occurred during the deployment process, which can help you fix the issue in your code.

You can also contact support for help with the issue, if necessary.

Redeploy a Deployment#

You might need to redeploy an old deployment if there are unexpected issues with the current live deployment.

By redeploying a previous deployment, you revert or rollback the live version of its environment to the code in that deployment's commit.

To redeploy a deployment:

1. Go to the deployment's details page.
2. Click the "Redeploy" button at the top right of the page.

This will trigger the redeployment process for the selected deployment. The deployment will go through the same lifecycle as a new deployment.

Once the redeployment is complete, the deployment's status will change to "Live" and it will become the new live version of the environment.

Change Deployment Rules#

For each environment, you can change the rules that trigger a new deployment. For example, you can change the branch that the environment is connected to, which changes when a new deployment is created.

To change the deployment rules for an environment:

1. Go to the environment's dashboard.
2. Click on the "Settings" tab.
3. Scroll down to the "Deployment rules" section. You'll find a branch rule in this section.

4. You can edit it by clicking the icon and choosing "Edit" from the dropdown.
5. In the side window that opens, you can change the branch that the environment is connected to. For example, you can change it from main to staging to create a new deployment every time you push a commit to the staging branch.
6. Click "Save" to apply the changes.

The deployment rules will take effect for next deployments. For example, if you change the branch to staging, the next deployment will be created from the latest commit in the staging branch.