From 03fb24af8d846c88dccc35705e1c65ecf23303ce Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Fri, 20 Jun 2025 11:40:59 +0300 Subject: [PATCH] docs: added cloud infrastructure guide (#12783) * docs: added cloud infrastructure guide * added md route * fixes --- www/apps/cloud/app/infrastructure/page.mdx | 36 +++++++++ .../cloud/app/md-content/[[...slug]]/route.ts | 80 +++++++++++++++++++ www/apps/cloud/app/page.mdx | 8 +- www/apps/cloud/generated/edit-dates.mjs | 5 +- www/apps/cloud/generated/sidebar.mjs | 8 ++ www/apps/cloud/sidebar.mjs | 5 ++ 6 files changed, 134 insertions(+), 8 deletions(-) create mode 100644 www/apps/cloud/app/infrastructure/page.mdx create mode 100644 www/apps/cloud/app/md-content/[[...slug]]/route.ts diff --git a/www/apps/cloud/app/infrastructure/page.mdx b/www/apps/cloud/app/infrastructure/page.mdx new file mode 100644 index 0000000000..142a0c9ff5 --- /dev/null +++ b/www/apps/cloud/app/infrastructure/page.mdx @@ -0,0 +1,36 @@ +export const metadata = { + title: `Infrastructure`, +} + +# {metadata.title} + +In this guide, you'll learn about the infrastructure that powers your Cloud projects. + +## Project's Infrastructure + +Every Cloud project you create is made up of multiple [environments](../environments/page.mdx), each having their own infrastructure. Cloud automatically provisions and manages the infrastructure of every environment, so you don't have to worry about setting up servers or scaling. + +Your project will have at least a production environment, which is your live application. You may create custom [long-lived environments](../environments/page.mdx#create-a-long-lived-environment) for staging or other uses. You may also create [short-lived preview environments](../environments/page.mdx#preview-environments) for testing changes before merging them into production. + +This guide only covers the server specs for production, long-lived, and preview environments. You can also learn about other resources of an environment, such as [database](../database/page.mdx), [redis](../redis/page.mdx), and [S3 storage](../s3/page.mdx). + +--- + +## Production (Long-Lived) Environment Infrastructure + +Production and long-lived environments are stable and scalable, making them ideal for hosting your Medusa applications. Cloud ensures that they're: + +- **Always available with zero-downtime deployments**: Your application will always be available for users, even during deployments. Cloud automatically handles rolling updates without interrupting your users. +- **Automatically scaled to meet peak traffic**: Cloud automatically scales your servers to handle traffic spikes, such as during flash sales or marketing campaigns. Your application can handle sudden increases in traffic without manual intervention. +- **Equipped with server and worker instances**: Your application runs on multiple server instances that handle incoming HTTP requests, while worker instances handle background tasks like scheduled jobs and subscribers. This separation allows your application to handle both web traffic and background processing efficiently. + +--- + +## Preview (Short-Lived) Environment Infrastructure + +Preview environments are designed for testing changes before merging them into production. So, they have a simpler setup compared to production environments: + +- Cloud automatically scales preview environments to zero after ten minutes of inactivity. So, if no one is using the preview environment, it will automatically shut down to save resources. +- Preview environments run on a single server instance, which is sufficient for testing changes. + +The simpler setup is sufficient for testing changes. However, some customizations like scheduled jobs and subscribers may not work as expected since the preview environment may be inactive. You can still use these customizations in long-lived environments normally. \ No newline at end of file diff --git a/www/apps/cloud/app/md-content/[[...slug]]/route.ts b/www/apps/cloud/app/md-content/[[...slug]]/route.ts new file mode 100644 index 0000000000..e1a70695d5 --- /dev/null +++ b/www/apps/cloud/app/md-content/[[...slug]]/route.ts @@ -0,0 +1,80 @@ +import { getCleanMd } from "docs-utils" +import { existsSync } from "fs" +import { unstable_cache } from "next/cache" +import { notFound } from "next/navigation" +import { NextRequest, NextResponse } from "next/server" +import path from "path" +import { + addUrlToRelativeLink, + crossProjectLinksPlugin, + localLinksRehypePlugin, +} from "remark-rehype-plugins" +import type { Plugin } from "unified" + +type Params = { + params: Promise<{ slug: string[] }> +} + +export async function GET(req: NextRequest, { params }: Params) { + const { slug = ["/"] } = await params + + // keep this so that Vercel keeps the files in deployment + const basePath = path.join(process.cwd(), "app") + const filePath = path.join(basePath, ...slug, "page.mdx") + + if (!existsSync(filePath)) { + return notFound() + } + + const cleanMdContent = await getCleanMd_(filePath, { + before: [ + [ + crossProjectLinksPlugin, + { + baseUrl: process.env.NEXT_PUBLIC_BASE_URL, + projectUrls: { + docs: { + url: process.env.NEXT_PUBLIC_DOCS_URL, + path: "", + }, + resources: { + url: process.env.NEXT_PUBLIC_RESOURCES_URL, + }, + ui: { + url: process.env.NEXT_PUBLIC_UI_URL, + }, + api: { + url: process.env.NEXT_PUBLIC_API_URL, + }, + "user-guide": { + projectPath: path.resolve("..", "user-guide"), + }, + }, + useBaseUrl: + process.env.NODE_ENV === "production" || + process.env.VERCEL_ENV === "production", + }, + ], + [localLinksRehypePlugin], + ] as unknown as Plugin[], + after: [ + [addUrlToRelativeLink, { url: process.env.NEXT_PUBLIC_BASE_URL }], + ] as unknown as Plugin[], + }) + + return new NextResponse(cleanMdContent, { + headers: { + "Content-Type": "text/markdown", + }, + status: 200, + }) +} + +const getCleanMd_ = unstable_cache( + async (filePath: string, plugins?: { before?: Plugin[]; after?: Plugin[] }) => + getCleanMd({ file: filePath, plugins }), + ["clean-md"], + { + revalidate: 3600, + } +) diff --git a/www/apps/cloud/app/page.mdx b/www/apps/cloud/app/page.mdx index a43dc633a9..3b1a547793 100644 --- a/www/apps/cloud/app/page.mdx +++ b/www/apps/cloud/app/page.mdx @@ -1,12 +1,8 @@ -import { config } from "@/config" - -export const title = `Cloud Documentation` - export const metadata = { - title: `${title} - ${config.titleSuffix}`, + title: `Medusa Cloud Documentation`, } -# {title} +# Cloud Documentation Welcome to the Cloud documentation. Learn about Cloud, its features, how to sign up, and how to use it. diff --git a/www/apps/cloud/generated/edit-dates.mjs b/www/apps/cloud/generated/edit-dates.mjs index 8500cfdb44..795535ce89 100644 --- a/www/apps/cloud/generated/edit-dates.mjs +++ b/www/apps/cloud/generated/edit-dates.mjs @@ -1,5 +1,5 @@ export const generatedEditDates = { - "app/page.mdx": "2025-06-19T14:17:00.893Z", + "app/page.mdx": "2025-06-20T07:56:00.893Z", "app/organization/page.mdx": "2025-06-12T14:43:20.772Z", "app/projects/page.mdx": "2025-06-19T14:17:06.679Z", "app/environments/page.mdx": "2025-06-19T14:15:00.389Z", @@ -15,5 +15,6 @@ export const generatedEditDates = { "app/logs/page.mdx": "2025-06-19T07:44:38.336Z", "app/support/page.mdx": "2025-06-19T11:18:37.253Z", "app/update-medusa/page.mdx": "2025-06-19T11:18:42.545Z", - "app/connect-storefront/page.mdx": "2025-06-19T14:13:06.812Z" + "app/connect-storefront/page.mdx": "2025-06-19T14:13:06.812Z", + "app/infrastructure/page.mdx": "2025-06-20T07:16:54.699Z" } \ No newline at end of file diff --git a/www/apps/cloud/generated/sidebar.mjs b/www/apps/cloud/generated/sidebar.mjs index e3f0b0684b..daa852243d 100644 --- a/www/apps/cloud/generated/sidebar.mjs +++ b/www/apps/cloud/generated/sidebar.mjs @@ -62,6 +62,14 @@ export const generatedSidebars = [ "title": "Resources", "initialOpen": true, "children": [ + { + "loaded": true, + "isPathHref": true, + "type": "link", + "title": "Infrastructure", + "path": "/infrastructure", + "children": [] + }, { "loaded": true, "isPathHref": true, diff --git a/www/apps/cloud/sidebar.mjs b/www/apps/cloud/sidebar.mjs index 9bfec16b17..67d81fd591 100644 --- a/www/apps/cloud/sidebar.mjs +++ b/www/apps/cloud/sidebar.mjs @@ -44,6 +44,11 @@ export const sidebar = [ title: "Resources", initialOpen: true, children: [ + { + type: "link", + title: "Infrastructure", + path: "/infrastructure", + }, { type: "link", title: "Database",