How to Setup A Medusa Server Locally
Tags: javascript, webdev, tutorial, opensource
Published: 2022-10-08 04:46:57

[Medusa](https://medusajs.com) 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](https://nodejs.dev/en/learn/how-to-install-nodejs) on how to install NodeJS.

### Install the Medusa CLI
Install the Medusa CLI globally using NPM

```bash
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`.

```bash
medusa new watch-store-medusa-server --seed
```


### Start the Medusa Server

Navigate to our medusa server project directory and start the server

```bash
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.

```bash
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](https://www.postgresqltutorial.com/postgresql-getting-started/install-postgresql/), [Linux](https://www.postgresqltutorial.com/install-postgresql-linux) and [macOS](https://flaviocopes.com/postgres-how-to-install/)

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.

```bash
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](https://stackoverflow.com/a/57466346/12538899) : `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:

```bash

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

```

### Configure Postgres in `medusa-config.js`

```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](https://redis.io/docs/getting-started/installation) on your computer.

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

```bash
redis-server -v
```


### Start Redis Server

Learn how to start and stop a Redis server with [this tutorial](https://tableplus.com/blog/2018/10/how-to-start-stop-restart-redis.html)

```bash
# 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`

```bash
REDIS_URL=redis://localhost:6379
```

### Configure Redis in medusa-config.js

```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.

```bash
# 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](https://docs.min.io/minio/baremetal/quickstart/quickstart.html).  


### 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.

```bash
# 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.

![Terminal screenshot of the minio server running](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/tbgth9ui9cofa5pwm0gc.png)


### **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”.

![Screenshot of MinIO Console](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/hvwy67m8bjsk7v8lnu0a.png)

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 the “Buckets” button on the sidebar, then the “Manage” button.](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/5bwvomlrf8r4cuj3a9qh.png)


Click on the Access Policy button and set it to public.
![Click on the Access Policy button and set it to public.](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/1co1wm9ufhmey1ax0jpa.png)

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.


![MinIO Console Screeshot](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/rd4sm91q74pho6dm2aw0.png)

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.

![MinIO Console Screeshot](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/1rv57pdh8a9c4fbmiu83.png)


### Install Medusa MinIO Plugin

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

```bash
npm install medusa-file-minio
```

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

```env
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:

```env
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. 
```js
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](https://nextjs.org/docs/messages/next-image-unconfigured-host) error.

```js
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.

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


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

```

![Terminal Screenshot](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/z59wnlwaspjpw0ui3jc0.png)

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](https://docs.medusajs.com/usage/configurations). You can also read about how to set up a [Medusa Admin](https://docs.medusajs.com/admin/quickstart) or read about the [Storefront REST API](https://docs.medusajs.com/api/store/)  to create Storefronts.