diff --git a/www/apps/cloud/app/support/page.mdx b/www/apps/cloud/app/support/page.mdx index 879e6a10f7..0b377ebb2d 100644 --- a/www/apps/cloud/app/support/page.mdx +++ b/www/apps/cloud/app/support/page.mdx @@ -21,7 +21,7 @@ There are two main ways to contact support: through the Cloud dashboard or throu ## Contact Support via Cloud -You'll find a icon at the top right of the Cloud dashboard. Click on it to open the support form. +You can find a icon at the top right of the Cloud dashboard. Click on it to open the support form. In the support form, you can provide a subject and a description of your issue. You can also attach files to help our team understand the problem better. @@ -45,10 +45,10 @@ If your plan includes Slack support, our team will set up a dedicated support ch You can reach out on this channel to receive help from our team. You can: -- Ask questions about using Cloud -- Report issues with the Cloud dashboard -- Get assistance with operations that require actions from our team -- Receive guidance on building custom features +- Ask questions about using Cloud. +- Report issues with the Cloud dashboard. +- Get assistance with operations that require actions from our team. +- Receive guidance on building custom features. Make sure to provide as many details as possible about your issue to receive the best assistance. Also, please follow the guidelines shared in the channel to ensure a smooth support experience. diff --git a/www/apps/cloud/app/update-medusa/page.mdx b/www/apps/cloud/app/update-medusa/page.mdx new file mode 100644 index 0000000000..732567a284 --- /dev/null +++ b/www/apps/cloud/app/update-medusa/page.mdx @@ -0,0 +1,79 @@ +export const metadata = { + title: `Cloud Best Practices: Update Medusa Application`, +} + +# {metadata.title} + +In this guide, you'll learn how to update your Medusa application that is deployed on Cloud. + + + +Refer to the [Update guide](!docs!/learn/update) to learn how to update your Medusa application. + + + +## Why Update Your Medusa Application? + +Medusa regularly releases new versions of the core application with bug fixes, performance improvements, and new features. + +It's highly recommended to always keep your Medusa application up to date. You'll benefit from the latest improvements and security patches. + +--- + +## Update Your Deployed Medusa Application + +This section provides best practices for updating your Medusa application on Cloud and how to update your application in a safe manner. + +### Don't Push Directly to Production + +It's **strongly discouraged** to push a new update directly to your production branch. While Medusa updates are generally safe and stable, it's always a good practice to test the update in a separate environment before deploying it to production. + +By using a separate environment, you mitigate any unexpected issues that may arise during the update process. This way, you ensure that your customizations and configurations work correctly with the new version of Medusa. + +The **recommended** approach is to [create a long-lived environment](../environments/page.mdx#create-a-long-lived-environment), such as Staging. You can push the new update and test it thoroughly in a production-like environment before deploying it to production. + + + +Each environment has its own database, so you can safely update other environments and make data changes without affecting the production environment. + + + +![Diagram showcasing process of deploying to staging then production](https://res.cloudinary.com/dza7lstvk/image/upload/v1750334010/Cloud/deploy-to-staging_d4oyys.jpg) + +Alternatively, you can open a pull request to the production branch, which will [create a preview environment](../environments/page.mdx#preview-environments). The preview environment allows you to test the update before merging it into the production branch. + +![Diagram showcasing process of deploying to preview then production](https://res.cloudinary.com/dza7lstvk/image/upload/v1750334010/Cloud/deploy-to-preview_plpz9z.jpg) + +### Ensure Custom Migrations Have Rollback Methods + +When creating custom migrations, it's important to include both `up` and `down` methods. The `up` method should define the changes to be made to the database schema, while the `down` method should reverse those changes. + +By including both methods, you can easily roll back database changes if you need to revert the application's update. + +If you use the [db\:generate](!resources!/medusa-cli/commands/db#dbgenerate) command to generate migrations, it will automatically create both `up` and `down` methods for you. If you're creating the migrations manually, you can learn more in the [Migrations](!docs!/learn/fundamentals/data-models/write-migration) guide. + +### Update Your Medusa Application + +To update your Medusa application deployed on Cloud: + +1. Update your Medusa application locally either on the long-lived environment's branch (for example, Staging) or in a new branch that will be used to create a pull request. + - To learn how to update your Medusa application, refer to the [Update guide](!docs!/learn/update). It includes all the details you need to update the Medusa application locally. +2. Once you're done updating your application locally, push the changes in `package.json`, lock file (for example, `yarn.lock`), and any other affected files to the branch. + - If you're using a long-lived environment, Cloud will automatically deploy the changes to the branch's environment. + - If you're using a new branch to create a pull request, open the pull request to the production branch. This will create a preview environment that you can use to test the update before merging it into the production branch. + +Then, you can access the environment's [live deployment](../deployments/page.mdx#access-live-deployment) to test the update. You can also use the [build](../logs/page.mdx#view-build-logs) and [runtime](../logs/page.mdx#view-runtime-logs) logs of the environment to debug any issues that occur during the update process or testing. + +### Push Update to Production + +Once you've thoroughly tested the update in your long-lived or preview environment, you can merge the changes into your production branch. + +Cloud will automatically deploy the changes to the production environment. This will update the production's code and database. + +--- + +## Rollback Medusa Application Update + +If you encounter any issues after updating your deployed Medusa application, you can [redeploy a previous deployment](../deployments/page.mdx#redeploy-a-deployment) to roll back the code changes made by the update. + +However, redeploying a previous deployment will not roll back the database changes made by the update. If you need to roll back the database changes, [contact support](../support/page.mdx) for assistance. diff --git a/www/apps/cloud/generated/edit-dates.mjs b/www/apps/cloud/generated/edit-dates.mjs index 1a52977720..0cef367b5d 100644 --- a/www/apps/cloud/generated/edit-dates.mjs +++ b/www/apps/cloud/generated/edit-dates.mjs @@ -13,5 +13,6 @@ export const generatedEditDates = { "app/loyalty-plugin/page.mdx": "2025-06-18T08:28:51.756Z", "app/billing-usage/page.mdx": "2025-06-18T10:35:56.993Z", "app/logs/page.mdx": "2025-06-19T07:44:38.336Z", - "app/support/page.mdx": "2025-06-19T10:29:01.693Z" + "app/support/page.mdx": "2025-06-19T11:18:37.253Z", + "app/update-medusa/page.mdx": "2025-06-19T11:18:42.545Z" } \ No newline at end of file diff --git a/www/apps/cloud/generated/sidebar.mjs b/www/apps/cloud/generated/sidebar.mjs index 3573921cc1..fcb3fa9633 100644 --- a/www/apps/cloud/generated/sidebar.mjs +++ b/www/apps/cloud/generated/sidebar.mjs @@ -162,6 +162,23 @@ export const generatedSidebars = [ "children": [] } ] + }, + { + "loaded": true, + "isPathHref": true, + "type": "category", + "title": "Best Practices", + "initialOpen": true, + "children": [ + { + "loaded": true, + "isPathHref": true, + "type": "link", + "title": "Update Medusa", + "path": "/update-medusa", + "children": [] + } + ] } ] } diff --git a/www/apps/cloud/sidebar.mjs b/www/apps/cloud/sidebar.mjs index a192b747c9..7af20a6c00 100644 --- a/www/apps/cloud/sidebar.mjs +++ b/www/apps/cloud/sidebar.mjs @@ -112,6 +112,18 @@ export const sidebar = [ }, ], }, + { + type: "category", + title: "Best Practices", + initialOpen: true, + children: [ + { + type: "link", + title: "Update Medusa", + path: "/update-medusa", + }, + ], + }, ], }, ]