Deploying Medusa to Oracle Cloud

How to Deploy a Medusa Commerce Backend Server using Oracle Cloud Compute Infrastructure

Introduction

Medusa is a modular commerce engine that helps developers build rich digital commerce applications. It is free, open source, and uses Node.js. With Medusa, a developer can quickly build advanced commerce solutions without coding from scratch.

Medusa is very flexible and customizable. It can be hosted in the cloud using IAAS and PAAS.

Oracle Cloud provides virtual machines suitable enough to host a Medusa backend.

This guide will teach you how to deploy a live server of the Medusa backend in the cloud using OCI.

Why Oracle Cloud?

Oracle Cloud offers a very generous "Always-Free" tier for its cloud services. You can host the Medusa server application within the OCI all for free.

The free services of interest that OCI provides to your app are:

• An ARM-based VM with:
  • Upto 8 CPUs
  • Linux
  • 24GB of memory
  • 50GB boot volume for storage
• Up to 200GB of block storage for your VM with 5 backups
• Free Load Balancer with max bandwidth set to 10Mbps
• Up to 10TB per month of Outbound Data Transfer
• Unlimited Inbound Data Transfer

For more information about the all the free services offered Oracle Cloud check out the Always Free Resources page.

Prerequisites

• A GitHub account. Sign up for one here
• An Oracle Cloud account. Sign up for Oracle Cloud account here

Create OCI Linux Instance

Create a compartment for your resources

In this step, you will create a compartment to control and organize the resources you will use for your Medusa backend server. You will only need one compartment to manage all the project resources.

Sign in to your Oracle Cloud Console.

Click on the navigation menu icon and select Identity & Security. Choose Compartments under the Identity option.

Click Create Compartment.

Enter the following:

• Name: Enter "Medusa"
• Description: Enter "Compartment for Medusa backend server"
• Parent Compartment: Select the default root compartment

Select Create Compartment, wait a moment, and refresh to see your compartment displayed in the list of compartments.

Click on Networking in the navigation menu and select Virtual cloud networks.

From the compartment list on the left, select the Medusa compartment you created before.

For more information check out these instructions on Choosing and Creating a Compartment for your project.

Create a virtual cloud network

Click the Start VCN Wizard button.

Choose the Create VCN with Internet Connectivity option, and then click Start VCN Wizard

Enter these details:

• VCN Name: medusa
• Compartment: Select the Medusa compartment
• VCN CIDR Block: 10.0.0.0/16
• Public Subnet CIDR Block: 10.0.0.0/24
• Private Subnet CIDR Block: 10.0.1.0/24

Leave all the other details as they are.

Click Next and review the details for your VCN and click on Create. Wait a few seconds for your VCN to be created, then select View VCN.

For more information check out Creating a Virtual Cloud Network

Launch an instance

Select Instances under Compute in the navigation menu of your Oracle Dashboard.

Click Create Instance to take you to the Create compute instance page.

Enter the name medusa-server for your instance and the compartment should be Medusa.

For the Placement section, leave the default Availability domain as it is.

Choose the following Image and shape:

• Image: Ubuntu 22.04
• Shape: VM.Standard.A1.Flex

If you need a different image and shape for your medusa-server VM, you can follow these instructions to change them.

For the Networking section, add the following configurations:

• Primary network: Select existing virtual cloud network
• Virtual cloud network in medusa: medusa
• Subnet: Select existing subnet
• Subnet in medusa: public subnet-medusa (regional)
• Public IPv4 address: Assign a public IPv4 address

In the Add SSH key section:

• Choose Generate a key pair for me

OCI will generate an SSH key for your instance

• Select Save Private Key to save the private key in your computer as a .key file.

If you prefer other options for establishing an SSH connection use these instructions

For the Boot volume section, leave the default options.

Click Create and wait for your instance to be provisioned.

Wait for a few minutes for your instance to be created and you will see it the Console. When the status of the instance has changed to RUNNING you can now connect to it.

For more information check out Launching a Linux Instance in the Oracle Cloud Documentation.

Connect to the Instance

