Set up Development Environment

This document will guide you to set up your development environment to efficiently and properly use Medusa.

Required Tools

To get your development environment ready you need to install the following tools:

Node.js

Node.js is the environment that makes it possible for Medusa to run, so you must install Node.js on your computer to start Medusa development.

Medusa supports versions 14 and 16 of Node.js. You can check your Node.js version using the following command:

node -v

Windows

You can install the executable directly from the Node.js website.

For other approaches, you can check out Node.js’s guide.

Linux

You can use the following commands to install Node.js on Ubuntu:

#Ubuntu
sudo apt update
sudo apt install nodejs

For other Linux distributions, you can check out Node.js’s guide.

macOS

You can use the following commands to install Node.js on macOS:

Homebrew

brew install node

Without Homebrew

curl \
 "https://nodejs.org/dist/latest/node-${VERSION:-$(wget -qO- \
  https://nodejs.org/dist/latest/ | sed -nE \ 
  's|.*>node-(.*)\.pkg</a>.*|\1|p')}.pkg" \
  > "$HOME/Downloads/node-latest.pkg" && 
  sudo installer -store -pkg "$HOME/Downloads/node-latest.pkg" -target "/"

For other approaches, you can check out Node.js’s guide.

Make sure that you have Xcode command line tools installed; if not, run the following command to install it: xcode-select --install

Git

Medusa uses Git behind the scenes when you create a new project so you'll have to install it on your computer to get started.

Windows

To install Git on Windows, you need to download the installable package.

Linux

For Debian/Ubuntu, you can use the following command:

apt-get install git

As for other Linux distributions, please check git’s guide.

macOS

You should already have Git installed as part of the Xcode command-line tools.

However, if for any reason you need to install it manually, you can install it with Homebrew:

brew install git

You can also check out git’s guide for more installation options.

Medusa CLI

The final installation required to get started with Medusa is the Medusa CLI. It is an NPM package you can install globally on your machine to get instant access to commands that help you manage and run your Medusa project.

You can install Medusa’s CLI with the following command:

npm

npm install @medusajs/medusa-cli -g

Yarn

yarn global add @medusajs/medusa-cli

You can check that Medusa was installed by running the following command:

medusa -v

If you run into any errors while installing the CLI tool, check out the troubleshooting guide.

---

Install Medusa Server

If you're not interested in installing the optional tools and want to get started quickly, check out the quickstart guide.

---

Optional Tools

These tools are not required to have to run a Medusa server, but it's highly recommended that you have them installed.

PostgreSQL

Although you can use an SQLite database with Medusa which would require no necessary database installations, it is recommended to use a PostgreSQL database for your server.

After installing PostgreSQL, check out the Configure your Server documentation to learn how to configure PostgreSQL to work with Medusa.

Windows

You can download the PostgreSQL Windows installer from their website.

Linux

If you’re using Ubuntu, you can use the following commands to download and install PostgreSQL:

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

For other distributions, you can check out PostgreSQL’s website for more guides.

macOS

You can download PostgreSQL on your macOS using the installer on their website.

Docker

Make sure the Docker Desktop app is running, then run the following command to quickly spin up a PostgreSQL instance:

docker run --name postgres -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=postgres -e \
  POSTGRES_DB=medusa-docker -p 5432:5432 -d postgres

Where:

• --name creates a new container named postgres.
• -e creates environment variables POSTGRES_USER, POSTGRES_PASSWORD and POSTGRES_DB. These will be used to set up a database named medusa-docker with the username and password being postgres.
• -p maps the container port 5432 to the external host 5432. This allows you to connect to the database server from outside of the container.
• -d enables Docker to run the container in the background.
• The last section of the command, postgres grabs the latest postgres image from the Docker hub.

Redis

Medusa uses Redis as the event queue in the server. If you want to use subscribers to handle events such as when an order is placed and perform actions based on the events, then you need to install and configure Redis.

If you don’t install and configure Redis with your Medusa server, then it will work without any events-related features.

After installing Redis, check out the Configure your Server documentation to learn how to configure Redis to work with Medusa.

Windows

To use Redis on Windows, you must have Windows Subsystem for Linux (WSL2) enabled. This lets you run Linux binaries on Windows.

After installing and enabling WSL2, if you use an Ubuntu distribution you can run the following commands to install Redis:

sudo apt-add-repository ppa:redislabs/redis
sudo apt-get update
sudo apt-get upgrade
sudo apt-get install redis-server

## Start Redis server
sudo service redis-server start

Linux

If you use Ubuntu you can use the following commands to install Redis:

curl -fsSL https://packages.redis.io/gpg | \
  sudo gpg --dearmor -o /usr/share/keyrings/redis-archive-keyring.gpg

echo "deb [signed-by=/usr/share/keyrings/redis-archive-keyring.gpg] https://packages.redis.io/deb $(lsb_release -cs) main" \
  | sudo tee /etc/apt/sources.list.d/redis.list

sudo apt-get update
sudo apt-get install redis

## Start Redis server
sudo service redis-server start

For other distributions, you can check out Redis’ guide on this.

macOS

You can install Redis on macOS using Homebrew with the following command:

brew install redis

## Start Redis server
brew services start redis

To install Redis without Homebrew you can check out Redis’s guide on installing it from source.

---

See Also

• Install Medusa server
• Configure your Medusa server.
• Install a storefront with Next.js or Gatsby.
• Install the Medusa Admin.