docs: added cloud deployments guide (#12755)

* docs: added cloud deployments guide

* fixes

* fixes

* fixes

www/apps/cloud/app/deployments/page.mdx

@@ -0,0 +1,276 @@
+import { Table } from "docs-ui"
+
+export const metadata = {
+  title: `Deployments`,
+}
+
+# {metadata.title}
+
+In this guide, you'll learn about deployments, how they're created, and how you can troubleshoot them in Cloud.
+
+## Deployments Overview
+
+Each [environment](../environments/page.mdx) has at least one deployment, which is publicly accessible at the [environment's URL](#find-environments-url).
+
+A deployment is created from the latest source code of an [environment](../environments/page.mdx)'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](#redeploy-a-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 Environment Deployments
+
+You can find the deployments for a project and its environments in the project and environment dashboards.
+
+For example, to find the deployments for the Production environment:
+
+1. [Go to its project's dashboard](../projects/page.mdx#open-project-dashboard).
+2. You can go to the latest Production deployment's details by clicking the "Latest Deployment" link in the Production environment card.
+
+![Production card highlighted with the latest deployment link](https://res.cloudinary.com/dza7lstvk/image/upload/v1750146946/Cloud/CleanShot_2025-06-17_at_10.54.05_2x_ksw4nk.png)
+
+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.
+
+![Production environment details page with deployment cards highlighted](https://res.cloudinary.com/dza7lstvk/image/upload/v1750151060/Cloud/CleanShot_2025-06-17_at_10.57.49_2x_wqrfzf.png)
+
+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](../projects/page.mdx#open-project-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:
+
+![Deployment details page with key sections highlighted](https://res.cloudinary.com/dza7lstvk/image/upload/v1750147821/Cloud/CleanShot_2025-06-17_at_11.08.58_2x_ea1l8s.png)
+
+1. **Commit**: The commit that the deployment was created from.
+2. **Status**: The current [status](#deployment-statuses-and-lifecycle) 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.
+
+![Deployment switcher at the top of the deployment details page](https://res.cloudinary.com/dza7lstvk/image/upload/v1750148493/Cloud/CleanShot_2025-06-17_at_11.20.16_2x_jegncv.png)
+
+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
+
+<Note>
+
+For preview environments, refer to the [Environments](../environments/page.mdx#access-deployed-preview-environment) guide to find the URL of the preview environment.
+
+</Note>
+
+An environment's URL is in the format `<subdomain>.medusajs.app`, where `<subdomain>` is the subdomain you set either when [creating its project](../projects/page.mdx#create-a-project) or when [creating the environment](../environments/page.mdx#create-a-long-lived-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](../organizations/page.mdx#organization-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.
+
+<Note title="Why are there two URLs?">
+
+Aside from the subdomain you set when [creating the environment](../environments/page.mdx#create-a-long-lived-environment), Cloud also provides a unique, randomly generated URL for each environment. Both of these URLs point to the same deployment.
+
+</Note>
+
+![URL of environment in its card under the environment's name](https://res.cloudinary.com/dza7lstvk/image/upload/v1750157464/Cloud/CleanShot_2025-06-17_at_13.50.38_2x_nfxy1t.png)
+
+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.
+
+![URL of environment in its dashboard under the environment's name](https://res.cloudinary.com/dza7lstvk/image/upload/v1750081257/Cloud/CleanShot_2025-06-16_at_16.40.37_2x_vxupew.png)
+
+### Access the Deployment's Medusa Admin
+
+To access the Medusa Admin of a live deployment, click on [the environment's URL](#find-environments-url).
+
+You can then log in using the email and password set either [during project creation](../projects/page.mdx#create-a-project) or [in the environment's variables](../environments/page.mdx#create-medusa-admin-user-in-environment).
+
+### 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:
+
+```bash
+curl https://my-project.medusajs.app/health
+```
+
+Where `my-project` is the subdomain you set either when [creating the project](../projects/page.mdx#create-a-project) or when [creating the environment](../environments/page.mdx#create-a-long-lived-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:
+
+<Table>
+  <Table.Header>
+    <Table.Row>
+      <Table.HeaderCell>
+        Status
+      </Table.HeaderCell>
+      <Table.HeaderCell>
+        Description
+      </Table.HeaderCell>
+    </Table.Row>
+  </Table.Header>
+  <Table.Body>
+    <Table.Row>
+      <Table.Cell>
+        Building
+      </Table.Cell>
+      <Table.Cell>
+        The deployment is currently being built. This is the initial status of a deployment.
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+        Build canceled
+      </Table.Cell>
+      <Table.Cell>
+        The build process was canceled due to a newer commit pushed to the branch, which resulted in a new deployment.
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+        Build failed
+      </Table.Cell>
+      <Table.Cell>
+        The build process failed due to a build error. You can check the [build logs](#) to troubleshoot the issue.
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+        Awaiting deployment
+      </Table.Cell>
+      <Table.Cell>
+        The deployment has finished building and is waiting to be deployed.
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+        Deploying
+      </Table.Cell>
+      <Table.Cell>
+        The deployment is currently being deployed.
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+        Deploy failed
+      </Table.Cell>
+      <Table.Cell>
+        The deployment failed during the deployment process. You can check the [Runtime Logs](#) to troubleshoot the issue.
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+        Live
+      </Table.Cell>
+      <Table.Cell>
+        The deployment finished successfully and is now the live version of the environment.
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+        Ready
+      </Table.Cell>
+      <Table.Cell>
+        The deployment was previously deployed, but it's not currently the live version of the environment. This happens when a new deployment becomes the live version.
+      </Table.Cell>
+    </Table.Row>
+  </Table.Body>
+</Table>
+
+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.
+
+<Note>
+
+If a deployment is stuck at a status like "Building" or "Deploying" for a long time, [contact support](#) for assistance.
+
+</Note>
+
+![Diagram showcasing the lifecycle of a deployment](https://res.cloudinary.com/dza7lstvk/image/upload/v1750150491/Cloud/deployment-lifecycle_y85gdl.jpg)
+
+---
+
+## 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.
+
+<Note title="Important">
+
+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.
+
+</Note>
+
+To redeploy a deployment:
+
+1. [Go to the deployment's details page](#find-deployment-details).
+2. Click the "Redeploy" button at the top right of the page.
+
+![Redeploy button highlighted on the deployment details page](https://res.cloudinary.com/dza7lstvk/image/upload/v1750156363/Cloud/CleanShot_2025-06-17_at_13.31.17_2x_i6lfit.png)
+
+This will trigger the redeployment process for the selected deployment. The deployment will go through [the same lifecycle](#deployment-statuses-and-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.

www/apps/cloud/app/environments/page.mdx

@@ -120,25 +120,15 @@ After adding the environment variables, you need to redeploy the environment for
 
 ![Redeploy button at the top right of the environment's dashboard](https://res.cloudinary.com/dza7lstvk/image/upload/v1750081204/Cloud/CleanShot_2025-06-16_at_16.39.44_2x_d3yij6.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 Medusa Admin](#access-medusa-admin).
+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 Medusa Admin
+## Access Deployed Environment
 
-To access the Medusa Admin of an environment, click on the environment's URL in the environment's card or [dashboard](#open-environment-dashboard).
+Once an environment is deployed, you can access it through its URL.
 
-You can then login using the email and password [set in the environment variables](#create-medusa-admin-user-in-environment).
+Learn more about how to access an environment's deployment in the [Deployments](../deployments/page.mdx#access-live-deployment) guide.
-
-![URL of environment in its dashboard under the environment's name](https://res.cloudinary.com/dza7lstvk/image/upload/v1750081257/Cloud/CleanShot_2025-06-16_at_16.40.37_2x_vxupew.png)
-
----
-
-## Access Environment Server through SSH
-
-Cloud doesn't support SSH access to the server instance of an environment. 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.
 
 ---
 
@@ -314,7 +304,15 @@ You can also view the preview deployment and its status in the comment made on y
 
 ### Access Deployed Preview Environment
 
-Once the preview environment has finished deploying, you can access its Medusa Admin either through the comment in the PR or by clicking the "Preview" button in the project's dashboard.
+Once the preview environment has finished deploying, you can access its Medusa Admin either through the comment in the PR or by clicking the "Preview" button in the [project's dashboard](../projects/page.mdx#open-project-dashboard).
+
+![Preview button in the project's dashboard](https://res.cloudinary.com/dza7lstvk/image/upload/v1750158423/Cloud/CleanShot_2025-06-17_at_14.06.41_2x_yaw699.png)
+
+This will open the preview environment's Medusa Admin in a new tab, where you can test the changes made in the PR.
+
+To log into the Medusa Admin of the preview environment, use the admin credentials of the Production environment. If you [configured the shared previews settings](#manage-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](../deployments/page.mdx#send-requests-to-the-deployment).
 
 ### Open Preview Environment Dashboard
 

www/apps/cloud/app/organizations/page.mdx

@@ -21,7 +21,7 @@ You can also join an existing organization by [receiving an invite from a user i
 
 ---
 
-## Organization View
+## Organization Dashboard
 
 When you open the Cloud dashboard and log in, you're viewing the projects, resources, and settings of a specific organization. You'll find the name of that organization at the top left of the dashboard.
 

www/apps/cloud/app/projects/page.mdx

@@ -113,31 +113,11 @@ If you encounter any issues while creating a project:
 
 ---
 
-## Open Deployed Medusa Admin
+## Access Deployed Project
 
-To open the deployed Medusa Admin of a project:
+To access the deployed project, you can access the URL of its Production environment.
 
-1. Make sure you're viewing the [correct organization's dashboard in Cloud](../organizations/page.mdx#switch-organization).
+Learn more in the [Deployments](../deployments/page.mdx#access-live-deployment) guide.
-2. Open the project's dashboard by clicking on the project card in the organization's dashboard.
-3. Click on the URL in the "Production" card of the project's dashboard. It will open the Medusa Admin in a new tab.
-
-![The project dashboard with the production deployment URL highlighted](https://res.cloudinary.com/dza7lstvk/image/upload/v1749743331/Cloud/CleanShot_2025-06-12_at_18.48.24_2x_zgo8ws.png)
-
-You can then log in using the email and password you set during the project creation.
-
-<Note>
-
-Lost your Medusa Admin email or password? You can [contact support](#) or [reset your password in the Medusa Admin](!user-guide!/reset-password) if your Medusa project has a Notification Module Provider configured.
-
-</Note>
-
----
-
-## Access Server through SSH
-
-Cloud doesn't support SSH access to the server instances of a project. However, you can still access the server's [runtime and build logs](#) to debug issues in your project.
-
-If this isn't sufficient for your use case, you can [contact support](#) to discuss alternatives.
 
 ---
 
@@ -164,7 +144,7 @@ On the project's dashboard, you can view the following details:
     - The Previews environments are created whenever you create a pull request in the linked GitHub repository. They allow you to preview changes before merging them into the main branch.
 3. **Production URL**: The URL of the project's production deployment. You'll find it in the "Production" card under the title. Clicking it will open the production Medusa Admin in a new tab.
 4. **Repository**: The GitHub repository linked to the project. You'll find it as a "Repository" button at the top right of the project's dashboard. Clicking it will open the repository in a new tab.
-5. **Project Status**: The status of the project, which may be "Live", "Building", or "Failed". The status for the production deployment is shown in the "Production" card of the project's dashboard.
+5. **Production Status**: The status of the project's environment, which may be "Live" or "Building". Learn more in the [Deployments](../deployments/page.mdx#deployment-statuses-and-lifecycle) guide.
 
 ### Switch Projects
 

www/apps/cloud/generated/edit-dates.mjs

@@ -1,6 +1,8 @@
 export const generatedEditDates = {
   "app/page.mdx": "2025-06-12T12:31:48.681Z",
   "app/organization/page.mdx": "2025-06-12T14:43:20.772Z",
-  "app/projects/page.mdx": "2025-06-13T08:53:08.964Z",
+  "app/projects/page.mdx": "2025-06-17T11:20:16.174Z",
-  "app/environments/page.mdx": "2025-06-16T13:42:04.870Z"
+  "app/environments/page.mdx": "2025-06-17T11:12:50.824Z",
+  "app/deployments/page.mdx": "2025-06-17T11:17:03.236Z",
+  "app/organizations/page.mdx": "2025-06-17T10:48:50.969Z"
 }

www/apps/cloud/generated/sidebar.mjs

@@ -44,6 +44,14 @@ export const generatedSidebars = [
             "title": "Environments",
             "path": "/environments",
             "children": []
+          },
+          {
+            "loaded": true,
+            "isPathHref": true,
+            "type": "link",
+            "title": "Deployments",
+            "path": "/deployments",
+            "children": []
           }
         ]
       }

www/apps/cloud/sidebar.mjs

@@ -32,6 +32,11 @@ export const sidebar = [
             title: "Environments",
             path: "/environments",
           },
+          {
+            type: "link",
+            title: "Deployments",
+            path: "/deployments",
+          },
         ],
       },
     ],