> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mercurjs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Medusa Cloud deployment

> Deploy Mercur — backend, admin panel, and vendor panel — 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>
  A single Medusa Cloud deployment serves everything: the backend API, the
  **admin panel** at `/dashboard`, and the **vendor panel** at `/seller`. The
  panels are built together with the backend and served from the same origin —
  no separate hosting is needed.
</Info>

## How it works

The `basic` template wires this up out of the box:

* During `build`, the API package builds both panels and bundles their production
  output into the Medusa build artifact (`.medusa/server/dashboards/<name>`), so hosts
  that deploy only the artifact — like Medusa Cloud — carry the panels with it
  (`packages/api/scripts/bundle-dashboards.mjs`).
* At runtime, the `admin-ui` and `vendor-ui` modules detect the bundled builds and
  serve them statically at their configured paths (`/dashboard`, `/seller`).
* The panels bake the backend URL at build time from the `MERCUR_BACKEND_URL`
  environment variable. Because they are served from the backend's own origin, all
  API calls are same-origin — no cross-site cookie or CORS gymnastics.

Medusa Cloud builds the monorepo with `NODE_ENV=production`. In that mode the build
**fails fast** when `MERCUR_BACKEND_URL` is missing instead of shipping panels that
silently point at `http://localhost:9000` — so make sure to set it as described below.

## Prerequisites

