import { Note, Table, InlineIcon, getOsShortcut, Kbd } from "docs-ui" import { XMarkMini } from "@medusajs/icons"

export const metadata = { title: Deployments, }

{metadata.title}

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

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.

If you deployed both the Medusa backend and storefront in an environment, each deployment refers to the backend and storefront. The deployment will also show the status of both the backend and storefront.

How are Deployments Created?

For long-lived environments, Medusa 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, Medusa will create a new Production deployment every time you push a new commit to the main branch.

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

Build Process for Deployments

Medusa Application Only

Before deploying your application on Cloud, Medusa runs the build script defined in your project's package.json file, which must run the medusa build command, among other build steps you may have.

Cloud also supports optional lifecycle scripts that you can define in your backend and storefront package.json files:

• cloud:preinstall: Executed before Cloud installs dependencies
• cloud:prebuild: Executed after dependencies are installed but before the build process starts

For example, your package.json scripts may look like this:

{
  "scripts": {
    "cloud:preinstall": "echo 'Pre-install setup'",
    "cloud:prebuild": "echo 'Pre-build setup'", 
    "build": "medusa build && npm run other-build-steps"
  }
}

You can replace npm run other-build-steps with the appropriate command for your package manager, such as yarn other-build-steps.

Medusa Application with Storefront

If you're deploying both a Medusa application and a storefront on Cloud, Medusa will run the:

1. The build command defined in the backend's package.json file, which must run the medusa build command.
2. The build command relevant to the storefront, depending on the frontend framework you're using. For example, if you're using Next.js for your storefront, Medusa will run the next build command in the storefront's directory.
   • Medusa currently doesn't support custom build scripts for storefronts.

In a monorepo, Medusa doesn't run the build script of your root package.json file. It builds each of the two packages separately, targeting only that package and the workspace packages it depends on. So, the other packages of your monorepo don't enter the build process.

If you're using turbo, Medusa prunes your monorepo down to the package it's building. This means most files at the root of your monorepo aren't available during the build. Learn more in the Prerequisites guide.

Storefront builds and deployments operate independently of the backend status. This means storefront deployments can proceed successfully even if the backend build or deployment fails.

What Gets Deployed in the Medusa Application?

Medusa deploys the contents of the .medusa/server directory of the Medusa application. This directory is created by the build process. It includes the compiled JavaScript files in your project, the production build of the admin dashboard, and other necessary files to run your Medusa application in production.

Learn more about the .medusa/server directory in the Build guide.

So, if you have custom assets like JSON files that your application needs at runtime, make sure to copy them to the .medusa/server directory after the medusa build command in your build script.

For example, if your application needs a src/data/custom.json file at runtime, you can add a script that copies it to .medusa/server/src/data/custom.json after the build process is complete.

You can also customize the Medusa Admin build configurations using the admin.vite option in your medusa-config.ts file.

Do not expose sensitive files in your deployments, especially in the .medusa/server/public directory, as they will be publicly accessible. Sensitive files include those containing secret API keys, database credentials, or any other confidential information.

Find Project Deployments

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

To find the deployments for a project:

You can also navigate to a project's deployments from the command palette. Press <Kbd>{getOsShortcut()}</Kbd> + <Kbd>K</Kbd>, select Deployments, then choose a project.

1. If you're in a different organization, switch to the organization.
2. Click Projects in the sidebar and select the project that contains the environment you want to view.
3. Click Deployments in the sidebar under the project.

You'll find all deployments for the project's environments on the Deployments page, 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. If you're in a different organization, switch to the organization.
2. Click Projects in the sidebar and select the project that contains the environment you want to view.
3. In the project's dashboard, click on the name of the environment. For example, "Production".

You'll find a table of all deployments for the environment, sorted in descending order. For each deployment, you can see its commit, status, and more.

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. If you're in a different organization, switch to the organization.
2. Click Projects in the sidebar and select the project that contains the environment you want to view.
3. Click Deployments in the sidebar under the project.
4. Click on the deployment you want to view. You can also search deployments by their commit hash.

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. Backend: The status of the backend deployment.
2. Storefront: The status of the storefront deployment, if applicable. If the storefront is not deployed, this section will show "Not deployed".
3. Duration: The time it took to build and deploy the deployment.
4. Commit: The commit hash that the deployment was created from, with the name of the branch, the commit message, the author, and when the commit was pushed.

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.

If a deployment is stuck at a status like "Building" or "Deploying" for a long time, contact support for assistance.

Access Live Deployment

Once a deployment's status is "Live", you can access its Medusa Admin, send requests to its API routes, and access its storefront (if applicable).

Learn more in the Access Live Deployment guide.

Troubleshooting Failed Deployments

AI Troubleshooting

When a deployment or its build fails, you can use the "Fix with AI" feature to troubleshoot the issue with the help of the Cloud Assistant. The assistant is always available for failed deployments, allowing you to get assistance whenever there are issues in your deployments. The AI agent will analyze the deployment and build logs, identify the root cause of the issue, and provide you with actionable steps to resolve it.

Learn more in the Fix Deployment and Build Issues with AI guide.

Manually 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 for either the backend or storefront (if applicable), which can help you fix the issue in your code.
• Use the Cloud CLI to stream the build logs and identify the issue. This is useful when debugging the issue with your AI agent.
• Contact support for help with the issue, if necessary.

Manually 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.
• Use the Cloud CLI to stream the deployment logs and identify the issue. This is useful when debugging the issue with your AI agent.
• Contact support for help with the issue, if necessary.

If the logs don't show a cause related to your application, check the Cloud status page for ongoing Cloud incidents. If the Build & Deploy service isn't operational, wait for Cloud to resolve the incident, then redeploy the deployment.

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.

Redeploying a deployment will not revert database changes made in the latest deployment. If you need to revert database changes, contact support for assistance based on your use case.

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 branch that triggers a deployment for an environment, refer to the Change Environment's Branch guide.

Change Environment Deployment Rules

To change the deployment rules for an environment:

1. If you're in a different organization, switch to the organization.
2. Click Projects in the sidebar and select the project that contains the environment.
3. In the project's dashboard, click on the name of the environment. For example, "Production".
4. Click Deployment Rules in the sidebar under the environment's section.
5. In the "Deploy rules" section, you can click Add condition to add a new deployment rule. You can then select:
   • Condition Type: Either Author or Commit Message. This determines what the condition will check for when a new commit is pushed to the environment's branch.
   • Operator: Either Is, Is not, or Contains. This determines how the condition will check the commit's author or message.
   • Value: The value to compare against. For example, if the condition type is Author and the operator is Is, you would enter the author's name here.
   • To remove a condition, click the <InlineIcon Icon={XMarkMini} alt="x" /> icon next to the condition.
6. Click "Save" to apply the changes.

The deployment rules will take effect for next deployments. For example, if you change the author that triggers a deployment, the next deployment will only be created if a commit is pushed to the environment's branch by that author.