From f12fb7dfad92b26a330583fffc0969c4a308c45c Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Tue, 17 Jun 2025 15:57:41 +0300 Subject: [PATCH] docs: added cloud deployments guide (#12755) * docs: added cloud deployments guide * fixes * fixes * fixes --- www/apps/cloud/app/deployments/page.mdx | 276 ++++++++++++++++++++++ www/apps/cloud/app/environments/page.mdx | 28 +-- www/apps/cloud/app/organizations/page.mdx | 2 +- www/apps/cloud/app/projects/page.mdx | 28 +-- www/apps/cloud/generated/edit-dates.mjs | 6 +- www/apps/cloud/generated/sidebar.mjs | 8 + www/apps/cloud/sidebar.mjs | 5 + 7 files changed, 311 insertions(+), 42 deletions(-) create mode 100644 www/apps/cloud/app/deployments/page.mdx 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. + +![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 + + + +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. + + + +![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: + + + + + + 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. + + + +![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. + + + +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. + +![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. \ 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 ![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). - -![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. +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). + +![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 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. - -![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. - - - -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", + }, ], }, ],