Skip to content

The complete open source platform to run your entire marketplace. Storefront, vendor panel, admin console, and integrations in one enterprise-grade platform you own.

feat(templates,docs): bundle admin and vendor panels in api Dockerfile

vholikfb0e04d71f7f
diff --git a/apps/docs/docs.json b/apps/docs/docs.json
index 10ab757a8..722cd5c38 100644
--- a/apps/docs/docs.json
+++ b/apps/docs/docs.json
@@ -77,7 +77,8 @@
{
"group": "How-to Guides",
"pages": [
- "how-to-guides/stripe-connect-integration"
+ "how-to-guides/stripe-connect-integration",
+ "how-to-guides/medusa-cloud"
]
},
{
@@ -530,7 +531,7 @@
},
{
"source": "/medusa-cloud",
- "destination": "/v1/medusa-cloud"
+ "destination": "/how-to-guides/medusa-cloud"
}
],
"footer": {
diff --git a/apps/docs/how-to-guides/medusa-cloud.mdx b/apps/docs/how-to-guides/medusa-cloud.mdx
new file mode 100644
index 000000000..2faaa6825
--- /dev/null
+++ b/apps/docs/how-to-guides/medusa-cloud.mdx
@@ -0,0 +1,87 @@
+---
+title: "Medusa Cloud deployment"
+description: "Install and deploy Mercur on Medusa Cloud."
+---
+
+## Introduction
+
+[Medusa Cloud](https://cloud.medusajs.com) is a dedicated hosting service for Medusa-based applications. It automatically detects changes on your repository, pulls and builds the code, and provisions a database, Redis, and file storage.
+
+Head to the [Medusa Cloud signup page](https://cloud.medusajs.com/signup) to get started. After registration is complete and your account is active, authorize the Medusa Cloud GitHub app in your organization or personal account.
+
+<Info>
+ Medusa Cloud builds the project with the Dockerfile in `packages/api`, which
+ bundles the backend, the admin panel, and the vendor panel into a single
+ container. Only the storefront needs to be deployed separately.
+</Info>
+
+## Prerequisites
+
+- A Mercur project created with [`@mercurjs/cli`](/getting-started/installation) and pushed to a GitHub repository
+- A [Medusa Cloud](https://cloud.medusajs.com) account with the GitHub app authorized
+- API keys for any third-party services you plan to use (Stripe, Resend, Algolia, etc.)
+
+## Setup
+
+1. On the main dashboard view, click the **Create project** button.
+2. Thanks to the GitHub integration, Medusa Cloud can access your codebase and automatically pull the code. Choose your Mercur repository from the list and click **Continue**.
+ ![Choose repository](/images/cloud_2.png)
+3. Under project details, choose a name for your project. You can also pick a custom subdomain.
+ ![Basic project settings](/images/cloud_3.png)
+4. Head to the **Build details** section. Under **Project root directory** enter `/packages/api`. Then, choose the first admin user credentials.
+ ![Build details](/images/cloud_4.png)
+5. The last configuration step is environment variables. Medusa Cloud automatically provisions a database, Redis, and file storage, so you don't have to configure them.
+ ![Environment variables](/images/cloud_5.png)
+
+Only the following variables should be set:
+
+```bash
+# CORS (point to the URLs that will host your panels and storefront)
+STORE_CORS=
+ADMIN_CORS=
+VENDOR_CORS=
+AUTH_CORS=
+
+# Secrets
+JWT_SECRET=
+COOKIE_SECRET=
+
+# Vendor panel URL used in seller emails and onboarding flows
+MERCUR_VENDOR_URL=
+
+# Stripe (customer payments + Mercur payout provider)
+STRIPE_API_KEY=
+STRIPE_WEBHOOK_SECRET=
+STRIPE_PAYOUT_WEBHOOK_SECRET=
+
+# Email (optional, e.g. Resend)
+RESEND_API_KEY=
+RESEND_FROM_EMAIL=
+
+# Search (optional)
+ALGOLIA_APP_ID=
+ALGOLIA_API_KEY=
+```
+
+<Info>
+ For Stripe setup, including which keys go where and how to wire both webhooks,
+ see the [Stripe Connect integration
+ guide](/how-to-guides/stripe-connect-integration).
+</Info>
+
+6. Click **Create**. The build and deploy process will start and can take a few minutes to complete.
+
+You can change these variables later in environment settings, and switch the deployment branch at any time. Medusa Cloud will automatically pull and rebuild your environment whenever a new commit is pushed to the selected branch.
+
+![ENV settings](/images/cloud_6.png)
+
+## After deployment
+
+Once the build succeeds, a single container exposes the API and both dashboards:
+
+- The API is available at `https://<your-subdomain>.medusajs.app`.
+- The Admin Panel is available at `https://<your-subdomain>.medusajs.app/dashboard`.
+- The Vendor Panel is available at `https://<your-subdomain>.medusajs.app/seller`.
+- Point your storefront deployment at the API URL via its `VITE_MEDUSA_BACKEND_URL` (or equivalent) build-time variable.
+
+The dashboard routes are configured in `packages/api/medusa-config.ts` under the `admin-ui` and `vendor-ui` modules — change `path` there to remap them.
diff --git a/apps/docs/images/cloud_4.png b/apps/docs/images/cloud_4.png
index 47d4353af..724ae6b24 100644
Binary files a/apps/docs/images/cloud_4.png and b/apps/docs/images/cloud_4.png differ
diff --git a/apps/docs/images/cloud_7.png b/apps/docs/images/cloud_7.png
deleted file mode 100644
index d07d8cf12..000000000
Binary files a/apps/docs/images/cloud_7.png and /dev/null differ
diff --git a/templates/basic/packages/api/Dockerfile b/templates/basic/packages/api/Dockerfile
new file mode 100644
index 000000000..9d4b9024b
--- /dev/null
+++ b/templates/basic/packages/api/Dockerfile
@@ -0,0 +1,61 @@
+FROM node:24-alpine AS base
+
+# The api Dockerfile lives in packages/api but must be built from the repository
+# root so the Turborepo workspace context is available. Example:
+# docker build -f packages/api/Dockerfile -t mercur-api .
+
+FROM base AS builder
+# Check https://github.com/nodejs/docker-node/tree/b4117f9333da4138b03a546ec926ef50a31506c3#nodealpine to understand why libc6-compat might be needed.
+RUN apk update
+RUN apk add --no-cache libc6-compat
+WORKDIR /app
+RUN npm install --global [email protected] turbo
+COPY . .
+# Prune the monorepo to the API plus the two dashboard Vite apps. The API's
+# admin-ui and vendor-ui modules serve apps/admin/dist and apps/vendor/dist
+# at /dashboard and /seller, so all three workspaces must be built.
+RUN turbo prune @acme/api @acme/admin @acme/vendor --docker
+
+FROM base AS installer
+RUN apk update
+RUN apk add --no-cache libc6-compat
+WORKDIR /app
+RUN npm install --global [email protected]
+
+# First install dependencies (as they change less often)
+COPY --from=builder /app/out/json/ .
+RUN bun install
+
+# Build the project and its dependencies (api + admin + vendor dist)
+COPY --from=builder /app/out/full/ .
+
+RUN bun run build
+
+FROM base AS runner
+WORKDIR /app
+
+# Install wget for healthcheck and bun for runtime
+RUN apk add --no-cache wget
+RUN npm install --global [email protected]
+
+# Don't run production as root
+RUN addgroup --system --gid 1001 medusa
+RUN adduser --system --uid 1001 medusa
+
+# Ensure the medusa user owns the api and dashboard folders
+RUN mkdir -p /app/packages/api/static /app/apps/admin /app/apps/vendor
+RUN chown -R medusa:medusa /app/packages/api /app/apps
+
+USER medusa
+COPY --from=installer --chown=medusa:medusa /app .
+
+WORKDIR /app/packages/api
+
+EXPOSE 9000
+
+# Run migrations, optionally seed demo data (controlled by SEED_DEMO_DATA env), and start server
+# MIGRATE_LINKS options: "safe" (default), "skip", "all"
+# - safe: auto-creates new links, skips deletions (recommended for most users)
+# - skip: ignores all link operations
+# - all: auto-executes all link operations including deletions (use with caution)
+CMD ["sh", "-c", "case \"$MIGRATE_LINKS\" in skip) LINK_FLAG='--skip-links';; all) LINK_FLAG='--execute-all-links';; *) LINK_FLAG='--execute-safe-links';; esac && bunx medusa db:migrate $LINK_FLAG && if [ \"$SEED_DEMO_DATA\" = \"true\" ]; then bun run seed || true; fi && bun run start"]