diff --git a/www/apps/cloud/app/deployments/page.mdx b/www/apps/cloud/app/deployments/page.mdx
new file mode 100644
index 0000000000..f80cce546b
--- /dev/null
+++ b/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.
+
+
+
+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](../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:
+
+
+
+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.
+
+
+
+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
+
+
+
+For preview environments, refer to the [Environments](../environments/page.mdx#access-deployed-preview-environment) guide to find the URL of the preview environment.
+
+
+
+An environment's URL is in the format `.medusajs.app`, where `` 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.
+
+
+
+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.
+
+
+
+
+
+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](#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:
+
+
+
+
+
+ Status
+
+
+ Description
+
+
+
+
+
+
+ Building
+
+
+ The deployment is currently being built. This is the initial status of a deployment.
+
+
+
+
+ Build canceled
+
+
+ The build process was canceled due to a newer commit pushed to the branch, which resulted in a new deployment.
+
+
+
+
+ Build failed
+
+
+ The build process failed due to a build error. You can check the [build logs](#) to troubleshoot the issue.
+
+
+
+
+ Awaiting deployment
+
+
+ The deployment has finished building and is waiting to be deployed.
+
+
+
+
+ Deploying
+
+
+ The deployment is currently being deployed.
+
+
+
+
+ Deploy failed
+
+
+ The deployment failed during the deployment process. You can check the [Runtime Logs](#) to troubleshoot the issue.
+
+
+
+
+ Live
+
+
+ The deployment finished successfully and is now the live version of the environment.
+
+
+
+
+ Ready
+
+
+ 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.
+
+
+
+
+
+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.
+
+
+
+
+
+---
+
+## 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.
+
+
+
+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](#find-deployment-details).
+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](#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.
\ No newline at end of file
diff --git a/www/apps/cloud/app/environments/page.mdx b/www/apps/cloud/app/environments/page.mdx
index 0ef17b7d27..2ac4fbfc13 100644
--- a/www/apps/cloud/app/environments/page.mdx
+++ b/www/apps/cloud/app/environments/page.mdx
@@ -120,25 +120,15 @@ After adding the environment variables, you need to redeploy the environment for
-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).
-
-
-
----
-
-## 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.
+Learn more about how to access an environment's deployment in the [Deployments](../deployments/page.mdx#access-live-deployment) guide.
---
@@ -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).
+
+
+
+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
diff --git a/www/apps/cloud/app/organizations/page.mdx b/www/apps/cloud/app/organizations/page.mdx
index 3e621ea077..108dd5d024 100644
--- a/www/apps/cloud/app/organizations/page.mdx
+++ b/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.
diff --git a/www/apps/cloud/app/projects/page.mdx b/www/apps/cloud/app/projects/page.mdx
index b8b67f1820..51695e2a23 100644
--- a/www/apps/cloud/app/projects/page.mdx
+++ b/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).
-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.
-
-
-
-You can then log in using the email and password you set during the project creation.
-
-
-
-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.
-
-
-
----
-
-## 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.
+Learn more in the [Deployments](../deployments/page.mdx#access-live-deployment) guide.
---
@@ -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
diff --git a/www/apps/cloud/generated/edit-dates.mjs b/www/apps/cloud/generated/edit-dates.mjs
index 92879d1c94..3994f9d839 100644
--- a/www/apps/cloud/generated/edit-dates.mjs
+++ b/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/environments/page.mdx": "2025-06-16T13:42:04.870Z"
+ "app/projects/page.mdx": "2025-06-17T11:20:16.174Z",
+ "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"
}
\ No newline at end of file
diff --git a/www/apps/cloud/generated/sidebar.mjs b/www/apps/cloud/generated/sidebar.mjs
index eb8f6df321..a119cf3fa4 100644
--- a/www/apps/cloud/generated/sidebar.mjs
+++ b/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": []
}
]
}
diff --git a/www/apps/cloud/sidebar.mjs b/www/apps/cloud/sidebar.mjs
index ae66f5ff89..5d820f17f4 100644
--- a/www/apps/cloud/sidebar.mjs
+++ b/www/apps/cloud/sidebar.mjs
@@ -32,6 +32,11 @@ export const sidebar = [
title: "Environments",
path: "/environments",
},
+ {
+ type: "link",
+ title: "Deployments",
+ path: "/deployments",
+ },
],
},
],