Skip to content

Commit 0823deb

Browse files
shahednassershahednasser
authored
docs: added cloud environments documentation (medusajs#12750)
* initial * finished environments page * fixes * fixes * fix to introduction
1 parent 6a95c1a commit 0823deb

File tree

5 files changed

+408
-2
lines changed

5 files changed

+408
-2
lines changed

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

Lines changed: 392 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,392 @@
1+
import { InlineIcon } from "docs-ui"
2+
import { EllipsisHorizontal } from "@medusajs/icons"
3+
4+
export const metadata = {
5+
title: `Environments`,
6+
}
7+
8+
# {metadata.title}
9+
10+
In this guide, you'll learn about environments, how to create and manage them, and how to use preview environments.
11+
12+
## Environments Overview
13+
14+
A project can have multiple environments, each representing a different stage of your application. For example, you can have a Production environment for your live application, and a Staging environment for testing new features.
15+
16+
Each environment has its own resources, such as a database and server instance. By default, a project has at least a Production environment, and you can create custom environments based on your development needs.
17+
18+
Environments are useful to test changes in production-like conditions before actually pushing them to production. You can test out new features, bug fixes, and integrations without affecting the live application.
19+
20+
### Environment Types
21+
22+
There are two types of environments:
23+
24+
- Long-lived environments: These are environments that you create for specific branches in your GitHub repository, such as Production or Staging environments.
25+
- Short-lived [Preview environments](#preview-environments): These are environments automatically created for each pull request (PR) towards a branch that has a long-lived environment in Cloud. They're created as a preview for the PR, and are destroyed once the PR is merged or closed.
26+
27+
---
28+
29+
## View Project's Environments
30+
31+
To view a project's environments:
32+
33+
1. Make sure you're viewing the [correct organization's dashboard in Cloud](../organizations/page.mdx#switch-organization).
34+
2. Click on the project whose environments you want to view.
35+
36+
In the project's dashboard, you'll find a card for every environment in your project. For example, you may have Production, Staging, and Previews cards.
37+
38+
![Project dashboard showing the environment cards](https://res.cloudinary.com/dza7lstvk/image/upload/v1750081123/Cloud/CleanShot_2025-06-16_at_16.37.50_2x_wgqkws.png)
39+
40+
---
41+
42+
## Create a Long-Lived Environment
43+
44+
It's recommended to create long-lived environments for different stages of your project's development.
45+
46+
For example, you can create a Staging environment to test new features and updates before deploying them to Production. That way, you can test changes in a production-like environment without affecting the live application.
47+
48+
This section explains how to create a long-lived environment in Cloud.
49+
50+
### Prerequisites: Create Environment Branch
51+
52+
A long-lived environment is associated with a specific branch in your GitHub repository. So, before creating an environment, make sure you have the necessary branch for it in your repository.
53+
54+
For example, if you're creating a Staging environment, create and push a `staging` branch in your repository:
55+
56+
```bash
57+
git checkout -b staging # create branch
58+
git push origin staging # push branch to remote
59+
```
60+
61+
### Steps to Create a Long-Lived Environment
62+
63+
To create a long-lived environment:
64+
65+
1. In the [project's dashboard](../projects/page.mdx#open-project-dashboard), click on the "Add environment" button at the top right.
66+
2. In the side window that opens:
67+
- Enter the name of the environment. For example, `Staging`.
68+
- Select the branch you want to associate with this environment. For example, `staging`.
69+
- Set the custom subdomain for the environment. All environments are subdomains of `medusajs.app`. So, if you set the subdomain to `staging-my-project`, the environment's URL will be `staging-my-project.medusajs.app`.
70+
3. Once you're done, click the "Create" button.
71+
72+
![Side window with the form to create an environment](https://res.cloudinary.com/dza7lstvk/image/upload/v1749812846/Cloud/CleanShot_2025-06-13_at_14.04.53_2x_apb634.png)
73+
74+
The created environment will appear in the [project's dashboard](../projects/page.mdx) as a card.
75+
76+
### Trigger Environment Deployment
77+
78+
After creating the environment, you need to trigger its deployment by pushing a commit to the environment's branch (in this example, `staging`).
79+
80+
The first time you push a commit, Cloud will:
81+
82+
- Deploy the environment from the associated branch.
83+
- Set up the database and resources for the environment. These are different from the resources of other environments.
84+
85+
After that, Cloud will automatically deploy the environment whenever you push a new commit to the associated branch.
86+
87+
![Project dashboard showing the created environment](https://res.cloudinary.com/dza7lstvk/image/upload/v1749813096/Cloud/CleanShot_2025-06-13_at_14.11.09_2x_j6uoap.png)
88+
89+
### Create Medusa Admin User in Environment
90+
91+
After the environment is deployed, you need to set the email and password for the environment's Medusa Admin user.
92+
93+
To set the email and password for the admin user:
94+
95+
1. In the [project's dashboard](../projects/page.mdx#open-project-dashboard), click on the environment you just created.
96+
2. In the environment's dashboard, click on the "Settings" tab.
97+
3. In the "Add new environment variables" section, add the following environment variables:
98+
99+
```shell
100+
[email protected]
101+
USER_INITIAL_PASSWORD=secret
102+
```
103+
104+
<Note title="Tip">
105+
106+
You can paste the above variables directly in the Key field and both environment variables will be filled.
107+
108+
</Note>
109+
110+
Make sure to replace the values with your desired email and password.
111+
112+
4. Click the "Save" button to save the environment variables.
113+
114+
### Redeploy Environment
115+
116+
After adding the environment variables, you need to redeploy the environment for the changes to take effect:
117+
118+
1. Go back to the environment's dashboard by clicking the "Overview" tab.
119+
2. Click on the "Redeploy" button to redeploy the environment with the new environment variables.
120+
121+
![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)
122+
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).
124+
125+
---
126+
127+
## Access Medusa Admin
128+
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).
130+
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.
142+
143+
---
144+
145+
## Open Environment Dashboard
146+
147+
On the environment's dashboard, you can view its details, logs, and settings. You can also manage the environment's variables, deployment rules, and database dump.
148+
149+
To open an environment's dashboard:
150+
151+
1. Make sure you're viewing the [correct organization's dashboard in Cloud](../organizations/page.mdx#switch-organization).
152+
2. Click on the project that contains the environment you want to view.
153+
3. In the project's dashboard, click on the environment you want to view.
154+
155+
This will open the environment's dashboard. You can see the environment's name at the top of the Cloud dashboard.
156+
157+
![Environment dashboard with the name at the top left](https://res.cloudinary.com/dza7lstvk/image/upload/v1749813349/Cloud/CleanShot_2025-06-13_at_14.14.32_2x_ttqg3h.png)
158+
159+
### Find Environment Details
160+
161+
On the environment's dashboard, you can find the following details:
162+
163+
![Environment dashboard with sections highlighted](https://res.cloudinary.com/dza7lstvk/image/upload/v1749814360/Cloud/CleanShot_2025-06-13_at_14.27.24_2x_rhpaga.png)
164+
165+
1. **Environment URL**: The URL to access the environment. You can find it below the environment's name.
166+
2. **Environment Status**: The current status of the environment, such as "Live" or "Deploying". You can find it at the top right of the environment's dashboard.
167+
3. **Environment Deployments**: The list of deployments for the environment, including the latest deployment. You can find it in the "Deployments" section of the environment's dashboard.
168+
169+
### Switch Environments
170+
171+
The environment's name at the top of the dashboard is also an environment switcher.
172+
173+
To switch to a different environment:
174+
175+
1. Click on the environment's name at the top of the Cloud dashboard, next to the project name.
176+
2. Choose the environment you want to switch to from the dropdown.
177+
178+
![Environment switcher dropdown at the top of the dashboard](https://res.cloudinary.com/dza7lstvk/image/upload/v1749815237/Cloud/CleanShot_2025-06-13_at_14.46.54_2x_j4848b.png)
179+
180+
This will change the view to the selected environment, and you'll see its details, logs, and settings.
181+
182+
---
183+
184+
## View Environment Logs
185+
186+
You can view build and runtime logs for an environment in the "Logs" section of the environment's dashboard. These logs help you debug issues in your application.
187+
188+
Learn more in the [Logs guide](#).
189+
190+
---
191+
192+
## Manage Environment Variables
193+
194+
In an environment's "Settings" tab, you can manage the environment's variables.
195+
196+
### Add Environment Variables
197+
198+
To add environment variables to an environment:
199+
200+
1. In the [environment's dashboard](#open-environment-dashboard), click on the "Settings" tab.
201+
2. In the "Add new environment variables" section, there are different ways you can add environment variables:
202+
- **Manually**:
203+
- Enter the key and value of the environment variable in the respective fields.
204+
- Click the "Add another" button to add another variable.
205+
- **Paste `.env` format**:
206+
- If you copied environment variables in a `.env` file format, you can paste them directly into the "Key" field. The environment variables will be pre-filled for you.
207+
- **Import `.env` file**:
208+
- If you have a `.env` file that defines your environment variables, click the "Import .env" button to upload the file. The environment variables will be automatically extracted and added to the list.
209+
3. Once you're done, click the "Save" button to save the environment variables.
210+
211+
<Note title="Important">
212+
213+
After adding the environment variables, you must [redeploy the environment](#redeploy-environment) for the changes to take effect.
214+
215+
</Note>
216+
217+
![Environment variables section in the environment's settings tab](https://res.cloudinary.com/dza7lstvk/image/upload/v1749816071/Cloud/CleanShot_2025-06-13_at_15.00.54_2x_dbdxl4.png)
218+
219+
### Edit Environment Variables
220+
221+
To edit an environment variable:
222+
223+
1. In the [environment's dashboard](#open-environment-dashboard), click on the "Settings" tab.
224+
2. In the "Environment variables" section, find the variable you want to edit.
225+
3. Click the <InlineIcon Icon={EllipsisHorizontal} alt="three-dots" /> icon at the variable's right side.
226+
4. Choose "Edit" from the dropdown menu.
227+
228+
![Edit environment variable in the environment's settings tab](https://res.cloudinary.com/dza7lstvk/image/upload/v1749816223/Cloud/CleanShot_2025-06-13_at_15.03.21_2x_a38dch.png)
229+
230+
5. In the side window that opens, you can edit the variable's key, value, and whether it's sensitive.
231+
6. Once you're done, click the "Save" button.
232+
233+
<Note title="Important">
234+
235+
After editing the environment variable, you must [redeploy the environment](#redeploy-environment) for the changes to take effect.
236+
237+
</Note>
238+
239+
![Edit environment variable side window](https://res.cloudinary.com/dza7lstvk/image/upload/v1749816330/Cloud/CleanShot_2025-06-13_at_15.05.20_2x_ps04uf.png)
240+
241+
### Delete Environment Variables
242+
243+
To delete an environment variable:
244+
245+
1. In the [environment's dashboard](#open-environment-dashboard), click on the "Settings" tab.
246+
2. In the "Environment variables" section, find the variable you want to delete.
247+
3. Click the <InlineIcon Icon={EllipsisHorizontal} alt="three-dots" /> icon at the variable's right side.
248+
4. Choose "Delete" from the dropdown menu.
249+
250+
<Note title="Important">
251+
252+
After deleting the environment variable, you must [redeploy the environment](#redeploy-environment) for the changes to take effect.
253+
254+
</Note>
255+
256+
![Delete environment variable in the environment's settings tab](https://res.cloudinary.com/dza7lstvk/image/upload/v1749816223/Cloud/CleanShot_2025-06-13_at_15.03.21_2x_a38dch.png)
257+
258+
### Export Environment Variables
259+
260+
You can export an environment's variables as a `.env` file. This is useful for debugging issues that require you to have the same environment variables.
261+
262+
To export an environment's variables:
263+
264+
1. In the [environment's dashboard](#open-environment-dashboard), click on the "Settings" tab.
265+
2. In the "Environment variables" section, click on the "Export .env" button at the top right of the section.
266+
267+
A file download will start with the name `env.txt`, which contains the environment variables in `.env` format.
268+
269+
You can rename the file to `.env` and use it in your local development.
270+
271+
![Export env button in the environment's settings tab](https://res.cloudinary.com/dza7lstvk/image/upload/v1749816591/Cloud/CleanShot_2025-06-13_at_15.09.37_2x_k5t0nz.png)
272+
273+
---
274+
275+
## Manage Environment's Deployment Rules
276+
277+
In an environment's "Settings" tab, you can manage the deployment rules for the environment. Deployment rules allow you to control how and when deployments are triggered for the environment.
278+
279+
Learn more in the [Deployments](#) guide.
280+
281+
---
282+
283+
## Import and Export Environment's Database Dump
284+
285+
In the environment's "Settings" tab, you can export a database dump of the environment. This is useful for backing up the environment's data, debugging issues, or migrating the data to another environment.
286+
287+
You can also import a database dump to use existing data that you have, or to restore the environment to a previous state.
288+
289+
Learn more in the [Database](#) guide.
290+
291+
---
292+
293+
## Preview Environments
294+
295+
A preview environment is a short-lived environment that is automatically created for each pull request (PR) opened towards a branch with a long-lived environment in Cloud.
296+
297+
Preview environments facilitate testing a PR's changes in a live environment before merging them. They allow you to test changes in an environment that closely resembles the target long-lived environment.
298+
299+
### View Preview Environments
300+
301+
To view the preview environments for a project, go to the [project's dashboard](../projects/page.mdx#open-project-dashboard). You'll see a "Previews" card with all the preview environments for the project.
302+
303+
![Project dashboard with the Previews card highlighted](https://res.cloudinary.com/dza7lstvk/image/upload/v1750081308/Cloud/CleanShot_2025-06-16_at_16.41.30_2x_ocwoqf.png)
304+
305+
### Create Preview Environment
306+
307+
To create a new preview environment, create a PR towards a branch that has a long-lived environment in Cloud, such as Production.
308+
309+
Cloud will automatically create a preview environment for the PR and deploy the changes to that environment. Everytime you push a new commit to the PR, Cloud will redeploy the preview environment with the latest changes.
310+
311+
You can also view the preview deployment and its status in the comment made on your PR in GitHub.
312+
313+
![Preview environment deployment comment in GitHub PR](https://res.cloudinary.com/dza7lstvk/image/upload/v1749817407/Cloud/CleanShot_2025-06-13_at_15.23.10_2x_rbjorr.png)
314+
315+
### Access Deployed Preview Environment
316+
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.
318+
319+
### Open Preview Environment Dashboard
320+
321+
Similar to long-lived environments, you can open a preview environment's dashboard to view its details, logs, and edit its settings.
322+
323+
To open a preview environment's dashboard:
324+
325+
1. Go to its [project's dashboard](../projects/page.mdx#open-project-dashboard).
326+
2. In the "Previews" card, click on the preview environment you want to view.
327+
328+
Then, you can manage the preview environment just like any other long-lived environment, as mentioned throughout this guide. You can [manage its environment variables](#manage-environment-variables), [deployment rules](#manage-environments-deployment-rules), and [import/export its database dump](#import-and-export-environments-database-dump).
329+
330+
![Preview environment dashboard](https://res.cloudinary.com/dza7lstvk/image/upload/v1749817815/Cloud/CleanShot_2025-06-13_at_15.29.58_2x_h9vn34.png)
331+
332+
### Manage Shared Previews Settings
333+
334+
While you can manage each preview environment's settings individually, you can also manage shared settings between all preview environments in the project. By using the shared settings, you don't need to replicate the same settings for each preview environment.
335+
336+
For example, you can define environment variables that are common to all preview environments.
337+
338+
To manage the shared settings for preview environments:
339+
340+
1. In a [project's dashboard](../projects/page.mdx#open-project-dashboard), click on the "Settings" tab.
341+
2. Choose the "Previews" tab from the sidebar.
342+
3. In the Previews settings, you can:
343+
- Manage environment variables, as explained in the [Manage Environment Variables](#manage-environment-variables) section. All preview environments created after making changes will inherit these variables.
344+
- Specify which database to create the preview environment's database from. By default, a new database will be created from the Production environment's database. You can change this to use a different environment's database, such as Staging.
345+
346+
<Note>
347+
348+
Making changes to the shared settings will affect all preview environments created after the changes. Existing preview environments will not be affected by the changes.
349+
350+
</Note>
351+
352+
![Previews settings in the project's settings tab](https://res.cloudinary.com/dza7lstvk/image/upload/v1749818069/Cloud/CleanShot_2025-06-13_at_15.34.15_2x_zdh3ha.png)
353+
354+
### Preview Environment's Database
355+
356+
Each preview environment has its own resources, including its own database, separate from the production environment.
357+
358+
By default, the preview environment's database will be replicated from the Production environment's database. This means you can test changes in the preview environment with the same data in production, without actually affecting the production database.
359+
360+
You can change the environment from which the preview environment's database is replicated in the [shared Previews settings](#manage-shared-previews-settings).
361+
362+
#### Preview Environment Inactivity
363+
364+
Since Preview environments are only meant for testing, they are put to sleep after ten minutes of inactivity.
365+
366+
So, if you're testing scheduled jobs or events, they may not work as expected in preview environments. They will work as expected in long-lived environments, such as Staging or Production.
367+
368+
### Delete Preview Environment
369+
370+
Preview environments are automatically deleted when their PR is merged or closed. However, you can also delete them manually if needed.
371+
372+
To delete a preview environment, you can follow the same steps in the [Delete an Environment](#delete-an-environment) section.
373+
374+
---
375+
376+
## Delete an Environment
377+
378+
<Note title="Danger" type="warning">
379+
380+
Deleting an environment will delete all its resources and settings, including its database and environment variables. This action is irreversible. You won't be able to recover any data after deletion.
381+
382+
</Note>
383+
384+
You can delete any environment in your project, except for the Production environment.
385+
386+
To delete an environment:
387+
388+
1. In the environment's dashboard, click on the "Settings" tab.
389+
2. Scroll down to the "Delete environment" section.
390+
3. Click the "Delete Environment" button.
391+
392+
![Delete environment button in the environment's settings tab](https://res.cloudinary.com/dza7lstvk/image/upload/v1749816910/Cloud/CleanShot_2025-06-13_at_15.14.50_2x_qm8hfi.png)

0 commit comments

Comments
 (0)