You will use the private key generated in the previous section to connect to the instance.

If you are using a Windows system you must install OpenSSH. If you don't have it, download and install the PuTTY Key Generator

Note down the Public IP address and Username for your running instance.

To apply the appropriate permissions to your SSH private key so that you and only you can read it, follow these instructions for Unix-style systems and these for Windows System with OpenSSH.

After applying permissions to your private key, open up a new terminal session on your local computer and use the following SSH command to access the Oracle instance:

Where:

• <private_key_file> is the path and name of the private SSH key file in your computer associated with your medusa server instance.
• <username> is the default username you noted down in the previous step. In this case it is ubuntu.
• <public-ip-address> is the IP address for your instance you noted down in a previous step.

If your SSH connection is successful, you should be logged in to your medusa server instance as the default ubuntu user.

Set up and Configure Environment

Install Node.js and Set up Git

To deploy a Medusa server into an OCI, you must have Node v16 or greater.

Ensure you are still logged in to your server instance and run the following commands:

curl -sL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt install nodejs
node -v && npm -v

The last command should give you v18.x.x for node and 9.x.x for npm to confirm successful installation.

If you see errors when trying to install packages globally, resolve the access permissions for npm using the following command:

mkdir ~/.npm-global && npm config set prefix '~/.npm-global' && echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.profile && source ~/.profile

Git comes by default in Ubuntu. You can confirm if it is installed by running the following command:

git --version

If it is not installed follow these instructions on how to install Git on Ubuntu 22.04

Configure the global username and email for your Git Identity.

Set up and configure PostgreSQL Database.

When deploying Medusa, it is recommended to use a PostgreSQL database. In this step, you will install PostgreSQL and create a database for your Medusa server.

To download and install PostgreSQL run the following commands:

sudo sh -c \
  'echo "deb http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'
wget --quiet -O - \
  https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add -
sudo apt-get update
sudo apt-get -y install postgresql

To check if the PostgreSQL installation was successful, run the following:

psql -V

Access the PostgreSQL console to create a new user and database for the Medusa server.

sudo -u postgres psql

To create a new user named medusa_admin run this command:

CREATE USER medusa_admin WITH PASSWORD 'medusa_admin_password';

Now, create a new database named medusa_db and make medusa_admin the owner.

CREATE DATABASE medusa_db OWNER medusa_admin;

Last, grant all privileges to medusa_admin and exit the PostgreSQL console.

GRANT ALL PRIVILEGES ON DATABASE medusa_db TO medusa_admin;

exit

Set up a Medusa app on your local machine

In your web browser, sign in to your GitHub account and create a GitHub repository to store your Medusa server app.

In a new terminal session, clone the repo you have just created to your local machine and change to the new directory:

git clone https://github.com/<username>/<reponame>.git
cd <reponame>

<username> refers to your GitHub username.
<reponame> refers to your GitHub repo.

Set up a Medusa server app using the Medusa Server Quickstart Guide instructions.

If you successfully followed the instructions, you should have a directory named my-medusa-store containing your Medusa server app and a server running on port 9000.

Here's the tree structure for the my-medusa-store folder.

.
├── my-medusa-store
│   ├── .babelrc.js
│   ├── data
│   ├── dist
│   ├── .env
│   ├── .git
│   ├── .gitignore
│   ├── index.js
│   ├── medusa-config.js
│   ├── medusa-db.sql
│   ├── node_modules
│   ├── package.json
│   ├── package-lock.json
│   ├── README.md
│   ├── src
│   ├── tsconfig.json
│   ├── tsconfig.spec.json
│   └── uploads

Open up medusa-config.js in the root of your app folder.

In the projectConfig section, comment out the line database_database: "./medusa-db.sql", and add database_url: DATABASE_URL.

/** @type {import('@medusajs/medusa').ConfigModule["projectConfig"]} */
const projectConfig = {
  jwtSecret: process.env.JWT_SECRET,
  cookieSecret: process.env.COOKIE_SECRET,
  //database_database: "./medusa-db.sql",
  database_url: DATABASE_URL,
  database_type: DATABASE_TYPE,
  store_cors: STORE_CORS,
  admin_cors: ADMIN_CORS,
  // Uncomment the following lines to enable REDIS
  // redis_url: REDIS_URL
}

