docs: document build output + Cloud troubleshooting (#13774)
This commit is contained in:
Shahed Nasser
GitHub
@@ -17,7 +17,9 @@ A deployment is created from the latest source code of an [environment](../envir
|
||||
|
||||
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?
|
||||
---
|
||||
|
||||
## How are Deployments Created?
|
||||
|
||||
For long-lived environments, Medusa 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, Medusa will create a new Production deployment every time you push a new commit to the `main` branch.
|
||||
|
||||
@@ -25,6 +27,50 @@ For short-lived preview environments, Medusa creates a new environment and deplo
|
||||
|
||||
---
|
||||
|
||||
## Build Process for Deployments
|
||||
|
||||
Before deploying your application on Cloud, Medusa runs the `build` script defined in your project's `package.json` file, which must run the `medusa build` command, among other build steps you may have.
|
||||
|
||||
For example, your `build` script may look like this:
|
||||
|
||||
```json title="package.json"
|
||||
{
|
||||
"scripts": {
|
||||
"build": "medusa build && npm run other-build-steps"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
<Note>
|
||||
|
||||
You can replace `npm run other-build-steps` with the appropriate command for your package manager, such as `yarn other-build-steps`.
|
||||
|
||||
</Note>
|
||||
|
||||
### What Gets Deployed?
|
||||
|
||||
Medusa deploys the contents of the `.medusa/server` directory created by the [build process](!docs!/learn/build). It includes the compiled JavaScript files in your project, the production build of the admin dashboard, and other necessary files to run your Medusa application in production.
|
||||
|
||||
<Note>
|
||||
|
||||
Learn more about the `.medusa/server` directory in the [Build guide](!docs!/learn/build#output-directory-structure).
|
||||
|
||||
</Note>
|
||||
|
||||
So, if you have custom assets like JSON files that your application needs at runtime, make sure to copy them to the `.medusa/server` directory after the `medusa build` command in your `build` script.
|
||||
|
||||
For example, if your application needs a `src/data/custom.json` file at runtime, you can add a script that copies it to `.medusa/server/src/data/custom.json` after the build process is complete.
|
||||
|
||||
You can also customize the Medusa Admin build configurations using the [admin.vite](!docs!/learn/configurations/medusa-config#adminvite) option in your `medusa-config.ts` file.
|
||||
|
||||
<Note type="warning">
|
||||
|
||||
Do not expose sensitive files in your deployments, especially in the `.medusa/server/public` directory, as they will be publicly accessible. Sensitive files include those containing secret API keys, database credentials, or any other confidential information.
|
||||
|
||||
</Note>
|
||||
|
||||
---
|
||||
|
||||
## Find Project Deployments
|
||||
|
||||
You can find the deployments for a project in its dashboard.
|
||||
|
||||
46
www/apps/cloud/app/deployments/troubleshooting/page.mdx
Normal file
46
www/apps/cloud/app/deployments/troubleshooting/page.mdx
Normal file
@@ -0,0 +1,46 @@
|
||||
export const metadata = {
|
||||
title: `Troubleshooting Cloud Deployments`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
In this guide, you'll find solutions to common issues that may arise when deploying your Medusa applications on Cloud.
|
||||
|
||||
## Files Not Found After Deployment
|
||||
|
||||
Before deploying your Medusa application on Cloud, Medusa runs the `build` script defined in your `package.json` file, then copies only the output of the [build process](!docs!/learn/build), which is the `.medusa/server` directory.
|
||||
|
||||
The `.medusa/server` directory holds the compiled JavaScript files of your project, the production build of the admin dashboard, and other necessary files to run your Medusa application in production.
|
||||
|
||||
If you have custom files needed at runtime, such as a `src/data` directory that holds JSON files, modify the `build` script in your `package.json` file to copy these files to the `.medusa/server` directory after the build process.
|
||||
|
||||
For example:
|
||||
|
||||
```json title="package.json"
|
||||
{
|
||||
"scripts": {
|
||||
"postbuild": "cp -r src/data .medusa/server/src/data",
|
||||
"build": "medusa build && npm run postbuild"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
This script copies the `src/data` directory to the `.medusa/server` directory following the build process.
|
||||
|
||||
Learn more in the [Deployments Guide](../page.mdx#build-process-for-deployments).
|
||||
|
||||
<Note>
|
||||
|
||||
You can replace `npm run postbuild` with the appropriate command for your package manager, such as `yarn postbuild`.
|
||||
|
||||
</Note>
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting Other Cloud Deployment Issues
|
||||
|
||||
To troubleshoot other Cloud deployment issues, you can:
|
||||
|
||||
- [Check the build and runtime logs of your deployment](../../logs/page.mdx).
|
||||
- [Refer to Medusa's troubleshooting guides](!resources!/troubleshooting).
|
||||
- Contact support for help.
|
||||
@@ -131,10 +131,7 @@ Once the project is created and deployed, you'll receive a notification in the C
|
||||
|
||||
## Troubleshooting Project Creation
|
||||
|
||||
If you encounter any issues while creating a project:
|
||||
|
||||
- [Check the build and runtime logs of the project's production deployment](../logs/page.mdx).
|
||||
- Contact support for help.
|
||||
If you encounter any issues while creating a project, [check common deployment issues and their solutions](../deployments/troubleshooting/page.mdx)
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -1,9 +1,9 @@
|
||||
export const generatedEditDates = {
|
||||
"app/page.mdx": "2025-09-11T15:21:38.987Z",
|
||||
"app/organization/page.mdx": "2025-06-12T14:43:20.772Z",
|
||||
"app/projects/page.mdx": "2025-10-02T11:49:21.541Z",
|
||||
"app/projects/page.mdx": "2025-10-17T13:38:32.827Z",
|
||||
"app/environments/page.mdx": "2025-10-15T15:25:09.940Z",
|
||||
"app/deployments/page.mdx": "2025-10-15T15:23:16.572Z",
|
||||
"app/deployments/page.mdx": "2025-10-17T14:40:07.793Z",
|
||||
"app/organizations/page.mdx": "2025-10-02T11:31:07.315Z",
|
||||
"app/notifications/page.mdx": "2025-10-15T15:25:33.672Z",
|
||||
"app/database/page.mdx": "2025-10-15T15:20:06.292Z",
|
||||
@@ -23,5 +23,6 @@ export const generatedEditDates = {
|
||||
"app/pricing/page.mdx": "2025-09-05T10:31:59.059Z",
|
||||
"app/sign-up/page.mdx": "2025-10-08T14:40:47.993Z",
|
||||
"app/comparison/page.mdx": "2025-09-30T06:17:40.257Z",
|
||||
"app/billing/plans/page.mdx": "2025-10-08T14:49:27.009Z"
|
||||
"app/billing/plans/page.mdx": "2025-10-08T14:49:27.009Z",
|
||||
"app/deployments/troubleshooting/page.mdx": "2025-10-17T14:44:22.894Z"
|
||||
}
|
||||
@@ -106,7 +106,16 @@ export const generatedSidebars = [
|
||||
"type": "link",
|
||||
"title": "Deployments",
|
||||
"path": "/deployments",
|
||||
"children": []
|
||||
"children": [
|
||||
{
|
||||
"loaded": true,
|
||||
"isPathHref": true,
|
||||
"type": "link",
|
||||
"title": "Troubleshooting",
|
||||
"path": "/deployments/troubleshooting",
|
||||
"children": []
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
@@ -72,6 +72,13 @@ export const sidebar = [
|
||||
type: "link",
|
||||
title: "Deployments",
|
||||
path: "/deployments",
|
||||
children: [
|
||||
{
|
||||
type: "link",
|
||||
title: "Troubleshooting",
|
||||
path: "/deployments/troubleshooting",
|
||||
},
|
||||
],
|
||||
},
|
||||
],
|
||||
},
|
||||
|
||||
Reference in New Issue
Block a user