RamNode logo
    Sign UpLogin
    E-Commerce Guide

    Self-Hosted Medusa Commerce

    Deploy Medusa, the open-source headless commerce platform, on RamNode VPS. Build custom e-commerce experiences with complete control over your storefront.

    Ubuntu 22.04/24.04 LTS
    Node.js 20+
    ⏱️ 30-45 minutes

    Why Medusa?

    Medusa is an open-source headless commerce platform that provides a flexible and extensible foundation for building custom e-commerce experiences. Unlike traditional monolithic platforms, Medusa separates the backend commerce engine from the frontend presentation layer.

    REST and GraphQL APIs
    PostgreSQL for persistent storage
    Redis caching and sessions
    Admin dashboard included
    Extensible plugin ecosystem
    Complete storefront flexibility

    Prerequisites

    VPS Requirements

    • • RAM: 2 GB (4 GB recommended)
    • • CPU: 1 vCPU (2 vCPUs recommended)
    • • Storage: 20 GB SSD
    • • OS: Ubuntu 22.04 or 24.04 LTS

    Before You Begin

    • • Root or sudo access to your VPS
    • • Domain name pointed to your VPS IP
    • • Basic Linux command line knowledge
    • • SSH access to your server

    Initial Server Setup

    1

    Update the System

    Connect to your VPS via SSH and update all packages:

    Update System
    sudo apt update && sudo apt upgrade -y
    2

    Create a Dedicated User

    Create a non-root user for running Medusa:

    Create User
    sudo adduser medusa
sudo usermod -aG sudo medusa
    3

    Configure Firewall

    Enable UFW and allow necessary ports:

    Configure UFW
    sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable

    Node.js Installation

    1

    Install Node.js 20

    Medusa requires Node.js 20 or higher. Install it using NodeSource:

    Install Node.js
    curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs
    2

    Verify Installation

    Verify the installation:

    Check Versions
    node --version
npm --version

    Tip: You should see Node.js v20.x.x or higher.

    PostgreSQL Setup

    1

    Install PostgreSQL

    Install PostgreSQL:

    Install PostgreSQL
    sudo apt install -y postgresql postgresql-contrib
    2

    Create Database and User

    Switch to the postgres user and create the Medusa database:

    Login to PostgreSQL
    sudo -u postgres psql
    SQL Commands
    CREATE USER medusa WITH PASSWORD 'your_secure_password';
CREATE DATABASE medusa_db OWNER medusa;
GRANT ALL PRIVILEGES ON DATABASE medusa_db TO medusa;
\q

    Warning: Replace 'your_secure_password' with a strong, unique password. Store this securely.

    Redis Installation

    1

    Install Redis

    Redis is used for caching, session storage, and background job queues:

    Install Redis
    sudo apt install -y redis-server
    2

    Configure Redis

    Configure Redis to start on boot:

    Enable Redis
    sudo systemctl enable redis-server
sudo systemctl start redis-server
    3

    Verify Redis

    Verify Redis is running:

    Test Redis
    redis-cli ping

    You should see PONG as the response.

    Medusa Installation

    1

    Switch to Medusa User

    Switch User
    su - medusa
    2

    Create Medusa Project

    Use the Medusa CLI to create a new project:

    Create Project
    npx create-medusa-app@latest my-store

    During installation, you'll be prompted for:

    • Project directory name
    • PostgreSQL database URL (use the credentials from earlier)
    • Whether to create a Next.js storefront
    3

    Manual Installation (Alternative)

    If you prefer manual setup:

    Manual Setup
    mkdir ~/my-store && cd ~/my-store
npm init -y
npm install @medusajs/medusa-cli -g
medusa new . --skip-db

    Configuration

    1

    Environment Configuration

    Navigate to your project and edit the .env file:

    Edit .env
    cd ~/my-store
nano .env

    Configure the following environment variables:

    Environment Variables
    # Database
DATABASE_URL=postgres://medusa:your_secure_password@localhost:5432/medusa_db

# Redis
REDIS_URL=redis://localhost:6379

# JWT Secrets (generate unique values)
JWT_SECRET=your-super-secret-jwt-key-min-32-chars
COOKIE_SECRET=your-super-secret-cookie-key-min-32

