Self-Hosting a Headless Commerce Solution: Deploying MedusaJS on a VPS with a Next.js Frontend

Introduction to Headless Commerce and the MedusaJS Ecosystem

In the rapidly evolving landscape of digital commerce, traditional monolithic platforms often present significant roadblocks to scaling enterprises. High subscription fees, rigid frontend templates, and restricted backend customization frequently stifle innovation. This has led forward-thinking businesses to adopt headless commerce architectures, which decouple the presentation layer (frontend) from the core commerce logic (backend).

Among the open-source technologies driving this shift, MedusaJS has emerged as a premier open-source alternative to Shopify, built specifically for developers who require flexibility and control. When paired with Next.js—the industry-standard React framework for performance and Search Engine Optimization (SEO)—businesses can create blazing-fast, highly tailored shopping experiences. By self-hosting this stack on a Virtual Private Server (VPS), organizations retain absolute ownership of their data, eliminate vendor lock-in, and optimize infrastructure costs. This guide delivers a comprehensive blueprint for deploying MedusaJS and Next.js on a VPS for a production-ready environment.

Why Choose MedusaJS and Next.js for Your Enterprise?

Before diving into the technical deployment, it is vital to understand why the architectural combination of MedusaJS and Next.js is highly advantageous for modern B2B and B2C enterprises:

• Absolute Architectural Freedom: MedusaJS operates entirely via a REST API. This means your backend can power not only a web storefront but also mobile applications, POS systems, and IoT devices simultaneously.
• Unmatched Frontend Performance: Next.js leverages Server-Side Rendering (SSR) and Incremental Static Regeneration (ISR). This ensures pages load instantly, drastically reducing bounce rates and maximizing conversion potential.
• Cost-Efficiency at Scale: Monolithic SaaS platforms often charge a percentage of revenue or scale costs aggressively based on volume. Self-hosting on a VPS incurs a predictable, flat infrastructure fee, regardless of your transaction volume.
• Deep Customization capabilities: Built on Node.js, MedusaJS allows developers to easily extend core entities, create custom plugins, and integrate local payment gateways or ERP systems without fighting the core framework.

Prerequisites and Server Preparation

To ensure a stable and secure production deployment, your infrastructure must meet specific baseline requirements. We recommend a VPS running Ubuntu 22.04 LTS or 24.04 LTS with at least 2 vCPUs and 4GB of RAM to comfortably handle the backend, database, and frontend rendering processes.

Step 1: System Updates and Dependency Installation

First, connect to your VPS via SSH and update the core system packages to their latest versions:

Note: Always run system updates before installing new software stacks to ensure security patches are up to date.

Next, install the foundational software required to run and manage the applications, including Node.js (version 18 or 20 is recommended for modern MedusaJS builds), NPM, Git, and Docker if you prefer containerized database management.

Step 2: Database and Redis Configuration

MedusaJS requires PostgreSQL as its primary relational database and Redis for handling event queues, caching, and background jobs. For a production environment, ensure your PostgreSQL instance is configured with strong password authentication and that Redis is configured to persist data securely.

Deploying the MedusaJS Backend

With the environment prepared, the next phase involves initializing and configuring the MedusaJS core application on your server.

1. Setting Up the Project Structure

It is best practice to organize your applications within a dedicated directory on the server, such as /var/www/. Clone your custom MedusaJS project repository or initialize a clean instance directly on the server using the Medusa CLI tool. Configure the environment variables by editing the .env file to link correctly to your PostgreSQL and Redis credentials.

2. Running Database Migrations and Seeding

Before launching the server, execute the database migrations to build the necessary schema for products, customers, orders, and regions:

Running the migration command ensures that your database is structurally ready to accept API requests. You may also run a seeding script to populate initial setup data, such as currency regions and tax configurations.

3. Process Management with PM2

In a production ecosystem, applications must run continuously in the background and automatically restart if the server reboots or encounters an unexpected failure. PM2 is an excellent process manager for this task. You can launch your MedusaJS backend under PM2 control to ensure maximum uptime and easy log management.

Deploying the Next.js Storefront

Once the backend API is live and accessible locally, you can deploy your Next.js frontend storefront on the same VPS (or a separate web server if horizontal scaling is required).

1. Environment Integration

Your Next.js repository must be configured to talk to the MedusaJS API. In your frontend .env.production file, define the backend URL pointing to your server's domain or local port where Medusa is listening. This enables Server-Side Rendering components to fetch product data seamlessly during build time and runtime.

2. Building and Process Optimization

Compile the Next.js application for production. This step triggers optimization processes, including code splitting, minification, and static page generation. Once the build succeeds, launch the Next.js server using PM2, assigning it to a distinct port (e.g., port 3000) so it does not conflict with the backend (typically port 9000).

Configuring Reverse Proxy, SSL, and Security

Exposing Node.js applications directly to the public web is highly discouraged for security and performance reasons. Instead, we use Nginx as a reverse proxy alongside Let's Encrypt for automated SSL encryption.

1. Nginx Reverse Proxy Configuration

Configure Nginx to route incoming public traffic to the appropriate internal ports. You will set up two distinct server blocks: one for your frontend domain (e.g., yourstore.com) routing to port 3000, and one for your backend API domain (e.g., api.yourstore.com) routing to port 9000. Ensure that proper headers, such as X-Real-IP and X-Forwarded-For, are passed along to preserve client information for analytics and fraud detection.

2. Securing with Let's Encrypt SSL

Security is paramount for any digital commerce platform. Use Certbot to acquire and automatically renew SSL certificates for both domains. This ensures that all customer data, checkout transactions, and administrative credentials are encrypted using modern HTTPS protocols.

Conclusion and Ongoing Maintenance

By self-hosting MedusaJS and Next.js on a VPS, your business unlocks an enterprise-grade, high-performance commerce engine without the burden of recurring platform fees or restrictive vendor guidelines. You possess complete control over your customer data, user experience, and backend logic.

To maintain peak performance, implement routine maintenance practices. This includes setting up automated daily backups of your PostgreSQL database, utilizing monitoring tools to track CPU and memory usage, and keeping your Node.js dependencies updated to benefit from the latest security patches. With this robust foundation, your headless commerce store is fully equipped to scale efficiently alongside your business growth.