How to Setup A Medusa Server Locally

Medusa is a NodeJS-based headless e-commerce platform marketed as an open-source and viable alternative to Shopify.

At the end of this article, you should know what Medusa is, install and setup Medusa. This tutorial requires basic knowledge of NodeJS, NPM, and Git.

A Primer On Medusa

A Medusa store comprises three components: A headless server, an admin dashboard, and a storefront.

The Medusa headless server is the component that holds the store’s core functionalities and data. The Admin dashboard and Storefront interact with the headless server via the Admin REST APIs and Storefront REST APIs. The headless server consists of NodeJS and Postgres for the database.

The Admin dashboard is the UI part of the store accessible by the store operators. Store operators can use the admin dashboard to create, view, and edit product data and orders.

The Storefront is the UI part of the store that customers see and interact with to view products and make orders. The Storefront is typically built using client-side Javascript Frameworks like React (NextJS, Gatsby) and VueJS.

Requirements

Install NodeJS

Medusa is built on NodeJS so it is required to run. NodeJS - Medusa currently supports Node versions 14 and 16. You can check which version you have by running node -v in the terminal. If you don’t already have Node installed on your computer, read this article on how to install NodeJS.

Install the Medusa CLI

Install the Medusa CLI globally using NPM

npm install @medusajs/medusa-cli --global

Create a Medusa Server Project

Bootstrap a new Medusa server project and seed with sample product data. For this tutorial, we’re going to create a Medusa e-commerce store for Watches, let’s name it watch-store-medusa-server.

medusa new watch-store-medusa-server --seed

Start the Medusa Server

Navigate to our medusa server project directory and start the server

cd watch-store-medusa-server
medusa develop

Test It Out

Send a get request to the API’s products endpoint using curl in a different terminal window to confirm the server is running properly.

curl localhost:9000/store/products

# If you have Python installed, you can format the JSON result.
curl localhost:9000/store/products | python -m json.tool

Medusa Server Configuration

Open the medusa project folder in a code editor like VS Code, At the root of the folder, there's a medusa-config.js file, the file contains all the configurations for your Medusa server like database and plugin. It's important to configure your Medusa server properly.

Install PostgreSQL

PostgreSQL is an open-source relational database system. Although Postgres isn't required to run a Medusa server, it is highly recommended as it gives you a more production-like environment. If you don’t already have Postgres installed, these tutorials explain how to install PostgreSQL on Windows, Linux and macOS

To check if the installation was successful or if you already have Postgres installed, run:

psql -V

Create Postgres Database

Before getting started with configuring PostgreSQL, we have to create a database.

access the postgres console
psql postgres

# create a new user
CREATE USER medusa_admin WITH PASSWORD 'medusa_admin_password';

# create a new database and the newly created user as the owner
CREATE DATABASE medusa_db OWNER medusa_admin;

# grant all privileges on medusa_db to the medusa_admin user
GRANT ALL PRIVILEGES ON DATABASE medusa_db TO medusa_admin;

# exit the postgres console
quit

Add the Postgres URL to the environmental variable

Using this Postgres database URL template : postgres://<username>:<password>@<host>:<port>/<database> and default port 5432. Add the following line to the .env file at the root of our medusa server folder:

DATABASE_URL=postgres://medusa_admin:medusa_admin_password@localhost:5432/medusa_db

Configure Postgres in medusa-config.js

module.exports = {
  projectConfig: {
        //...other configurations
    database_url: process.env.DATABASE_URL,
    database_type: "postgres",
  },
};

You can go on to delete the default SQLite database file and it's reference in medusa-config.js

Install Redis

Redis is an open-source in-memory data structure store. It can be used for distributing and emitting messages and caching, among other purposes.

Although Redis is not required for the Medusa Server to run, you need to install Redis if you want to use subscribers to handle events such as when an order is placed and perform actions based on them. This tutorial explains how to install Redis on your computer.

To confirm the installation was successful or if you already have Redis installed, run:

redis-server -v

Start Redis Server

Learn how to start and stop a Redis server with this tutorial

# start redis server on mac
brew services start redis

# start redis server on linux
sudo systemctl enable redis

Add Redis the Server URL to the environmental variable