Open up package.json in the root of your app folder and change the start script as follows:

  "scripts": {
    "clean": "cross-env ./node_modules/.bin/rimraf dist",
    "build": "cross-env npm run clean && tsc -p tsconfig.json",
    "watch": "cross-env tsc --watch",
    "test": "cross-env jest",
    "seed": "cross-env medusa seed -f ./data/seed.json",
    "start": "medusa migrations run && medusa start",
    "start:custom": "cross-env npm run build && node --preserve-symlinks index.js",
    "dev": "cross-env npm run build && medusa develop",
    "build:admin": "cross-env medusa-admin build"
  },

Commit and push the changes you made to GitHub.

git commit -a -m "Updated medusa.config.js & package.json" 
git push

Run Medusa Server on Oracle Cloud VM

In a new terminal session, ssh into your Oracle Cloud instance and clone your Medusa server app repo from GitHub.

git clone https://github.com/<username>/<reponame>.git

Change to your new directory holding the Medusa server app and install the Node dependencies:

cd my-medusa-store
npm install

Create a .env file in the root of my-medusa-store and add the following variables:

PORT=9000
JWT_SECRET=something
COOKIE_SECRET=something
DATABASE_TYPE=postgres
DATABASE_URL=postgres://medusa_admin:medusa_admin_password@localhost:5432/medusa_db

Use other values for JWT_SECRET and COOKIE_SECRET besides something for better security.

To seed your database run the following command:

npm run seed

Testing the Medusa app server

Give public access to the server

In this step, you will add an ingress rule to the medusa subnet to allow internet connections on port 9000.

Make sure you are still logged in via ssh to your Oracle instance.

Open the navigation menu, select Networking, and click on Virtual Cloud Networks.

Select the medusa VCN.

Select Security List link and click on the Default Security List for medusa link.

Select Add Ingress Rules to display the Add Ingress Rules modal. Fill in the ingress rule as follows:

• Stateless: Checked
• Source Type: CIDR
• Source CIDR: 0.0.0.0/0
• IP Protocol: TCP
• Source port range:
• Destination Port Range: 9000
• Description: Allow HTTP connections

Click Add Ingress Rules. Now your server is accessible via HTTP.

Configure Ubuntu Firewall

Follow these steps to configure the firewall settings for your Medusa server. In a new terminal session, ssh into your medusa server.

Run the following commands to update the iptables configuration to allow HTTP traffic.

sudo iptables -I INPUT 6 -m state --state NEW -p tcp --dport 9000 -j ACCEPT
sudo netfilter-persistent save

Start your Medusa app server

Ensure you are still logged in via ssh to your Oracle instance, and run the following command to start your Medusa app server.

npm run start

Now you can access it over the internet on http://x.x.x.x:9000, where x.x.x.x is your server's IP address.

If you visit the endpoint, http://x.x.x.x:9000/health you should see an OK message. This confirms that your server is working.

Visit the endpoint http://x.x.x.x:9000/store/products, and you should see a list of products in your database.

With that, your Medusa server should be working as expected.

Conclusion

This tutorial showcased minimal deployment of a Medusa server on Oracle Cloud. Here are some additional configurations you can make:

• Install the MinIO plugin to handle image uploads to your Medusa backend.
• Install and configure Redis if you want scheduled jobs.
• Install PM2 to manage and ensure availability of your Medusa server.
• Install Nginx to configure a domain name.
• Add an SSL certificate for your domain name.
• Set up a CI/CD pipeline between your development environment and your deployment.
• Secure your server.

Oracle Cloud Free Tier provides a convenient way for developers to test and deploy Medusa ecommerce apps. I hope this tutorial has provided sufficient knowledge on how you could host a Medusa server app on Oracle Cloud.

Enjoyed my tutorial? Help me keep creating free content by donating today. Every contribution makes a big difference! Thank you.

If there are any issues or questions, feel free to comment with your query.