Skip to content

Commit f12fb7d

Browse files
shahednassershahednasser
authored
docs: added cloud deployments guide (medusajs#12755)
* docs: added cloud deployments guide * fixes * fixes * fixes
1 parent 00505b4 commit f12fb7d

File tree

7 files changed

+311
-42
lines changed

7 files changed

+311
-42
lines changed

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

Lines changed: 276 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,276 @@
1+
import { Table } from "docs-ui"
2+
3+
export const metadata = {
4+
title: `Deployments`,
5+
}
6+
7+
# {metadata.title}
8+
9+
In this guide, you'll learn about deployments, how they're created, and how you can troubleshoot them in Cloud.
10+
11+
## Deployments Overview
12+
13+
Each [environment](../environments/page.mdx) has at least one deployment, which is publicly accessible at the [environment's URL](#find-environments-url).
14+
15+
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.
16+
17+
The latest deployment of an environment is the live version of that environment, unless you [redeploy a previous deployment](#redeploy-a-deployment).
18+
19+
### How are Deployments Created?
20+
21+
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.
22+
23+
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.
24+
25+
---
26+
27+
## Find Environment Deployments
28+
29+
You can find the deployments for a project and its environments in the project and environment dashboards.
30+
31+
For example, to find the deployments for the Production environment:
32+
33+
1. [Go to its project's dashboard](../projects/page.mdx#open-project-dashboard).
34+
2. You can go to the latest Production deployment's details by clicking the "Latest Deployment" link in the Production environment card.
35+
36+
![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)
37+
38+
3. To find a list of all deployments, click on the "Production" environment card to open the environment's dashboard.
39+
- The "Latest update" card shows details about the latest deployment.
40+
- The "Deployments" card shows the list of all previous deployments.
41+
42+
![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)
43+
44+
The last step applies to all environments in your project, including custom environments (like Staging) and preview environments.
45+
46+
---
47+
48+
## Find Deployment Details
49+
50+
You'll often need to check a deployment's details, such as its status, commit information, and logs.
51+
52+
To view a deployment's details:
53+
54+
1. [Go to its project's dashboard](../projects/page.mdx#open-project-dashboard).
55+
2. If you're looking for the latest deployment:
56+
- Click the "Latest Deployment" link in its environment's card.
57+
3. If you're looking for an older deployment:
58+
- Click on its environment's card to open its dashboard.
59+
- In the "Deployments" card, click on the deployment you want to view.
60+
61+
This will open the deployment's details page, where you can also see the deployment's commit at the top of the page.
62+
63+
On the deployment details page, you'll find:
64+
65+
![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)
66+
67+
1. **Commit**: The commit that the deployment was created from.
68+
2. **Status**: The current [status](#deployment-statuses-and-lifecycle) of the deployment. For example, "Live" or "Build Failed".
69+
3. **Author**: The GitHub user who pushed the commit that created the deployment.
70+
4. **Build Logs**: The logs from the build process. They are useful to understand why a deployment failed. Learn more in the [Logs](#) guide.
71+
72+
### Switch Between Deployments
73+
74+
The deployment's commit at the top of the Cloud dashboard is also a deployment switcher.
75+
76+
To switch to a different deployment:
77+
78+
1. Click on the deployment's commit at the top of the Cloud dashboard, next to the environment's name.
79+
2. Choose the deployment you want to switch to from the dropdown.
80+
81+
![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)
82+
83+
This will change the view to the selected deployment and you'll see its details and logs.
84+
85+
---
86+
87+
## Access Live Deployment
88+
89+
You can only access a deployment once its status is "Live". You can access it through its environment's URL.
90+
91+
### Find Environment's URL
92+
93+
<Note>
94+
95+
For preview environments, refer to the [Environments](../environments/page.mdx#access-deployed-preview-environment) guide to find the URL of the preview environment.
96+
97+
</Note>
98+
99+
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).
100+
101+
You can also find the URL of a deployment's environment through the Cloud dashboard:
102+
103+
1. Select a project from the [organization's dashboard](../organizations/page.mdx#organization-dashboard).
104+
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.
105+
106+
<Note title="Why are there two URLs?">
107+
108+
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.
109+
110+
</Note>
111+
112+
![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)
113+
114+
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.
115+
116+
![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)
117+
118+
### Access the Deployment's Medusa Admin
119+
120+
To access the Medusa Admin of a live deployment, click on [the environment's URL](#find-environments-url).
121+
122+
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).
123+
124+
### Send Requests to the Deployment
125+
126+
You can send requests to a live deployment's API routes using its URL.
127+
128+
For example, to check the health of the live deployment, you can send a `GET` request to the `/health` endpoint:
129+
130+
```bash
131+
curl https://my-project.medusajs.app/health
132+
```
133+
134+
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).
135+
136+
### Access Deployment's Server through SSH
137+
138+
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.
139+
140+
If this isn't sufficient for your use case, you can [contact support](#) to discuss alternatives.
141+
142+
---
143+
144+
## Deployment Statuses and Lifecycle
145+
146+
A deployment can have one of the following statuses:
147+
148+
<Table>
149+
<Table.Header>
150+
<Table.Row>
151+
<Table.HeaderCell>
152+
Status
153+
</Table.HeaderCell>
154+
<Table.HeaderCell>
155+
Description
156+
</Table.HeaderCell>
157+
</Table.Row>
158+
</Table.Header>
159+
<Table.Body>
160+
<Table.Row>
161+
<Table.Cell>
162+
Building
163+
</Table.Cell>
164+
<Table.Cell>
165+
The deployment is currently being built. This is the initial status of a deployment.
166+
</Table.Cell>
167+
</Table.Row>
168+
<Table.Row>
169+
<Table.Cell>
170+
Build canceled
171+
</Table.Cell>
172+
<Table.Cell>
173+
The build process was canceled due to a newer commit pushed to the branch, which resulted in a new deployment.
174+
</Table.Cell>
175+
</Table.Row>
176+
<Table.Row>
177+
<Table.Cell>
178+
Build failed
179+
</Table.Cell>
180+
<Table.Cell>
181+
The build process failed due to a build error. You can check the [build logs](#) to troubleshoot the issue.
182+
</Table.Cell>
183+
</Table.Row>
184+
<Table.Row>
185+
<Table.Cell>
186+
Awaiting deployment
187+
</Table.Cell>
188+
<Table.Cell>
189+
The deployment has finished building and is waiting to be deployed.
190+
</Table.Cell>
191+
</Table.Row>
192+
<Table.Row>
193+
<Table.Cell>
194+
Deploying
195+
</Table.Cell>
196+
<Table.Cell>
197+
The deployment is currently being deployed.
198+
</Table.Cell>
199+
</Table.Row>
200+
<Table.Row>
201+
<Table.Cell>
202+
Deploy failed
203+
</Table.Cell>
204+
<Table.Cell>
205+
The deployment failed during the deployment process. You can check the [Runtime Logs](#) to troubleshoot the issue.
206+
</Table.Cell>
207+
</Table.Row>
208+
<Table.Row>
209+
<Table.Cell>
210+
Live
211+
</Table.Cell>
212+
<Table.Cell>
213+
The deployment finished successfully and is now the live version of the environment.
214+
</Table.Cell>
215+
</Table.Row>
216+
<Table.Row>
217+
<Table.Cell>
218+
Ready
219+
</Table.Cell>
220+
<Table.Cell>
221+
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.
222+
</Table.Cell>
223+
</Table.Row>
224+
</Table.Body>
225+
</Table>
226+
227+
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.
228+
229+
<Note>
230+
231+
If a deployment is stuck at a status like "Building" or "Deploying" for a long time, [contact support](#) for assistance.
232+
233+
</Note>
234+
235+
![Diagram showcasing the lifecycle of a deployment](https://res.cloudinary.com/dza7lstvk/image/upload/v1750150491/Cloud/deployment-lifecycle_y85gdl.jpg)
236+
237+
---
238+
239+
## Troubleshooting Failed Deployments
240+
241+
### Troubleshooting Build Failures
242+
243+
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.
244+
245+
You can also [contact support](#) for help with the issue, if necessary.
246+
247+
### Troubleshooting Deployment Failures
248+
249+
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.
250+
251+
You can also [contact support](#) for help with the issue, if necessary.
252+
253+
---
254+
255+
## Redeploy a Deployment
256+
257+
You might need to redeploy an old deployment if there are unexpected issues with the current live deployment.
258+
259+
By redeploying a previous deployment, you revert or rollback the live version of its environment to the code in that deployment's commit.
260+
261+
<Note title="Important">
262+
263+
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.
264+
265+
</Note>
266+
267+
To redeploy a deployment:
268+
269+
1. [Go to the deployment's details page](#find-deployment-details).
270+
2. Click the "Redeploy" button at the top right of the page.
271+
272+
![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)
273+
274+
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.
275+
276+
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‎

Lines changed: 13 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -120,25 +120,15 @@ After adding the environment variables, you need to redeploy the environment for
120120

121121
![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)
122122

123-
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).
123+
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.
124124

125125
---
126126

127-
## Access Medusa Admin
127+
## Access Deployed Environment
128128

129-
To access the Medusa Admin of an environment, click on the environment's URL in the environment's card or [dashboard](#open-environment-dashboard).
129+
Once an environment is deployed, you can access it through its URL.
130130

131-
You can then login using the email and password [set in the environment variables](#create-medusa-admin-user-in-environment).
132-
133-
![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)
134-
135-
---
136-
137-
## Access Environment Server through SSH
138-
139-
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.
140-
141-
If this isn't sufficient for your use case, you can [contact support](#) to discuss alternatives.
131+
Learn more about how to access an environment's deployment in the [Deployments](../deployments/page.mdx#access-live-deployment) guide.
142132

143133
---
144134

@@ -314,7 +304,15 @@ You can also view the preview deployment and its status in the comment made on y
314304

315305
### Access Deployed Preview Environment
316306

317-
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.
307+
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).
308+
309+
![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)
310+
311+
This will open the preview environment's Medusa Admin in a new tab, where you can test the changes made in the PR.
312+
313+
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.
314+
315+
You can also [send requests to the preview deployment's API](../deployments/page.mdx#send-requests-to-the-deployment).
318316

319317
### Open Preview Environment Dashboard
320318

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ You can also join an existing organization by [receiving an invite from a user i
2121

2222
---
2323

24-
## Organization View
24+
## Organization Dashboard
2525

2626
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.
2727

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

Lines changed: 4 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -113,31 +113,11 @@ If you encounter any issues while creating a project:
113113

114114
---
115115

116-
## Open Deployed Medusa Admin
116+
## Access Deployed Project
117117

118-
To open the deployed Medusa Admin of a project:
118+
To access the deployed project, you can access the URL of its Production environment.
119119

120-
1. Make sure you're viewing the [correct organization's dashboard in Cloud](../organizations/page.mdx#switch-organization).
121-
2. Open the project's dashboard by clicking on the project card in the organization's dashboard.
122-
3. Click on the URL in the "Production" card of the project's dashboard. It will open the Medusa Admin in a new tab.
123-
124-
![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)
125-
126-
You can then log in using the email and password you set during the project creation.
127-
128-
<Note>
129-
130-
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.
131-
132-
</Note>
133-
134-
---
135-
136-
## Access Server through SSH
137-
138-
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.
139-
140-
If this isn't sufficient for your use case, you can [contact support](#) to discuss alternatives.
120+
Learn more in the [Deployments](../deployments/page.mdx#access-live-deployment) guide.
141121

142122
---
143123

@@ -164,7 +144,7 @@ On the project's dashboard, you can view the following details:
164144
- 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.
165145
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.
166146
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.
167-
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.
147+
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.
168148

169149
### Switch Projects
170150

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

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
export const generatedEditDates = {
22
"app/page.mdx": "2025-06-12T12:31:48.681Z",
33
"app/organization/page.mdx": "2025-06-12T14:43:20.772Z",
4-
"app/projects/page.mdx": "2025-06-13T08:53:08.964Z",
5-
"app/environments/page.mdx": "2025-06-16T13:42:04.870Z"
4+
"app/projects/page.mdx": "2025-06-17T11:20:16.174Z",
5+
"app/environments/page.mdx": "2025-06-17T11:12:50.824Z",
6+
"app/deployments/page.mdx": "2025-06-17T11:17:03.236Z",
7+
"app/organizations/page.mdx": "2025-06-17T10:48:50.969Z"
68
}

0 commit comments

Comments
 (0)