Self-host Mercur

This guide covers the general steps to self-host a Mercur marketplace. Mercur is a Medusa plugin, so deployment follows Medusa’s model, with one addition: the Vendor panel is a separate app. Apply these steps to the hosting provider of your choice.

What you’ll deploy

A Mercur marketplace has several parts.

PostgreSQL: the primary database.
Redis: session storage, the event bus, the workflow engine, and caching.
Mercur API: a Medusa server running the Mercur plugin. You deploy it twice, one instance in server mode and one in worker mode.
Admin panel: served by the API server.
Vendor panel: a separate static app that talks to the Vendor API.
Storefront (optional): your own frontend on the Store API.

Server mode handles API requests and serves the Admin panel. Worker mode runs background work such as scheduled jobs and subscribers. Choose a host with at least 2GB of RAM per instance.

1. Configure the API for production

Set three values in medusa-config.ts so the same build can run as either a server or a worker.

medusa-config.ts

module.exports = defineConfig({
  projectConfig: {
    // ...
    redisUrl: process.env.REDIS_URL,
    workerMode: process.env.MEDUSA_WORKER_MODE as "shared" | "worker" | "server",
  },
  admin: {
    disable: process.env.DISABLE_MEDUSA_ADMIN === "true",
  },
})

The Admin panel is served by the server instance, so you disable it on the worker instance. redisUrl moves sessions, events, and the workflow engine onto Redis.

2. Add a predeploy script

Run migrations before the app starts in production. Add a predeploy script to package.json.

package.json

{
  "scripts": {
    "predeploy": "medusa db:migrate"
  }
}

3. Use production modules

The default project ships modules meant for development, such as the local file provider. Swap them for production-ready ones and register them alongside withMercur in medusa-config.ts.

Redis cache, event bus, and workflow engine: move caching, events, and workflow state off the local process.
Redis locking provider: coordinate work safely across instances.
S3 file provider: store uploads durably.
A notification provider such as SendGrid or Resend, for transactional email.

4. Set environment variables

Set these on each API instance.

Variable	Description
`DATABASE_URL`	PostgreSQL connection string
`REDIS_URL`	Redis connection string
`JWT_SECRET`	Secret for signing auth tokens
`COOKIE_SECRET`	Secret for signing session cookies
`MEDUSA_WORKER_MODE`	`server` on the server instance, `worker` on the worker instance
`DISABLE_MEDUSA_ADMIN`	`false` on the server, `true` on the worker
`STORE_CORS` / `ADMIN_CORS` / `AUTH_CORS`	Allowed origins for the storefront, panels, and auth

5. Deploy the API

Deploy the same build as two instances.

Build the app

Run bun run build to compile the server and the Admin panel.

Run migrations

The predeploy script runs medusa db:migrate. Run it once before starting.

Start the server instance

Set MEDUSA_WORKER_MODE=server and DISABLE_MEDUSA_ADMIN=false. This instance serves the API and the Admin panel.

Start the worker instance

Set MEDUSA_WORKER_MODE=worker and DISABLE_MEDUSA_ADMIN=true. This instance runs jobs and subscribers.

6. Deploy the Vendor panel

The Vendor panel is a separate Vite app. Build it with the API URL configured, then host the static output on any static host or CDN.

The Admin panel ships with the API server. The Vendor panel deploys on its own, the same way a storefront does.

How-Tos

Integrations

Deployment

What you’ll deploy

1. Configure the API for production

2. Add a predeploy script

3. Use production modules

4. Set environment variables

5. Deploy the API

6. Deploy the Vendor panel

Next steps

Medusa Cloud

Stripe Connect

​What you’ll deploy

​1. Configure the API for production

​2. Add a predeploy script

​3. Use production modules

​4. Set environment variables

​5. Deploy the API

​6. Deploy the Vendor panel

​Next steps

Medusa Cloud

Stripe Connect

What you’ll deploy

1. Configure the API for production

2. Add a predeploy script

3. Use production modules

4. Set environment variables

5. Deploy the API

6. Deploy the Vendor panel

Next steps