The default Redis URL on local host is redis://localhost:6379

REDIS_URL=redis://localhost:6379

Configure Redis in medusa-config.js

module.exports = {
  projectConfig: {
    //...other configurations
    redis_url: process.env.REDIS_URL
  },
};

Test It Out

Restart the medusa server to check if everything is running fine.

# seed new postgres database
npm run seed 

# start the server
npm run start 

Setup A File Storage Plugin

In order to manage file storage in Medusa (e.g for uploading product images), you need to integrate a file storage plugin. Medusa provides three options to handle your file storage: MinIO, Amazon S3 and DigitalOcean Spaces.

Set up MinIO

It is recommended to use MinIO for local development. MinIO is similar to Amazon S3, except that it is self-hosted. You can install MinIO on your computer by following this tutorial.

Launch MinIO Server

Always make sure that your MinIO server is running when your Medusa server is running.

MinIO has a default address port of 9000, which clashes with Medusa, which also uses port 9000. You should change MinIO’s port from 9000 to something else e.g 9001.

# launch the minio server on port 9001
minio server ~/data --address ":9001"

Once the Minio server is running, you can access the console from the browser with the URL and credentials the MinIO server prints to the terminal.

Create a MinIO bucket

A bucket is similar to a folder or directory in a filesystem, where each bucket can hold an arbitrary number of objects.

You should see a page similar to the one shown in the screenshot after logging into the MinIO console. Click on the “Create Bucket” button to create a new bucket to store your Medusa server files. You can name the bucket whatever you like, for this tutorial, I’ll name the bucket “medusa”.

After creating the bucket, you need to set its access policy to Public.

Click the “Buckets” button on the sidebar, then the “Manage” button.

Click on the Access Policy button and set it to public.

You also need to generate Access keys.

Click on “Identity > Service Accounts” in the sidebar of the console, then click on the “Create service account” button.

A random Access Key and Secret Key will be generated. Once you click the Create button, a modal showing the Secret Key will be displayed. Make sure to copy it down somewhere safe before you close the modal, as it will only display once.

Install Medusa MinIO Plugin

Navigate to the medusa server project directory and install the plugin.

npm install medusa-file-minio

Open the medusa server in a code editor like VScode and add the following to the .env file:

MINIO_ENDPOINT=<ENDPOINT>  # URL of your MinIO server
MINIO_BUCKET=<BUCKET> # MinIO Bucket Name
MINIO_ACCESS_KEY=<ACCESS_KEY> # MinIO Bucket access key generated earlier.
MINIO_SECRET_KEY=<SECRET_KEY> # MinIO Bucket secret key generated earlier.

The final values should look similar to this:

MINIO_ENDPOINT=http://127.0.0.1:9001
MINIO_BUCKET=medusa
MINIO_ACCESS_KEY=p1Vuc3Ojxxxxxx
MINIO_SECRET_KEY=fSpy9aHSMywNhRKdxxxxxxxx

Finally, add the configuration to the medusa-config.js file.

const plugins = [
  // other plugins
  {
    resolve: `medusa-file-minio`,
    options: {
      bucket: process.env.MINIO_BUCKET,
      endpoint: process.env.MINIO_ENDPOINT,
      access_key_id: process.env.MINIO_ACCESS_KEY,
      secret_access_key: process.env.MINIO_SECRET_KEY,
    },
  },
];

module.exports = {
  projectConfig: {
   // other configs
  },
  plugins,
};

If you intend to use NextJS for your storefront, you will need to add the MinIO domain name into the configured images domain names in your NextJS project next.config.js file, so as to not receive the next/image Un-configured Host error.

module.exports = {
  images: {
    domains: [
      "127.0.0.1",
      // other domains
    ],
  },
};

Test it Out

Check if everything is running fine. Don’t forget to always make sure that your MinIO server is running when your Medusa server is running.

# launch the minio server on port 9001
minio server ~/data --address ":9001"


# start the medusa server on a new terminal tab
npm run start

Congratulations! you have successfully set up a medusa server. There are still other things you can configure like JWT and Cookie Secrets, CORS and Plugins. For additional information, check out the official docs about Server Configurations. You can also read about how to set up a Medusa Admin or read about the Storefront REST API to create Storefronts.