In the rapidly evolving landscape of e-commerce, MedusaJS has emerged as a formidable force, offering a robust, headless architecture that empowers developers to build highly customized and scalable online stores. As someone deeply invested in optimizing development workflows and deployment strategies, I’ve consistently sought out platforms that simplify infrastructure while maximizing efficiency. This quest led me to Mercur, a meticulously crafted MedusaJS boilerplate, and Railway, a serverless platform that truly redefines deployment simplicity.

This guide isn’t just a set of instructions; it’s a deep dive into leveraging Mercur with Railway to achieve a seamless, production-ready e-commerce backend with minimal operational overhead. We’ll navigate the process from boilerplate acquisition to the nuanced configuration of a multi-service application, reflecting the strategic choices I make in my own projects.

The Strategic Advantage: Why Mercur on Railway?

My experience has shown that the true power of a development stack lies in its ability to abstract away complexity without sacrificing control. Mercur, combined with Railway, embodies this philosophy:

• MedusaJS API as the Core: At its heart, Mercur delivers a pre-configured MedusaJS API, providing the robust commerce capabilities I expect, from product management to order processing, all exposed via a flexible API.

• Integrated Data Persistence with PostgreSQL: Reliability is paramount. Mercur includes seamless PostgreSQL integration, ensuring my data layer is both robust and scalable, a critical foundation for any e-commerce venture.

• Flexible Asset Management with S3-Compatible Storage: For product images and other digital assets, the boilerplate’s support for S3-compatible file storage offers the versatility needed to integrate with services like AWS S3 or Cloudflare R2, which I frequently leverage.

• Performance Enhancement with Redis (Optional): Caching is key to a snappy user experience. The optional Redis integration in Mercur provides an immediate pathway to boost performance and handle real-time data efficiently.

• Streamlined Configuration: The inclusion of preconfigured environment files significantly cuts down on initial setup time, a detail I particularly appreciate when starting new projects or onboarding team members.

• Nixpacks: The Game Changer for Deployment: This is where Railway truly shines. Mercur’s Nixpacks for deployment strategy means I don’t grapple with Dockerfiles. Railway automatically detects and builds the application, providing a lightning-fast, zero-configuration CI/CD experience that accelerates my time to market.

This powerful synergy allows me to channel my energy into developing unique commerce features, confident that the underlying infrastructure is robust, scalable, and elegantly managed.

Prerequisites: Laying the Groundwork

Before we embark on this deployment journey, ensure you have the following essential tools at your disposal. This setup reflects a standard professional workflow:

• A GitHub Account: Indispensable for version control and Railway’s direct repository integration.

• A Railway Account: Your portal to serverless nirvana. If you don’t have one, setting it up is straightforward.

• Pre-existing Railway Project (Optional but Recommended): While you can create a new project during deployment, having a project ready, ideally with a PostgreSQL plugin already enabled, streamlines the process.

• Mercur Railway Boilerplate Repository: Ensure you have either cloned or forked the official Mercur Railway Boilerplate to your own GitHub account. This ensures you have full control over your codebase.

Step-by-Step Deployment Guide

Deploying Mercur to Railway involves a thoughtful, multi-service architecture. This approach, which I’ve found to be highly effective, allows for independent scaling and management of your backend API, admin dashboard, and customer-facing storefront.

1. Acquire the Boilerplate

Your first step is to get the Mercur boilerplate into your development environment:

• Clone Manually: For granular control and local development setup, I typically opt for

git clone https://github.com/dtoyoda10/mercur-railway-boilerplate.git 
cd mercur-railway-boilerplate

• Direct Railway Deployment: For those looking for the absolute quickest start, if the “Deploy on Railway” button is available on the boilerplate repository, it’s an excellent shortcut to initiate the process.

2. Initiating a New Railway Project

Head over to your Railway Dashboard. This is where the magic begins:

• Click on “New Project.”

• Select “Deploy from GitHub Repo.”

• Choose your forked Mercur repository (or the main boilerplate if you’re experimenting).

Railway’s intelligent build system will detect the repository’s structure and automatically configure Nixpacks for an optimized build process.

3. Setting Up Your Services: Backend, Vendor, and Storefront

This is a crucial step for a robust MedusaJS deployment. Instead of a monolithic application, we’ll configure three distinct services on Railway, sharing the same codebase but running independently:

Backend (Medusa API)

This service will host your core Medusa API:

• Right-click on the Railway canvas → Select “New Service.”

• Choose “GitHub Repository” → Select your forked mercur-railway-boilerplate.