* A Mercur project created with [`@mercurjs/cli`](/rc/learn/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

<Steps>
  <Step title="Import your repository">
    From the Medusa Cloud dashboard, choose **Import your existing repository into the Cloud** (the Mercur project lives in your own GitHub repo, not in the bundled DTC/B2B starters).

    <img src="https://mintcdn.com/mercur/CSC8qfjkjrhAGVwE/images/v2/cloud_1.png?fit=max&auto=format&n=CSC8qfjkjrhAGVwE&q=85&s=9218fa1e5e518d08ccfd513e94de52d7" alt="Medusa Cloud welcome screen" width="1876" height="1190" data-path="images/v2/cloud_1.png" />
  </Step>

  <Step title="Pick the repository">
    On the **Repository** step, make sure the Medusa Cloud GitHub app is installed, pick your Mercur repository from the list, and click **Continue**.

    <img src="https://mintcdn.com/mercur/CSC8qfjkjrhAGVwE/images/v2/cloud_2.png?fit=max&auto=format&n=CSC8qfjkjrhAGVwE&q=85&s=a9eb5cd6b9fd01c575803a5d0d6dbab5" alt="Choose repository" width="2792" height="1834" data-path="images/v2/cloud_2.png" />
  </Step>

  <Step title="Configure the project">
    On the **Configure** step, fill in:

    * **Project name** and **Custom subdomain**. The subdomain determines your backend URL (`https://<subdomain>.medusajs.app`) — you will reference it in the environment variables below.
    * **Region** closest to your users.
    * **Medusa root directory**: `/packages/api`.
    * **Initial user** — the first admin email and password.

    Leave **Storefront root directory** empty — the Mercur basic template doesn't ship a storefront.

    <img src="https://mintcdn.com/mercur/CSC8qfjkjrhAGVwE/images/v2/cloud_3.png?fit=max&auto=format&n=CSC8qfjkjrhAGVwE&q=85&s=971375c5a6f2aef7497f683bd760a899" alt="Configure project — name, region, Medusa root directory" width="2798" height="1844" data-path="images/v2/cloud_3.png" />
  </Step>

  <Step title="Set environment variables">
    Scroll down to **Environment variables** and add the **Backend Environment Variables** below. Medusa Cloud provisions the database, Redis, and file storage automatically, so you don't need to set those.

    <img src="https://mintcdn.com/mercur/CSC8qfjkjrhAGVwE/images/v2/cloud_4.png?fit=max&auto=format&n=CSC8qfjkjrhAGVwE&q=85&s=840e1ebbf8dd29c7cf640f76150163c4" alt="Environment variables" width="2774" height="1710" data-path="images/v2/cloud_4.png" />

    Only the following variables should be set:

    ```bash theme={null}
    # Panels (build-time): the deployed backend origin, baked into the admin and
    # vendor panels. Enable the **Build** toggle for this variable — the panels
    # read it while they are being built, not at runtime.
    MERCUR_BACKEND_URL=https://<your-subdomain>.medusajs.app

    # CORS — the panels are served from the backend's own origin, so it is enough
    # to list that origin (plus your storefront URL in STORE_CORS, if you have one)
    STORE_CORS=https://<your-subdomain>.medusajs.app
    ADMIN_CORS=https://<your-subdomain>.medusajs.app
    VENDOR_CORS=https://<your-subdomain>.medusajs.app
    AUTH_CORS=https://<your-subdomain>.medusajs.app

    # Secrets
    JWT_SECRET=
    COOKIE_SECRET=

    # Vendor panel URL used in seller emails and onboarding flows
    MERCUR_VENDOR_URL=https://<your-subdomain>.medusajs.app/seller

    # 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=
    ```

    <Warning>
      `MERCUR_BACKEND_URL` must have the **Build** toggle enabled in the Medusa Cloud
      environment-variable settings. Without it, the production build stops with a clear
      error rather than baking the localhost default into the panels.
    </Warning>

    <Info>
      For Stripe setup, including which keys go where and how to wire both webhooks,
      see the [Stripe Connect integration
      guide](/rc/resources/integrations/stripe-connect).
    </Info>
  </Step>

  <Step title="Create and deploy">
    Click **Create**. The build and deploy process will start and can take a few minutes to complete.
  </Step>
</Steps>

You can change these variables later from the project's 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. Remember that `MERCUR_BACKEND_URL` is baked into the panels at build time — changing it requires a redeploy.

## After deployment

Once the build succeeds, everything is served from `https://<your-subdomain>.medusajs.app`:

| Surface      | URL                                               |
| ------------ | ------------------------------------------------- |
| Backend API  | `https://<your-subdomain>.medusajs.app`           |
| Admin panel  | `https://<your-subdomain>.medusajs.app/dashboard` |
| Vendor panel | `https://<your-subdomain>.medusajs.app/seller`    |

Open the admin panel and sign in with the **Initial user** you configured in the setup step. If a panel shows a "Dashboard not built" page, the bundling step did not run — check the deployment's build logs for output from `bundle-dashboards`.

<Tip>
  Prefer hosting the panels separately (for example on Vercel or Netlify)? That
  still works: deploy `apps/admin` and `apps/vendor` as static Vite builds, set
  `MERCUR_BACKEND_URL` (or `VITE_MERCUR_BACKEND_URL`) to the backend URL at build
  time, and add the panel URLs to the backend's `ADMIN_CORS`, `VENDOR_CORS`, and
  `AUTH_CORS` variables.
</Tip>

## FAQ

<AccordionGroup>
  <Accordion title="A panel shows a 'Dashboard not built' page — what went wrong?">
    The bundling step didn't run during the build. Check the deployment's build logs for output from `bundle-dashboards`; the most common cause is a build that failed earlier (often a missing `MERCUR_BACKEND_URL` with the Build toggle off).
  </Accordion>

  <Accordion title="I changed MERCUR_BACKEND_URL but the panels still call the old URL">
    The backend URL is **baked into the panels at build time**, not read at runtime. After changing the variable, trigger a redeploy so the panels rebuild with the new value.
  </Accordion>

  <Accordion title="Do I need to configure a database or Redis?">
    No — Medusa Cloud provisions Postgres, Redis, and file storage automatically and injects their connection variables. Only set the variables listed in the setup step.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Stripe Connect" href="/rc/resources/integrations/stripe-connect">
    Wire payments and payouts on the deployed environment.
  </Card>

  <Card title="Build your first marketplace" href="/rc/resources/tutorials/first-marketplace">
    Run the end-to-end flow against your new deployment.
  </Card>
</CardGroup>