1.2.1. Install Medusa with Docker

In this chapter, you'll learn how to install and run a Medusa application using Docker.

The main supported installation method is using create-medusa-app. However, since it requires prerequisites like PostgreSQL, Docker may be a preferred and easier option for some users. You can follow this guide to set up a Medusa application with Docker in this case.

You can follow this guide on any operating system that supports Docker, including Windows, macOS, and Linux.

1. Clone Medusa Starter Repository#

To get started, clone the Medusa Starter repository that a Medusa application is based on:

Terminal
❯git clone https://github.com/medusajs/medusa-starter-default.git --depth=1 my-medusa-store

This command clones the repository into a directory named my-medusa-store.

Make sure to change into the newly created directory:

Terminal
❯cd my-medusa-store

The rest of the steps will be performed inside this directory.

2. Create docker-compose.yml#

In the cloned repository, create a file named docker-compose.yml with the following content:

docker-compose.yml
1services:2  # PostgreSQL Database3  postgres:4    image: postgres:15-alpine5    container_name: medusa_postgres6    restart: unless-stopped7    environment:8      POSTGRES_DB: medusa-store9      POSTGRES_USER: postgres10      POSTGRES_PASSWORD: postgres11    ports:12      - "5432:5432"13    volumes:14      - postgres_data:/var/lib/postgresql/data15    networks:16      - medusa_network17
18  # Redis19  redis:20    image: redis:7-alpine21    container_name: medusa_redis22    restart: unless-stopped23    ports:24      - "6379:6379"25    networks:26      - medusa_network27
28  # Medusa Server29  # This service runs the Medusa backend application30  # and the admin dashboard.31  medusa:32    build: .33    container_name: medusa_backend34    restart: unless-stopped35    depends_on:36      - postgres37      - redis38    ports:39      - "9000:9000"40    environment:41      - NODE_ENV=development42      - DATABASE_URL=postgres://postgres:postgres@postgres:5432/medusa-store43      - REDIS_URL=redis://redis:637944    env_file:45      - .env46    volumes:47      - .:/server48      - /server/node_modules49    networks:50      - medusa_network51
52volumes:53  postgres_data:54
55networks:56  medusa_network:57    driver: bridge

You define three services in this file:

• postgres: The PostgreSQL database service that stores your Medusa application's data.
• redis: The Redis service that stores session data.
• medusa: The Medusa service that runs the server and the admin dashboard. It connects to the PostgreSQL and Redis services.

You can add environment variables either in the environment section of the medusa service or in a separate .env file.

Recommendations for Multiple Local Projects#

If this isn't the first Medusa project you're setting up with Docker on your machine, make sure to:

• Change the container_name for each service to avoid conflicts.
  • For example, use medusa_postgres_myproject, medusa_redis_myproject, and medusa_backend_myproject instead of the current names.
• Change the volume names to avoid conflicts.
  • For example, use postgres_data_myproject instead of postgres_data.
• Change the network name to avoid conflicts.
  • For example, use medusa_network_myproject instead of medusa_network.
• Change the ports to avoid conflicts with other projects. For example:
  • Use "5433:5432" for PostgreSQL.
  • Use "6380:6379" for Redis.
  • Use "9001:9000" for the Medusa server.
• Update the DATABASE_URL and REDIS_URL environment variables accordingly.

3. Create start.sh#

Next, you need to create a script file that runs database migrations and starts the Medusa development server.

Create the file start.sh with the following content:

Make sure to give the script executable permissions:

Terminal
❯chmod +x start.sh

4. Create Dockerfile#

The Dockerfile defines how the Medusa service is built.

Create a file named Dockerfile with the following content:

In the Dockerfile, you use the node:20-alpine image as the base since Medusa requires Node.js v20 or later.

Then, you set the working directory to /server, copy the necessary files, install dependencies, expose the 9000 port that Medusa uses, and run the start.sh script to start the server.

5. Install Dependencies#

The Medusa Starter repository has a yarn.lock file that was generated by installing dependencies with Yarn v1.22.19.

If you're using a different Yarn version, or you're using NPM, you need to install the dependencies again to ensure compatibility with the Docker setup.

To install the dependencies, run the following command:

This will update yarn.lock or generate a package-lock.json file, depending on your package manager.

6. Update Scripts in package.json#

Next, you need to update the scripts section in your package.json file to start the development server using Docker.

Add the following scripts in package.json:

