Deploying a MedusaJS 2.0 Store on AN AWS EC2 Instance.

So you have decided to set up an online store and you would rather set it up your self, you’re in the right place.

We’ll Deploy a MedusaJS Backend and Storefront on an Ubuntu Server. In a later article we’ll look at using other AWS services to build a more resilient version. I’ll link it here when it’s ready [link]

Introduction
Pre-requisites
Step-by-Step Deployment
- STEP 1) Server Provisioning
- STEP 2) Installing Prerequisites
- STEP 3) Running the Medusa Backend
- STEP 4) Reverse Proxy with Nginx
- STEP 5) Setting up the Frontend
- STEP 6) Debugging and Fixes
- STEP 7) Next Steps (Future Work)
Why Deploy MedusaJS on a Scalable Server?

There are many modern, headless commerce platforms, and MedusaJS is one of the most versatile for building full-featured online stores. Medusa makes store development seamless but deploying a production-ready application can be challenging without the right setup and automation practices.

That’s what this article will focus on, configuring an Ubuntu server to handle it and serving it through Nginx so safe to say that by the end we’ll have

A live MedusaJS application running on your server

Clearly separated and functional routes for admin, API, authentication, and storefront

A persistent frontend using PM2 for reliability

Nginx properly configured to handle the admin panel, country-specific routes and SSL

So whether you’re a developer looking to build more features for a specific use-case or just exploring headless commerce, this step-by-step guide will give you everything you need to host Medusa yourself.

Server Provisioning

Start by provisioning an ubuntu server, we’ll create a new security group with inbound rules; 22 from your IP, 80 and 443 from anywhere.
You should have something like this

A t3 medium server with about 30GB of storage space should do just fine.

Installing the Prerequisites

All we need is a Server, a domain and a stripe account.

We’ll need to install quite a few things to get our Medusa Store up and running.

Node
Docker & Docker Compose
Curl & Git
PM2
Nginx
Certbot

We can use this script to install everything we need.
We’ll install the Certbot later since it requires interaction

#!/bin/bash # Update system sudo apt update && sudo apt upgrade -y # Install prerequisites sudo apt install -y ca-certificates curl gnupg lsb-release # Add Docker’s official GPG key sudo mkdir -p /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg |  sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg # Add Docker’s APT repository echo  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg]  https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" |  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null # Install Docker Engine, CLI, containerd, and Docker Compose plugin sudo apt update sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin # Enable and start Docker sudo systemctl enable docker sudo systemctl start docker # Allow current user to run Docker without sudo sudo usermod -aG docker $USER newgrp docker # Verify Docker docker --version docker compose version # Install Git sudo apt install -y git # Install Nginx sudo apt install -y nginx sudo systemctl enable nginx sudo systemctl start nginx # Install Node.js (LTS) and npm curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash - sudo apt install -y nodejs # Install PM2 globally sudo npm install -g pm2 # Setup PM2 startup (so it restarts apps on reboot) pm2 startup systemd -u $USER --hp $HOME

Running the Backend Server

We’ll set up the Medusa Backend using Docker.

Let’s begin by cloning the Repo

git clone https://github.com/medusajs/medusa-starter-default.git --depth=1 medusa-server
Next, create a Docker compose file, docker-compose.yml in the new repo

services: # PostgreSQL Database postgres: image: postgres:15-alpine container_name: medusa_postgres restart: unless-stopped environment: POSTGRES_DB: medusa-store POSTGRES_USER: postgres POSTGRES_PASSWORD: postgres ports: - "5432:5432" volumes: - postgres_data:/var/lib/postgresql/data networks: - medusa_network # Redis redis: image: redis:7-alpine container_name: medusa_redis restart: unless-stopped ports: - "6379:6379" networks: - medusa_network # Medusa Server # This service runs the Medusa backend application # and the admin dashboard. medusa: build: . container_name: medusa_backend restart: unless-stopped depends_on: - postgres - redis ports: - "9000:9000" environment: - NODE_ENV=production - DATABASE_URL=postgres://postgres:postgres@postgres:5432/medusa-store - REDIS_URL=redis://redis:6379 env_file: - .env volumes: - .:/app - /app/node_modules networks: - medusa_network volumes: postgres_data: networks: medusa_network: driver: bridge

