asyavee/medusa-store
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

docs: general changes to Cloud docs (#13616)

Browse Source 
* docs: document self serve

* docs: Cloud docs changes

* vale fixes

* vale error fix

* fixes

* added new sections

* generate
This commit is contained in:
Shahed Nasser
2025-09-30 18:37:04 +03:00
committed by GitHub
parent 70d855bd1b
commit a1dd2de0de
20 changed files with 538 additions and 491 deletions
Download Patch File Download Diff File Expand all files Collapse all files
www/apps/cloud/app/comparison/page.mdx
+322
View File
@@ -0,0 +1,322 @@
import { Table } from "docs-ui"
export const metadata = {
title: `Cloud vs Self-Hosting`,
}
# {metadata.title}
In this guide, you'll learn about the main differences between hosting your Medusa application on Cloud and self-hosting it. By the end of this guide, you'll be able to make an informed decision about which option is best for your use case.
## What is Self-Hosting?
Self-hosting means deploying and managing your Medusa application on your own infrastructure or a hosting provider of your choice, such as AWS, Railway, or DigitalOcean.
Developers with infrastructure management experience may consider self-hosting their Medusa application to have greater control over their deployment environment and potentially reduce costs.
However, before choosing self-hosting, it's important to understand the challenges that come with it, the efforts it requires, and whether Cloud can provide a better solution for your needs.
---
## Summary
<Table>
<Table.Header>
<Table.Row>
<Table.HeaderCell>
Concern
</Table.HeaderCell>
<Table.HeaderCell>
Self-Hosting
</Table.HeaderCell>
<Table.HeaderCell>
Cloud
</Table.HeaderCell>
</Table.Row>
</Table.Header>
<Table.Body>
<Table.Row>
<Table.Cell>
[Code Ownership](#code-ownership)
</Table.Cell>
<Table.Cell>
You own and manage your Medusa application code.
</Table.Cell>
<Table.Cell>
You own and manage your Medusa application code.
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
[Configurations](#configurations)
</Table.Cell>
<Table.Cell>
Requires manual configuration of servers, databases, and other services.
</Table.Cell>
<Table.Cell>
Provides pre-configured environments, reducing setup time.
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
[Deployment & Production Readiness](#deployment--production-readiness)
</Table.Cell>
<Table.Cell>
Requires complex setup of the deployment environment and ensuring production readiness.
</Table.Cell>
<Table.Cell>
Provides automated deployment and scaling, making it easier to manage production environments.
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
[Auto-Scaling](#auto-scaling)
</Table.Cell>
<Table.Cell>
Requires manual setup and management of scaling policies and infrastructure.
</Table.Cell>
<Table.Cell>
Automatically scales based on traffic, ensuring optimal performance.
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
[High-Availability](#high-availability)
</Table.Cell>
<Table.Cell>
Requires manual setup and management of redundancy and failover mechanisms.
</Table.Cell>
<Table.Cell>
Provides real-time monitoring and failover mechanisms to ensure high availability.
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
[Performance](#performance)
</Table.Cell>
<Table.Cell>
Requires manual optimization and monitoring to ensure optimal performance.
</Table.Cell>
<Table.Cell>
Provides continuous performance monitoring and optimization.
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
[Developer Experience](#developer-experience)
</Table.Cell>
<Table.Cell>
Limited developer experience due to the lack of features like code previews and staging environments.
</Table.Cell>
<Table.Cell>
Offers GitHub integration, preview and staging environments, and push-to-deploy features, enhancing developer experience and productivity.
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
[Data Backup](#data-backup)
</Table.Cell>
<Table.Cell>
Requires manual setup of reliable data backup and recovery processes.
</Table.Cell>
<Table.Cell>
Provides automated backups and recovery options based on your plan.
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
[Support](#support)
</Table.Cell>
<Table.Cell>
Relies on community support and documentation.
</Table.Cell>
<Table.Cell>
Offers dedicated support, ensuring timely assistance.
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
[Cost](#cost)
</Table.Cell>
<Table.Cell>
Costs will vary based on your chosen infrastructure and usage patterns.
</Table.Cell>
<Table.Cell>
Competitive pricing model with transparent plans.
</Table.Cell>
</Table.Row>
</Table.Body>
</Table>
---
## Code Ownership
Both self-hosting and Cloud allow you to own and manage your Medusa application codebase.
When you deploy your Medusa application on Cloud, you deploy it from your own GitHub repository. The code remains entirely yours. Cloud only manages the deployment and hosting of your application.
---
## Configurations
### Self-Hosting: Manual Configurations
When you **self-host**, you must manually configure the server for production. You also need to configure database connections, event services, locking mechanisms, and other [Infrastructure Modules](!resources!/infrastructure-modules) that your Medusa application may use.
There may also be platform-specific configurations, adding another layer of complexity that will slow down your time to launch. You'll also need to maintain these configurations over time as Medusa updates are released.
### Cloud: Pre-configured Environments
On **Cloud**, Medusa offers:
- Pre-configured environments optimized for Medusa applications with no configuration required on your end.
- Automated setup and management of infrastructure components.
- Integrated services like [PostgreSQL](../database/page.mdx), [Redis](../redis/page.mdx), and [S3](../s3/page.mdx).
All of these features are available out-of-the-box in your Cloud projects. By using Cloud, you can reduce the time and effort required to get your application up and running, allowing you to focus on building and shipping features.
---
## Deployment & Production Readiness
### Self-Hosting: Complex and Time-Consuming Setup
When you **self-host**, you need to manually set up the production environment, including scaling, monitoring, and logging. You'll need to build deployment pipelines and processes to ensure smooth deployments and rollbacks.
Additionally, your self-hosted environment must be production-ready with best security practices, performance optimizations, and high-availability configurations.
Supporting this setup requires extensive knowledge of infrastructure management. You must also dedicate time and resources to maintain the infrastructure.
### Cloud: Automated Deployment
On **Cloud**, Medusa manages your deployment environment and ensures it's optimized for production. Medusa:
- Handles scaling automatically based on your traffic. More information in the [Auto-Scaling](#auto-scaling) section.
- Rolls out your code updates with zero downtime, ensuring a smooth experience for your users.
- Provides [logging](../logs/page.mdx) features to track your application's performance without additional setup.
---
## Auto-Scaling
### Self-Hosting: Manual Setup and Management
Auto-scaling is essential to maintain performance and availability during high traffic periods, such as sales or promotions.
When you **self-host**, you must set up and manage scaling policies and infrastructure manually. You must configure load balancers, auto-scaling groups, and monitoring tools to ensure your application can handle traffic spikes.
If not set up correctly, your application may experience performance degradation or downtime during high traffic periods.
### Cloud: Automatic Scaling
On **Cloud**, Medusa automatically scales your application based on traffic. This ensures optimal performance without manual intervention.
Medusa adjusts the number of instances running your application based on demand, ensuring your users have a seamless experience even during traffic spikes. You don't need to configure or manage any scaling policies or infrastructure, as Medusa handles everything for you.
---
## High-Availability
### Self-Hosting: Risk of Downtime
When you **self-host**, you are responsible for setting up and managing redundancy and failover mechanisms to ensure high availability. You must monitor your application's health and respond to incidents manually.
If your infrastructure fails and you don't have proper failover mechanisms in place, your application may experience downtime, leading to a poor user experience.
### Cloud: Highly Reliable with 24/7 Monitoring
Medusa provides high-availability features on **Cloud** to ensure your application remains online and responsive. Medusa:
- Monitors your application's health 24/7 and automatically responds to incidents.
- Implements failover mechanisms to minimize downtime and ensures your application is always available.
- Offers [SLA-backed response and uptime](../pricing/page.mdx) based on your plan to guarantee your application's availability.
By using Cloud, you can focus on building your application without worrying about downtime or availability issues.
---
## Performance
### Self-Hosting: Manual Optimization
When you **self-host**, you are responsible for optimizing and monitoring your application's performance. You must configure caching mechanisms, database optimizations, and other performance-enhancing techniques.
If not optimized correctly, your application may experience slow response times, leading to a poor user experience.
### Cloud: Continuous Performance Monitoring
Medusa provides continuous performance monitoring and optimization on **Cloud**. Medusa continuously monitors applications to identify performance bottlenecks and build tooling to resolve them.
Cloud users benefit from these optimizations without any additional effort or configuration, ensuring their applications run smoothly and efficiently.
---
## Developer Experience
### Self-Hosting: Slower Developer Experience
When you **self-host**, you may miss out on features like code previews and push-to-deploy, making it difficult to review and ship changes quickly. You'll also find it challenging to reproduce production issues, as you'll need to set up staging environments manually, adding to the complexity.
### Cloud: Enhanced Developer Experience
Medusa enhances the developer experience on **Cloud** by providing features like:
- GitHub integration for [push-to-deploy](../deployments/page.mdx#how-are-deployments-created).
- [Preview environments](../environments/preview/page.mdx) to test changes in pull requests before merging.
- [Staging environments](../environments/page.mdx) to test new features and reproduce issues in a production-like setting.
By using Cloud, you streamline your development workflow and reduce the time and effort required to manage and ship features.
---
## Data Backup
### Self-Hosting: Risky if Not Done Properly
When you **self-host**, you need to set up data backup and recovery processes manually. This includes scheduling regular backups, storing them securely, and testing recovery procedures. Failing to implement a robust backup strategy can lead to data loss in the event of errors or disasters.
### Cloud: Automated Backups and Recovery
Medusa provides automated backups and recovery options on **Cloud** based on your [plan](../pricing/page.mdx). Backups are performed reliably and stored securely, reducing the risk of data loss. You can restore your data if needed without affecting your application's availability.
---
## Support
### Self-Hosting: Community Support
When you **self-host**, you rely on community support and documentation for assistance. While the Medusa community is active and helpful, you may not receive timely responses to critical issues or answers that are specific to your business use case. Limited support may slow down your development and affect your application's reliability.
### Cloud: Dedicated Support
Medusa offers dedicated [support](https://medusajs.com/medusa-support/) options for **Cloud** users based on their [plan](../pricing/page.mdx). You receive timely assistance to help resolve issues, upgrade your application, and improve performance. Medusa provides the necessary resources to maintain and grow your application.
---
## Cost
### Self-Hosting: Variable Costs
When you **self-host**, your costs vary based on your chosen infrastructure and usage patterns. At minimum, you'll need server and worker instances, a PostgreSQL database, and a Redis instance. You'll likely need additional services like S3 for file storage or monitoring tools.
Depending on your traffic and usage, costs can add up quickly, especially if the infrastructure isn't optimized for cost efficiency.
### Cloud: Cost-Competitive Pricing
Medusa offers a cost-competitive pricing model on **Cloud** compared to self-hosting. You can choose a [plan](../pricing/page.mdx) that fits your needs and budget, with the flexibility to scale as your application grows.
---
## Get Started with Cloud
[Sign Up](../sign-up/page.mdx) on Cloud to get started and deploy your first application in minutes.
### Migrate in Two Steps
If you have an existing self-hosted Medusa application, you can migrate it to Cloud by:
1. [Creating a project](../projects/page.mdx) and connecting it to your existing GitHub repository.
2. [Importing your production database](../database/page.mdx#importexport-database-dumps) to Cloud.
You'll then have a fully managed Medusa application deployed on Cloud, with all the benefits mentioned above, including automated deployment, scaling, and enhanced developer experience.
www/apps/cloud/app/organizations/page.mdx
+18 -2
View File
@@ -15,9 +15,25 @@ In Cloud, an organization is a group of users that have access to the same setti
As a user, you must be in an organization to create and deploy projects. A user can be a member of multiple organizations.
You can create a new organization when you sign up for Cloud. This will make you the organization's owner.
---
You can also join an existing organization by [receiving an invite from a user in that organization](#invite-members-to-organization).
## Create or Join an Organization
To get started with Cloud, you need to either create a new organization or [join an existing one](#invite-members-to-organization).
If you don't have a Cloud account, you can [sign up for Cloud](../sign-up/page.mdx) and create a new organization.
To create a new organization when you already have a Cloud account:
1. Click on the <InlineIcon Icon={ChevronUpDown} alt="switch organization" /> icon next to the current organization name at the top left of the Cloud dashboard.
2. Choose "Create Organization" from the dropdown.
3. In the "Setup your organization" step, enter your organization's name and click the "Create" button.
4. In the final step:
- Choose a plan for your organization. By default, the **Hobby** plan is selected. You can change the plan by clicking the "Change plan" link.
- **Payment Details**: Enter your card details. You'll be charged upfront based on the plan you selected once you finish the setup.
- **Billing details**: If you chose the **Pro** plan, enter your billing details, including your legal name and billing email address. These details are used for taxes and invoicing.
- **Billing address**: Enter your billing address. This address is used for generated invoices.
5. Once you're done, click the "Start your X/mo plan" button. Then, Medusa will charge you for the plan you selected, create an organization, and redirect you to your organization's Cloud dashboard.
---
www/apps/cloud/app/page.mdx
+1 -1
View File
@@ -12,7 +12,7 @@ In this guide, you'll learn about Cloud and its features.
## Sign Up for Cloud
Go to [medusajs.com/pricing](https://medusajs.com/pricing/) to learn more about the Cloud plans.
Refer to the [Sign Up for Cloud](./sign-up/page.mdx) guide to get started.
---
www/apps/cloud/app/sign-up/page.mdx
+101
View File
@@ -0,0 +1,101 @@
export const metadata = {
title: `Sign Up for Cloud`,
}
# {metadata.title}
In this guide, you'll learn how to sign up for Cloud. You'll create an organization, choose a plan, and set up billing.
After creating an organization, you can start deploying your Medusa applications on Cloud.
<Note>
If you already have a Cloud account and you want to create a new organization, refer to the [Create an Organization](../organizations/page.mdx#create-or-join-an-organization) guide instead.
</Note>
## Step 1: Create a Cloud Account
To sign up for Cloud, go to [cloud.medusajs.com/signup](https://cloud.medusajs.com/signup).
On this page, you can choose to either sign up with your GitHub account or with your email address.
![Sign up page with GitHub and email options](https://res.cloudinary.com/dza7lstvk/image/upload/v1757581724/Cloud/CleanShot_2025-09-11_at_12.08.08_2x_e6md6c.png)
---
## Step 2: Set Up Your Account
In the next step, you need to enter your account details. These details will be used for your organization as well.
Enter the following details:
- **What should we call you?**: Enter your full name.
- This name will be used as the organization's name. You can change the organization name later in the [organization settings](../organizations/page.mdx#edit-organization-details).
- **Where did you hear about Medusa?**: Select an option from the dropdown menu. This helps us understand how users find out about Medusa.
- **What are you building?**: Select an option from the dropdown menu. This helps us understand what users are building with Medusa. If you don't see an option that fits your use case, select "Other" and provide more details in the text box that appears.
- **News and features**: Keep the switch enabled to receive updates about Medusa, including new features, improvements, and other news. You can disable this option if you prefer not to receive such updates.
Once you're done, click the **Continue** button to proceed to the next step.
![Account details form with name, referral, use case, and newsletter options](https://res.cloudinary.com/dza7lstvk/image/upload/v1757581945/Cloud/CleanShot_2025-09-11_at_12.12.16_2x_t86r6j.png)
---
## Step 3: Set up Payment and Billing
In the last step, you need to choose a plan, enter your payment details, and set up billing details.
### Choose a Plan
By default, the **Hobby** plan is selected. This plan is minimal and allows you to deploy a single Medusa application that is suitable for development and testing purposes.
To change the plan, click on the **Change plan** link. This will open a modal where you can select a different plan.
<Note>
Learn about the different plans and their features in the [Plans guide](../pricing/page.mdx).
</Note>
![Plan section with the Hobby plan selected](https://res.cloudinary.com/dza7lstvk/image/upload/v1757582162/Cloud/CleanShot_2025-09-11_at_12.15.39_2x_ww4ff2.png)
### Enter Payment Details
Next, you need to enter your card details. This is required for all plans.
Once you finish the sign-up, you will be charged upfront for the first month based on the plan you selected. You can learn more about this in the [Billing guide](../billing/page.mdx).
![Payment details form with card number, expiry date, and CVC fields](https://res.cloudinary.com/dza7lstvk/image/upload/v1757582477/Cloud/CleanShot_2025-09-11_at_12.20.06_2x_lzk7gu.png)
### Pro Plan: Billing Details
If you chose the **Pro** plan, you need to enter your billing details that are used for tax purposes.
Enter your legal name and billing email address in this section.
![Billing details form with legal name and billing email fields](https://res.cloudinary.com/dza7lstvk/image/upload/v1757582477/Cloud/CleanShot_2025-09-11_at_12.19.53_2x_dxfziq.png)
### Billing Address
Finally, enter your billing address. This is required for all plans.
Your billing address will be used for your invoices.
![Billing address form with country, address, city, state, and postal code fields](https://res.cloudinary.com/dza7lstvk/image/upload/v1757582478/Cloud/CleanShot_2025-09-11_at_12.20.55_2x_un3emk.png)
### Complete the Sign-Up
Once you're done, click the "Start your X/mo plan" button to complete the sign-up process. The button text will vary based on the plan you selected.
At this point, Medusa will charge your card for the first month based on the plan you selected, and you will be redirected to your organization's Cloud dashboard.
---
## Next Steps
Now that you have signed up for Cloud, you can:
- [Create projects](../projects/page.mdx) to deploy your Medusa applications.
- [Manage your organization](../organizations/page.mdx) settings, including inviting team members.
- [Change your plan](../billing/page.mdx#change-your-organizations-plan) or update your payment details.
www/apps/cloud/generated/edit-dates.mjs
+5 -3
View File
@@ -1,10 +1,10 @@
export const generatedEditDates = {
"app/page.mdx": "2025-09-11T11:20:20.775Z",
"app/page.mdx": "2025-09-11T15:21:38.987Z",
"app/organization/page.mdx": "2025-06-12T14:43:20.772Z",
"app/projects/page.mdx": "2025-09-29T12:03:35.689Z",
"app/environments/page.mdx": "2025-06-25T08:00:05.550Z",
"app/deployments/page.mdx": "2025-06-25T07:57:13.059Z",
"app/organizations/page.mdx": "2025-09-11T14:26:31.848Z",
"app/organizations/page.mdx": "2025-09-11T15:21:38.987Z",
"app/notifications/page.mdx": "2025-06-25T07:27:37.642Z",
"app/database/page.mdx": "2025-08-15T15:30:37.814Z",
"app/redis/page.mdx": "2025-06-25T07:57:23.246Z",
@@ -20,5 +20,7 @@ export const generatedEditDates = {
"app/billing/page.mdx": "2025-09-04T15:25:50.586Z",
"app/usage/page.mdx": "2025-08-25T07:25:54.703Z",
"app/billing/manage/page.mdx": "2025-09-04T14:50:46.747Z",
"app/pricing/page.mdx": "2025-09-05T10:31:59.059Z"
"app/pricing/page.mdx": "2025-09-05T10:31:59.059Z",
"app/sign-up/page.mdx": "2025-09-29T10:16:20.885Z",
"app/comparison/page.mdx": "2025-09-30T06:17:40.257Z"
}
www/apps/cloud/generated/sidebar.mjs
+16
View File
@@ -18,6 +18,14 @@ export const generatedSidebars = [
"title": "Introduction",
"children": []
},
{
"loaded": true,
"isPathHref": true,
"type": "link",
"path": "/sign-up",
"title": "Sign Up",
"children": []
},
{
"loaded": true,
"isPathHref": true,
@@ -25,6 +33,14 @@ export const generatedSidebars = [
"path": "/faq",
"title": "FAQ",
"children": []
},
{
"loaded": true,
"isPathHref": true,
"type": "link",
"path": "/comparison",
"title": "Cloud vs Self Hosting",
"children": []
}
]
},
www/apps/cloud/sidebar.mjs
+10
View File
@@ -14,11 +14,21 @@ export const sidebar = [
path: "/",
title: "Introduction",
},
{
type: "link",
path: "/sign-up",
title: "Sign Up",
},
{
type: "link",
path: "/faq",
title: "FAQ",
},
{
type: "link",
path: "/comparison",
title: "Cloud vs Self Hosting",
},
],
},
{