• In the Settings tab for this new service:

Watch Path: apps/backend (This tells Railway to only build when changes occur in this specific directory).

Build Command: pnpm run build:api (Executes the build script for your Medusa API).

Start Command: pnpm run start:api (Launches the Medusa API server).

Vendor

• Add another “New Service” from GitHub, selecting the same mercur-railway-boilerplate fork.

• In its Settings tab:

Watch Path: apps/vendor

Build Command: pnpm run build:vendor

Start Command: pnpm run start:vendor

Storefront (Customer-Facing Frontend)

This service will host your customer-facing e-commerce storefront:

• Add yet another “New Service” from GitHub, again selecting the mercur-railway-boilerplate fork.

• In its Settings tab:

Watch Path: apps/store

Build Command: pnpm run build:store

Start Command: pnpm run start:store

This modular approach significantly enhances maintainability and scalability, allowing each component to be deployed and scaled independently based on demand.

4. Integrate the PostgreSQL Plugin

Every robust e-commerce platform needs a reliable database. Here’s how to provision it on Railway:

• Right-click anywhere on the Railway project canvas.

• Click “Database” from the context menu that appears.

• From the popup list of available plugins, select “PostgreSQL.”

Railway will automatically provision a PostgreSQL database for you, generating the essential connection string you’ll need shortly.

5. Configuring Environment Variables

This is where we connect all the pieces. Navigate to the “Variables” tab within your Railway project settings. This step is critical for security and functionality. Here’s the configuration I typically use:

6. Trigger Deployment

With all your services configured and environment variables set, Railway will automatically detect the changes and initiate the deployment process across all three services.

• Monitor the “Deployments” tab in your Railway dashboard to track the build and deployment logs.

• Upon successful completion, Railway will provide a live URL for each of your services. Your backend URL will typically look like:

https://mercur-production.up.railway.app

Verifying Your API Endpoint

To confirm your MedusaJS backend is fully operational and accessible, execute a simple curl command using the live URL provided by Railway for your backend service:

curl https://your-backend-app.up.railway.app/store/products

A successful response, displaying either an empty JSON array [] or a list of any pre-seeded products, confirms that your Medusa API is live and ready to serve requests.

Optional: Initializing Your Database and Creating an Admin User

For a fresh deployment, you’ll need to prepare your database and create an administrator account. I typically do this directly from the Railway shell connected to my backend service:

• Seed the Database: To run any necessary database migrations and seed initial data (if defined in your boilerplate’s seed.json):

pnpm run db:init

• Create an Admin User: To set up your first admin user for the Medusa admin dashboard:

pnpm run db:admin

Follow the prompts to set your administrator credentials.

Conclusion: My Journey to Serverless Bliss (and Yours Too!)

My path to deploying Mercur on Railway wasn’t just about following steps; it was about finding genuine relief from the infrastructure headaches that often plague e-commerce projects. I’ve spent countless hours wrestling with server configurations, trying to coax Docker containers into submission, and debugging cryptic deployment errors that felt like digital riddles. Frankly, my “serverless” dreams often involved a lot more “server” than “less.”

Then came Mercur and Railway. It’s like they read my mind — or perhaps, more accurately, heard my frustrated sighs across the internet. The sheer simplicity of getting a complex MedusaJS backend, complete with a separate admin and storefront, up and running with just a few clicks and some environment variables? It felt almost… illegal. I half-expected a hidden “catch” or a bill that would make my eyes water. Spoiler alert: there wasn’t one.

This setup isn’t just fast; it’s genuinely enjoyable. It frees you from the mundane, allowing you to focus on what actually matters: building an amazing e-commerce experience. No more late-night fights with nginx or wondering why your database isn’t connecting. Just pure, unadulterated development flow.

So, if you’re tired of infrastructure playing hide-and-seek with your sanity, and you’re ready to embrace a future where your e-commerce platform just works, then deploying Mercur to Railway is your next big move. Trust me, your future self (and your sleep schedule) will thank you.

Need Expert Guidance or Hands-on Development?

If you’re building an e-commerce platform with Medusa or Railway and want expert guidance or hands-on development support for advanced features like multi-vendor setups or AI-powered product imports, reach out to me directly. I’m actively developing advanced modules for Mercur to address these exact needs. If these resonate with your project, or if you’re looking for early access to these premium capabilities and custom integration services, don’t hesitate to connect. I’m always keen to hear about the cutting-edge problems you’re trying to solve.

📧 daichi.toyoda7@gmail.com

Let’s build something exceptional together.