package.json
1{2  "scripts": {3    // Other scripts...4    "docker:up": "docker compose up --build -d",5    "docker:down": "docker compose down"6  }7}

Where:

• docker:up starts the development server in a Docker container as a background process.
• docker:down stops and removes the Docker containers.

7. Update Medusa Configuration#

If you try to run the Medusa application now with Docker, you'll encounter an SSL error as the server tries to connect to the PostgreSQL database.

To resolve the error, add the following configurations in medusa-config.ts:

medusa-config.ts
1import { loadEnv, defineConfig } from "@medusajs/framework/utils"2
3loadEnv(process.env.NODE_ENV || "development", process.cwd())4
5module.exports = defineConfig({6  projectConfig: {7    // ...8    databaseDriverOptions: {9      ssl: false,10      sslmode: "disable",11    },12  },13})

You add the projectConfig.databaseDriverOptions to disable SSL for the PostgreSQL database connection.

8. Add .dockerignore#

To ensure only the necessary files are copied into the Docker image, create a .dockerignore file with the following content:

.dockerignore
1node_modules2npm-debug.log*3yarn-debug.log*4yarn-error.log*5.git6.gitignore7README.md8.env.test9.nyc_output10coverage11.DS_Store12*.log13dist14build

9. Create .env File#

You can add environment variables either in the environment section of the medusa service in docker-compose.yml or in a separate .env file.

If you don't want to use a .env file, you can remove the env_file section from the medusa service in docker-compose.yml.

Otherwise, copy the .env.template file to .env and update the values as needed.

10. Start the Medusa Application with Docker#

All configurations are now ready. You can start the Medusa application using Docker by running the following command:

npm
yarn
pnpm

Docker will pull the necessary images, start the PostgreSQL and Redis services, build the Medusa service, and run the development server in a Docker container.

You can check the logs to ensure everything is running smoothly with the following command:

Terminal
❯docker compose logs -f

Once you see the following message, the Medusa server and admin are ready:

Code
1✔ Server is ready on port: 9000 – 3ms2info:    Admin URL → http://localhost:9000/app

You can now access the Medusa server at http://localhost:9000 and the Medusa Admin dashboard at http://localhost:9000/app.

Create Admin User#

To create an admin user, run the following command:

Terminal
❯docker compose run --rm medusa npx medusa user -e admin@example.com -p supersecret

Make sure to replace admin@example.com and supersecret with your desired email and password.

You can now log in to the Medusa Admin dashboard at http://localhost:9000/app using the email and password you just created.

Stop the Medusa Application Running in Docker#

To stop the Medusa application running in Docker, run the following command:

npm
yarn
pnpm

This command stops and removes the Docker containers created by the docker-compose.yml file.

This doesn't delete any data in your application or its database. You can start the server again using the docker:up command.

Check Logs#

You can check the logs of the Medusa application running in Docker using the following command:

Terminal
❯docker compose logs -f medusa

This command shows the logs of the medusa service, allowing you to see any errors or messages from the Medusa application.

Troubleshooting#

start.sh Not Found Error#

If you get the following error when starting the Medusa application with Docker:

Terminal
❯medusa_backend exited with code 127 (restarting)❯medusa_backend   | /usr/local/bin/docker-entrypoint.sh: exec: line 11: ./start.sh: not found

This is a common error for Windows users. It usually occurs when the start.sh file uses CRLF line endings instead of LF.

To fix this, ensure that the start.sh file uses LF line endings. You can configure Git to maintain LF line endings by following this guide from GitHub.

Couldn't Find X File or Directory Errors#

If you encounter errors indicating that certain files or directories couldn't be found, make sure you're running the commands from the root directory of your Medusa application (the same directory where the docker-compose.yml file is located).

For example, if you run the docker:up command and see an error like this:

Terminal
❯error Couldn't find a package.json file in "/"

Ensure that your terminal's current working directory is the root of your Medusa application, then try running the command again.

Container Name Conflicts#

If you're running multiple Medusa projects with Docker or have previously run this guide, you may encounter container name conflicts.

To resolve this, ensure that the container_name values in your docker-compose.yml file are unique for each project. You can modify them by appending a unique identifier to each name.

For example, change:

docker-compose.yml
container_name: medusa_postgres

to

docker-compose.yml
container_name: medusa_postgres_myproject

Learn More about your Medusa Application#

You can learn more about your Medusa application and its setup in the Installation chapter.