Skip to main content

Install Medusa Backend

This document will guide you through setting up your Medusa backend in a three steps.

Prerequisites​

Before you can install and use Medusa, you need the following tools installed on your machine:

Create a Medusa Backend​

It is recommended to use Yarn for the installation process as it's much faster than using NPM.

1. Install Medusa CLI​

To install the Medusa backend, you need Medusa's CLI tool. You can install it globally or, alternatively, use it through npx with npx @medusajs/medusa-cli <command>.

npm install @medusajs/medusa-cli -g

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

2. Create a new Medusa project​

medusa new my-medusa-store # or npx @medusajs/medusa-cli new

You'll then be asked to specify your PostgreSQL database credentials. You can choose "Continue" to use the default credentials shown in the terminal, choose "Change credentials" to specify your PostgreSQL credentails, or choose "Skip database setup" to create the database later.

If you choose "Skip database setup" you will need to set the database configurations and run migrations later.

3. Start your Medusa backend​

Make sure your PostgreSQL server is running before you run the Medusa backend.

cd my-medusa-store
medusa develop # or npx @medusajs/medusa-cli develop

After these three steps and in only a couple of minutes, you now have a complete commerce engine running locally. You can test it out by sending a request using a tool like Postman or through the command line:

curl localhost:9000/store/products
Did you set up the backend successfully?

Troubleshooting Installation​

Error: SASL: SCRAM-SERVER-FIRST-MESSAGE: Client password must be a string

You may get the following error while running medusa new or while running integration tests during local development:

Error: SASL: SCRAM-SERVER-FIRST-MESSAGE: client password must be a string

If the error occurs while running medusa new and you've selected to enter your database credentials, either:

  1. Make sure your database credentials are correct;
  2. Or choose the Skip option to skip entering your database credentials.

If the error occurs while running integration tests, make sure the following variable is set in your system's environment variable:

DB_HOST=<YOUR_DB_HOST>
DB_USERNAME=<YOUR_DB_USERNAME>
DB_PASSWORD=<YOUR_PASSWORD>
Error: connect ECONNREFUSED ::1:5432

When you start your Medusa backend you may run into the following error:

Error: connect ECONNREFUSED ::1:5432

This error occurs because the backend couldn't connect to the PostgreSQL database. The issue could be one of the following:

  1. PostgreSQL server isn't running. Make sure it's always running while the Medusa backend is running.
  2. The connection URL to your PostgreSQL database is incorrect. This could be because of incorrect credentials, port number, or connection URL format. The format should be postgres://[user][:password]@[host][:port]/[dbname]. Make sure that the connection URL format is correct, and the credentials passed in the URL are correct. You can learn more about formatting the connection URL here
Error: EADDRINUSE

When you run your backend you may run to an error similar to the following:

code: 'EADDRINUSE',
errno: -48,
syscall: 'Listen',
address: '::',
port: 9000

This means that there's another process running at port 9000. You need to either:

  • Change the default port used by the Medusa backend. You can do that by setting the PORT environment variable to a new port. When you do this, make sure to change the port used in other apps that interact with your Medusa backend, such as in your admin or storefront.
  • Terminate other processes running on port 9000.
AwilixResolutionError: Could Not Resolve X

If you get the error on a fresh installation of the Medusa backend, or you haven't made any customizations that would cause this error, try to remove the node_modules directory, then run the following command in the root directory of the Medusa backend to re-install the dependencies:

npm install

Seed Data​

For better testing, you can add demo data to your Medusa backend by running the seed command in your Medusa backend directory:

medusa seed --seed-file=data/seed.json
# or npx @medusajs/medusa-cli seed --seed-file=data/seed.json

Health Route​

You can access /health to get health status of your backend.

Next Steps​

Was this page helpful?
© 2023 Medusa, Inc. All rights reserved.