# Server
MEDUSA_ADMIN_ONBOARDING_TYPE=default
STORE_CORS=https://your-storefront-domain.com
ADMIN_CORS=https://admin.your-domain.com
    2

    Generate Secure Secrets

    Generate random secrets for JWT and cookies:

    Generate Secrets
    openssl rand -hex 32

    Run this command twice and use the outputs for JWT_SECRET and COOKIE_SECRET.

    3

    Run Database Migrations

    Run Migrations
    npx medusa db:migrate
    4

    Create Admin User

    Create Admin
    npx medusa user -e admin@your-domain.com -p your-admin-password

    Systemd Service

    1

    Create Service File

    Create a systemd service to manage Medusa as a background process:

    Create Service
    sudo nano /etc/systemd/system/medusa.service

    Add the following configuration:

    Service Configuration
    [Unit]
Description=Medusa Commerce Server
After=network.target postgresql.service redis.service

[Service]
Type=simple
User=medusa
WorkingDirectory=/home/medusa/my-store
ExecStart=/usr/bin/npm run start
Restart=on-failure
RestartSec=10
StandardOutput=syslog
StandardError=syslog
SyslogIdentifier=medusa
Environment=NODE_ENV=production

[Install]
WantedBy=multi-user.target
    2

    Enable and Start Service

    Enable and start the service:

    Enable Service
    sudo systemctl daemon-reload
sudo systemctl enable medusa
sudo systemctl start medusa
    3

    Check Service Status

    Check Status
    sudo systemctl status medusa

    Nginx Reverse Proxy

    1

    Install Nginx

    Install Nginx
    sudo apt install -y nginx
    2

    Create Nginx Configuration

    Create Config
    sudo nano /etc/nginx/sites-available/medusa

    Add the following configuration:

    Nginx Configuration
    server {
    listen 80;
    server_name api.your-domain.com;

    location / {
        proxy_pass http://localhost:9000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        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;
        proxy_cache_bypass $http_upgrade;
    }
}
    3

    Enable Site

    Enable the site and restart Nginx:

    Enable Site
    sudo ln -s /etc/nginx/sites-available/medusa /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx

    SSL Certificate

    1

    Install Certbot

    Use Certbot to obtain a free SSL certificate from Let's Encrypt:

    Install Certbot
    sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d api.your-domain.com

    Certbot will automatically configure SSL and set up auto-renewal.

    Important: Ensure your domain's DNS A record points to your VPS IP address before running Certbot.

    Admin Dashboard

    After completing the setup, access the Medusa admin dashboard at:

    Admin URL
    https://api.your-domain.com/app

    Log in with the admin credentials you created earlier.

    Admin Dashboard Features

    Product management and inventory
    Order processing and fulfillment
    Customer management
    Discount and promotion configuration
    Region and tax settings
    Shipping and payment providers

    Connect a Storefront (Optional)

    1

    Official Next.js Starter

    Medusa supports various frontend frameworks:

    Next.js Starter
    npx create-medusa-app@latest --with-nextjs-starter
    2

    Gatsby Storefront

    Gatsby Starter
    git clone https://github.com/medusajs/gatsby-starter-medusa
cd gatsby-starter-medusa
npm install
    3

    Configure Storefront

    Configure the storefront's environment to point to your Medusa backend:

    Environment Variable
    NEXT_PUBLIC_MEDUSA_BACKEND_URL=https://api.your-domain.com

    Maintenance and Operations

    Viewing Logs

    View Logs
    sudo journalctl -u medusa -f

    Restarting Medusa

    Restart
    sudo systemctl restart medusa
    1

    Updating Medusa

    Update Medusa
    cd ~/my-store
npm update @medusajs/medusa
npx medusa db:migrate
sudo systemctl restart medusa
    2

    Database Backup

    Create regular backups of your PostgreSQL database:

    Backup Database
    pg_dump -U medusa medusa_db > backup_$(date +%Y%m%d).sql

    Troubleshooting

    IssueSolution
    Database connection failedVerify DATABASE_URL in .env and PostgreSQL is running
    Redis connection errorCheck Redis service: sudo systemctl status redis-server
    Port 9000 already in useCheck for conflicting services: sudo lsof -i :9000
    SSL certificate issuesEnsure DNS is properly configured before running Certbot
    CORS errorsUpdate STORE_CORS and ADMIN_CORS in .env file

    Additional Resources

    Medusa DocumentationMedusa GitHubMedusa Discord CommunityMedusa Plugin Ecosystem