This creates three new services we’ll need, Redis, Postgres and Medusa

Create a Dockerfile, Dockerfile

# Development Dockerfile for Medusa FROM node:20-alpine # Set working directory WORKDIR /server # Copy package files and npm config COPY package.json package-lock.json ./ # Install all dependencies using npm RUN npm install # Copy source code COPY . . # Expose the port Medusa runs on EXPOSE 9000 # Start with migrations and then the development server CMD ["./start.sh"]

Now create the start script start.sh and give it permission to run with chmod u+x start.sh

#!/bin/sh # Run migrations and start server echo "Running database migrations..." npx medusa db:migrate echo "Seeding database..." npm run seed || echo "Seeding failed, continuing..." echo "Starting Medusa development server..." npm run dev

Run npm install to install the dependencies we’ll be working with.

Replace the medusa-config.ts file with this

import { loadEnv, defineConfig } from '@medusajs/framework/utils' loadEnv(process.env.NODE_ENV || 'production', process.cwd()) module.exports = defineConfig({ projectConfig: { databaseUrl: process.env.DATABASE_URL, databaseDriverOptions: { ssl: false, sslmode: "disable", }, http: { storeCors: process.env.STORE_CORS!, adminCors: process.env.ADMIN_CORS!, authCors: process.env.AUTH_CORS!, jwtSecret: process.env.JWT_SECRET || "supersecret", cookieSecret: process.env.COOKIE_SECRET || "supersecret", }, }, admin: { vite: () => { return { server: { allowedHosts: [".domainhere.com"], // add your domain here }, } }, }, })

Don’t forget to replace with your domain name where i indicated

In the package.json script section add this

{ "scripts": { // Other scripts... "docker:up": "docker compose up --build -d", "docker:down": "docker compose down" } }

Create a .dockerignore file and add these to it

node_modules npm-debug.log* yarn-debug.log* yarn-error.log* .git .gitignore README.md .env.test .nyc_output coverage .DS_Store *.log dist build

Next create a .env file and add these, replacing with your domain where necessary

STORE_CORS=http://localhost:8000,https://docs.medusajs.com,https://domainhere.com,https://www.domainhere.com ADMIN_CORS=http://localhost:5173,http://localhost:9000,https://docs.medusajs.com,https://domainhere.com,https://domainhere.com/app AUTH_CORS=http://localhost:5173,http://localhost:9000,https://docs.medusajs.com,https://domainhere.com,https://domainhere.com/app REDIS_URL=redis://redis:6379 JWT_SECRET=supersecret COOKIE_SECRET=supersecret DATABASE_URL=postgres://postgres:postgres@postgres:5432/medusa-store DB_NAME=medusa-v2

Never expose your secrets but it should look like this

To start your application use npm run docker:up

To create a new admin user run

docker compose run --rm medusa npx medusa user -e admin@example.com -p supersecret

Replace with your email and password

To check your logs if everything runs smoothly
docker compose logs -f

Reverse Proxy with Nginx

Now let’s setup Nginx

We’ve installed Nginx previously so we should be seeing the “Welcome to Nginx page” on the server’s url

Create a Config file in /etc/nginx/sites-available and name it anything you want. I used the name of my domain, workrate.online

This config file sets up redirects to your Admin dashboard, frontend and API
Just replace my domain name, workrate.online with yours

server { listen 80; server_name workrate.online www.workrate.online; # --- Frontend (Next.js Storefront) --- location ~ ^/(dk|us|ng)(/.*)?$ { proxy_pass http://localhost:8000; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection 'upgrade'; proxy_set_header Host $host; proxy_cache_bypass $http_upgrade; } # Root frontend fallback location / { proxy_pass http://localhost:8000; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection 'upgrade'; proxy_set_header Host $host; proxy_cache_bypass $http_upgrade; } # --- Medusa Backend Routes --- location /store/ { proxy_pass http://localhost:9000/store/; } location /admin/ { proxy_pass http://localhost:9000/admin/; } location /auth/ { proxy_pass http://localhost:9000/auth/; } location /app/ { proxy_pass http://localhost:9000/app/; } }

Enable the newly created config with
sudo ln -s /etc/nginx/sites-available/yourfilenamehere/etc/nginx/sites-enabled/

Remove the default config, it sometimes interfere
sudo rm /etc/nginx/sites-enabled/default

Test and reload your config

sudo nginx -t sudo systemctl reload nginx

Don’t forget to point your domain to your server with your DNS provider.

Also you should set up Certbot to provide HTTPS by running

sudo apt install -y certbot python3-certbot-nginx
sudo certbot –nginx -d yourdomainname.com -d www.yourdomainname.com

You should now be able to access your Admin panel from your domain

Setting up the frontend

We’ll be setting up a GitHub Actions pipeline with the frontend because it seems more practical, the backend almost never changes but the frontend will require a lot of UI work and therefore constant pushing.

Anyways, let’s start by cloning the storefront

git clone https://github.com/medusajs/nextjs-starter-medusa medusa-storefront

Run npm install to install all dependencies

Create a .env file

#Your Medusa backend, should be updated to where you are hosting your server. Remember to update CORS settings for your server. See – https://docs.medusajs.com/learn/configurations/medusa-config#httpstorecors MEDUSA_BACKEND_URL=http://localhost:9000 # Your publishable key that can be attached to sales channels. See - https://docs.medusajs.com/resources/storefront-development/publishable-api-keys NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY= # Your store URL, should be updated to where you are hosting your storefront. NEXT_PUBLIC_BASE_URL=http://localhost:8000 # Your preferred default region. When middleware cannot determine the user region from the "x-vercel-country" header, the default region will be used. ISO-2 lowercase format. NEXT_PUBLIC_DEFAULT_REGION=dk # Your Stripe public key. See – https://docs.medusajs.com/resources/commerce-modules/payment/payment-provider/stripe NEXT_PUBLIC_STRIPE_KEY=pk_test_dQZtCPCXzFgnPf7YRp1ETSs7 # Your Next.js revalidation secret. See – https://nextjs.org/docs/app/building-your-application/data-fetching/fetching-caching-and-revalidating#on-demand-revalidation REVALIDATE_SECRET=supersecret NEXT_PUBLIC_MEDUSA_BACKEND_URL=http://localhost:9000

You’ll need your Publishable key and Stripe Key {You can use the test one i attached for development purpose only}

You can use SSH tunnelling to access your port 9000 through your browser, login and get your Publishable Key. Run this on your local machine not the server

Or just go through your domain/app

ssh -i /path/to/your-key.pem -L 9000:localhost:9000 ubuntu@<your-ec2-public-ip>

You should then be able to go to http://localhost:9000/app/settings/publishable-api-keys to retrieve your own keys

Use npm run dev to make sure everything is running smoothly

GitHub Action

Generate new secret keys on your local machine with
ssh-keygen -t rsa -b 4096 -C "example@email.com"
Follow the prompt and manually append your generated .pub keys to ~/.ssh/authorized_keys

Create a GitHub repo, Medusa-storefront

Copy the private keys and go over to your Github Repo

Navigate to Settings -> Secrets & Variables -> Actions

Create a new repository secret named SSH_PRIVATE_KEY and enter the keys you copied earlier.

Remember the values from the .env files, we’ll create some secrets and variables so we can SSH into over server, build the frontend and deploy it every time it detects a push.

SSH_PRIVATE_KEY Secret SERVER_HOST Secret Your Public IPv4 Address SERVER_USER Secret ubuntu APP_DIR Secret /var/www/storefront NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY Secret NEXT_PUBLIC_STRIPE_KEY Secret REVALIDATE_SECRET Secret MEDUSA_BACKEND_URL Variable https://domainname NEXT_PUBLIC_MEDUSA_BACKEND_URL Variable https://domainname NEXT_PUBLIC_BASE_URL Variable https://domainname NEXT_PUBLIC_DEFAULT_REGION Variable dk

Next in your server create a file in the store-front directory in .github/workflows/deploy.yml

Add this to the file save and push to your own local repo

name: Deploy Frontend on: push: branches: - main jobs: deploy: runs-on: ubuntu-latest env: MEDUSA_BACKEND_URL: ${{ vars.MEDUSA_BACKEND_URL }} NEXT_PUBLIC_MEDUSA_BACKEND_URL: ${{ vars.NEXT_PUBLIC_MEDUSA_BACKEND_URL }} NEXT_PUBLIC_BASE_URL: ${{ vars.NEXT_PUBLIC_BASE_URL }} NEXT_PUBLIC_DEFAULT_REGION: ${{ vars.NEXT_PUBLIC_DEFAULT_REGION }} NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY: ${{ secrets.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY }} NEXT_PUBLIC_STRIPE_KEY: ${{ secrets.NEXT_PUBLIC_STRIPE_KEY }} REVALIDATE_SECRET: ${{ secrets.REVALIDATE_SECRET }} steps: - name: Checkout code uses: actions/checkout@v3 - name: Setup Node.js uses: actions/setup-node@v3 with: node-version: 20 - name: Create .env file run: | cat > .env << EOF MEDUSA_BACKEND_URL=${{ vars.MEDUSA_BACKEND_URL }} NEXT_PUBLIC_MEDUSA_BACKEND_URL=${{ vars.NEXT_PUBLIC_MEDUSA_BACKEND_URL }} NEXT_PUBLIC_BASE_URL=${{ vars.NEXT_PUBLIC_BASE_URL }} NEXT_PUBLIC_DEFAULT_REGION=${{ vars.NEXT_PUBLIC_DEFAULT_REGION }} NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY=${{ secrets.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY }} NEXT_PUBLIC_STRIPE_KEY=${{ secrets.NEXT_PUBLIC_STRIPE_KEY }} REVALIDATE_SECRET=${{ secrets.REVALIDATE_SECRET }} EOF - name: Install dependencies and build run: | npm install npm run build - name: Copy build files and .env to server uses: appleboy/scp-action@v0.1.7 with: host: ${{ secrets.SERVER_HOST }} username: ${{ secrets.SERVER_USER }} key: ${{ secrets.SSH_PRIVATE_KEY }} source: ".,!.git" target: "${{ secrets.APP_DIR }}" - name: Restart app uses: appleboy/ssh-action@v1.0.3 with: host: ${{ secrets.SERVER_HOST }} username: ${{ secrets.SERVER_USER }} key: ${{ secrets.SSH_PRIVATE_KEY }} script: | cd ${{ secrets.APP_DIR }} # Install production dependencies sudo npm install # Restart PM2 process sudo pm2 delete medusa-storefront || true sudo pm2 start npm --name medusa-"storefront" -- run start sudo pm2 save

Use these commands to make sure the APP_DIR exists and has the correct permission to run

sudo mkdir -p /var/www/storefront sudo chown -R ubuntu:ubuntu /var/www/storefront

Debugging, Fixes and Additional Configs

All you have left to do is make a change to the frontend, i overhauled the Storefront landing page. Make a push, let it build and test to make sure everything works fine.
Check it out here.
https://github.com/aregbesolaisrael/medusa-storefront

Next Steps

While this setup works for small and medium businesses, in my next article i’ll cover scaling Medusa with AWS services (ECS, RDS, CloudFront) and setting up monitoring and alerts.

Source: DEV Community.