How to Self-Host Headless Commerce with MedusaJS on VPS with NextJS Frontend
This guide details self-hosting a headless commerce platform using MedusaJS as the backend and NextJS as the frontend on a VPS. It covers environment setup, database configuration,...
Image credit: wikimedia
This guide details self-hosting a headless commerce platform using MedusaJS as the backend and NextJS as the frontend on a VPS. It covers environment setup, database configuration, deploying both applications separately, API integration, and securing the entire system. Users will learn to deploy a modern, flexible, scalable, and fully controlled e-commerce system suitable for businesses needing custom development.
Introduction to MedusaJS and NextJS
MedusaJS is an open-source headless e-commerce platform that enables the creation of flexible shopping systems by decoupling the backend (API, product management, orders) from the frontend. NextJS is a popular React framework ideal for building modern, SEO-friendly, and high-performance frontends. By combining these technologies, you can build a comprehensive e-commerce system where the backend runs on your VPS and the frontend can be deployed on any platform.
MedusaJS provides powerful features such as product management, shopping cart, payment processing, order handling, and more via a robust RESTful API. NextJS allows the development of interactive, fast, and SEO-optimized user interfaces. Separating frontend and backend enables independent development, testing, and deployment, improving development speed and system stability.
Requirements and VPS Setup
To begin, you need a VPS (Virtual Private Server) with sufficient resources to run both MedusaJS and NextJS. A minimum of 4GB RAM and 2 CPU cores is recommended. You can choose from [NVMe Cloud VPS for Docker, Nginx & Databases](/en/vps) to ensure optimal performance for both applications and the database.
After purchasing the VPS, set up the operating system (typically Ubuntu 20.04 or 22.04), update the system, and create a non-root user with sudo privileges. Also, configure the firewall (ufw) and SSH keys to enhance security.
For deployment, you will need to install the following tools:
- Node.js (v16 or newer)
- Yarn or npm
- PostgreSQL or MySQL
- Docker (optional, but highly recommended)
- Nginx (for reverse proxy and SSL)
Database setup is crucial. You can install PostgreSQL directly on the VPS or use a separate database service. Below is an example of creating a PostgreSQL database:
sudo -u postgres psql
CREATE DATABASE medusa_db;
CREATE USER medusa_user WITH PASSWORD 'your_secure_password';
GRANT ALL PRIVILEGES ON DATABASE medusa_db TO medusa_user;
Deploying MedusaJS Backend
To deploy MedusaJS, create a new project using the Medusa CLI:
medusa new my-commerce-project --store-url=http://localhost:8080 --admin-url=http://localhost:7000
This will generate a MedusaJS project with default configuration. Edit the `.env` file to configure the database connection using the PostgreSQL instance created earlier:
MEDUSA_DATABASE_URL=postgres://medusa_user:your_secure_password@localhost:5432/medusa_db
After configuration, start MedusaJS using:
cd my-commerce-project
yarn dev
MedusaJS will start on ports 7000 (admin) and 8080 (store). For production deployment on the VPS, run the application in production mode using PM2:
pm2 start yarn --name "medusa" -- start
Deploying NextJS Frontend
For the frontend, create a new NextJS project using the NextJS CLI:
npx create-next-app@latest my-store
In the NextJS project, install the MedusaJS client library to connect to the backend API:
cd my-store
yarn add @medusajs/medusa-js
Then, create a `lib/medusa.js` file to initialize the Medusa client:
import { Medusa } from "@medusajs/medusa-js";
const medusa = new Medusa({
baseUrl: "https://your-vps-ip:8080",
maxRetries: 3,
});
export default medusa;
Replace `your-vps-ip` with your VPS's actual IP address. The frontend should now be able to access the MedusaJS API if configured correctly.
Integration and Security
To connect the frontend and backend, configure Nginx as a reverse proxy. This helps manage ports and secure connections. Below is an example Nginx configuration:
server {
listen 80;
server_name your-domain.com;
location / {
proxy_pass http://localhost:3000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
location /api {
proxy_pass http://localhost:8080;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
For security, use SSL. You can use Let's Encrypt to issue free SSL certificates. Install Certbot and run:
sudo certbot certonly --nginx -d your-domain.com
The SSL certificate will be automatically configured in Nginx. Also, configure the firewall to open only necessary ports (80, 443, 22).
Verification and Troubleshooting
To verify the system is working, check the following:
- Access `http://your-vps-ip:8080` to confirm the MedusaJS API returns data.
- Access `http://your-vps-ip:3000` to verify the NextJS frontend is running.
- Run `pm2 status` to check the MedusaJS service status.
- Review logs from MedusaJS and NextJS for errors.
If issues occur, check:
- SSL certificate and Nginx configuration.
- IP and port settings in the `.env` file.
- Database access permissions.
- PM2 service status.
References
For more information on MedusaJS, refer to the official documentation: [MedusaJS Documentation](https://docs.medusajs.com/). For NextJS, visit: [NextJS Documentation](https://nextjs.org/docs).
Related infrastructure & engineering guides: NVMe Cloud VPS for Docker, Nginx & Databases · How to Self-Host Excalidraw on Docker VPS for Internal Diagrams and Internal Collaboration in Enterprises
Recommended NVMe Cloud VPS Plans to Deploy This Setup
Enterprise RAID 10 NVMe SSDs, CMC & FPT District 9 uplinks with Anycast Anti-DDoS and 99.99% SLA.
VPS-3E
10% VAT included
- CPU: 2 vCPU
- RAM: 4 GB
- SSD: 50 GB NVMe
