Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/u11d-com/medusa-starter

medusa-starter - Starter templates for Medusa.js e-commerce development with Docker and Docker Compose.
https://github.com/u11d-com/medusa-starter

cicd docker docker-compose dockerfile e-commerce ecommerce local-development medusa medusajs nextjs nodejs open-source starter-kit starter-template typescript

Last synced: 4 months ago
JSON representation

medusa-starter - Starter templates for Medusa.js e-commerce development with Docker and Docker Compose.

Awesome Lists containing this project

README 

          
# Project Starter Templates for Medusa Commerce Platform



![v2 Build Status](https://img.shields.io/github/actions/workflow/status/u11d-com/medusa-starter/docker_build_v2.yml?branch=v2&label=Medusa%20v2%20build) ![v1 Build Status](https://img.shields.io/github/actions/workflow/status/u11d-com/medusa-starter/docker_build_v1.yml?branch=v1&label=Medusa%20v1%20build)



## Introduction



This project provides developers with starter templates for both the backend and storefront using the **Medusa framework**. The primary objectives are to demonstrate:



- How to configure a development environment using **Docker Compose**.

- How to structure a **GitHub workflow pipeline** for building and deploying a Medusa project.



## About Medusa



[Medusa](https://medusajs.com/) is a modular commerce framework designed for building advanced e-commerce applications without reinventing core commerce logic. Medusa’s flexible architecture allows developers to create:



- Scalable e-commerce stores

- Multi-vendor marketplaces

- Any application requiring foundational commerce functionality



All modules are open-source and available on npm, providing full customization and extensibility.



## Project Structure Overview



The `medusa-starter` repository is organized to provide a clear, modular structure for managing both the backend and storefront of a Medusa-based commerce platform. The setup leverages Docker Compose for service orchestration and includes essential configuration files for streamlined development, testing, and deployment.



### Directory Layout



```shell

medusa-starter/

├── .github/                 # GitHub workflows and automation scripts

├── .vscode/                 # VS Code workspace settings

├── backend/                 # Medusa backend services

│   ├── .dockerignore        # Defines files to exclude from Docker builds

│   ├── Dockerfile           # Instructions to build the backend Docker image

│   └── start.sh             # Script to handle migrations, admin user creation, and start backend

├── storefront/              # Next.js storefront application

│   ├── .dockerignore        # Defines files to exclude from Docker builds

│   └── Dockerfile           # Instructions to build the storefront Docker image

├── .editorconfig            # Maintains consistent coding styles

├── compose.seed.yaml        # Docker Compose file for database seeding

├── compose.storefront.yaml  # Docker Compose file for storefront services

├── compose.yaml             # Main Docker Compose file orchestrating all services

├── LICENSE                  # License information

└── README.md                # Project documentation

```



### Key Components



- `.github/` - Contains GitHub Actions workflows to automate CI/CD processes, ensuring smooth integration and deployment pipelines.

- `.vscode/` - Houses workspace settings to standardize development environments across teams using Visual Studio Code.

- `backend/` - This directory includes the Medusa backend setup:

  - `.dockerignore`: Lists files and directories to ignore during Docker builds.

  - `Dockerfile`: Defines the build instructions for the backend container.

  - `start.sh`: A shell script to automate database migrations, create an admin user if necessary, and start the Medusa backend in cluster mode.

  - `medusa-config.ts`: Example of configuration for Medusa.

- `storefront/` - The Next.js storefront application:

  - `.dockerignore`: Specifies files to exclude from the Docker image build.

  - `Dockerfile`: Instructions for building the storefront Docker image.

  - `next.config.js`: Example of configuration for Next.js deployment in standalone mode.

- Docker Compose Files:

  - `compose.yaml`: The primary file orchestrating PostgreSQL, Redis, and the Medusa backend services.

  - `compose.storefront.yaml`: Manages the storefront container separately to ensure modular service management.

  - `compose.seed.yaml`: Handles database seeding tasks.

  - `compose.db.yaml`: Can be used to deploy database separately.

- Other Configurations:

  - `.editorconfig`: Ensures consistent code formatting across different editors and IDEs.

  - `LICENSE`: Provides licensing information for the repository.

  - `README.md`: Offers comprehensive project documentation.



## Installation & Setup



### Prerequisites



Ensure you have the following installed:



- [Docker](https://docs.docker.com/get-started/get-docker/)

- [Docker Compose](https://docs.docker.com/compose/install/)

- [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)



### Cloning the Repository



Run the following command:



```shell

git clone https://github.com/u11d-com/medusa-starter.git

cd medusa-starter

```



## Setup Using Medusa CLI



You can use the `create-medusa-app` command to generate a starter Medusa project.



### 1. Start Databases



Run the following command to start the database services:



```shell

docker compose -f compose.db.yaml up -d

```



- **PostgreSQL** will be available at `localhost:5432`.

- **Redis** will be available at `localhost:6379`.

- Default credentials:



  ```plaintext

  POSTGRES_USER: medusa-starter

  POSTGRES_PASSWORD: medusa-password

  POSTGRES_DB: medusa-starter

  ```



Modify `compose.db.yaml` to change these values.



### 2. Create a Medusa Project



Follow the [Medusa installation guide](https://docs.medusajs.com/learn/installation) to create your first project using `create-medusa-app`.



### 3. Add Containerization



Use the Docker setup provided in this repository to containerize your project. Copy files from the `backend` and `storefront` directories to their respective locations in your project. Then, use these files to build Docker images for your application.



## Setup Using Git



### 1. Initialize the Backend Repository



Run the following commands:



```shell

git clone https://github.com/medusajs/medusa-starter-default.git

```



Copy and replace files from `backend` folder to created directory.



This sets up the Medusa backend starter template (Medusa v2).



### 2. Initialize the Storefront Repository



Run the following commands:



```shell

git clone https://github.com/medusajs/nextjs-starter-medusa.git

```



Copy and replace files from `storefront` folder to created directory.



This sets up the Medusa storefront starter template (Medusa v2).



---



## Running the Development Environment



### Optional: Enable Meilisearch Search



To integrate Meilisearch, add the `medusa-plugin-meilisearch` package to your project:



```shell

npm install @rokmohar/medusa-plugin-meilisearch

# or

yarn add @rokmohar/medusa-plugin-meilisearch

```



### 1. Start the Medusa Backend and Services



```shell

docker compose up --build -d

```



### 2. Seed the Database



Run this command once (unless the database volume is deleted):



```shell

docker compose -f compose.seed.yaml run --rm seed

```



### 3. Start the Storefront



You need NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY value from Medusa backend admin panel.

Log in to `localhost:9000/app` with credentials from `compose.yaml` file:



```plaintext

MEDUSA_ADMIN_EMAIL: admin@medusa-test.com

MEDUSA_ADMIN_PASSWORD: supersecret

```



You can find publishable key value in dashboard settings. Change it's value in `compose.storefront.yaml` file and run command:



```shell

docker compose -f compose.storefront.yaml up --build

```



### 4. Stopping the Development Environment



To stop services, run:



- Stop the storefront:



  ```shell

  docker compose -f compose.storefront.yaml down

  ```



- Stop the backend and other services:



  ```shell

  docker compose down

  ```



---



## Notes



- `docker compose up -d` initializes the backend services for Medusa.

- The database seeding step pre-populates the database with sample data and is only required when setting up a new database.

- Storefront services are started separately for better modularity.

- Shutting down the environment when not in use frees system resources.



Your environment should now be up and running! You can access the storefront and backend services as configured in the compose files.



---



## Customization



This project is designed to be flexible.



### Replacing the Default Templates



You can replace the backend and storefront templates with your own code while preserving the following essential files:



- `Dockerfile`

- `.dockerignore`



### Backend Customization



The backend runs on **Node.js** and can be customized using **TypeScript**. Replace the provided template with your own implementation while ensuring compatibility with Medusa.



### Storefront Customization



The storefront runs on **Next.js**. To create a new storefront, use:



```shell

npx create-next-app@latest

```



Once your custom backend and storefront are ready, the provided Docker Compose configuration will handle deployment.



---



## Deployment



This project includes a pre-configured **GitHub workflow pipeline** for building and deploying Medusa-based applications.



### Image Tags



The workflow generates images with the following tags:



- `medusajs-backend:`

- `medusajs-storefront:`



(Replace `` with the version or commit identifier.)



For Medusa v1, we provide the latest available starter configuration:



- `medusajs-backend:1.20.10-latest`

- `medusajs-storefront:1.18.1-latest`



For Medusa v2, we provide the latest available starter configuration:



- `medusajs-backend:-latest`

- `medusajs-storefront:-latest`



### Customizing Deployment



The GitHub workflow can be customized for different cloud providers (e.g., AWS, Google Cloud). Modify `.github/workflows` to:



- Add deployment steps.

- Configure cloud provider settings.

- Integrate with CI/CD pipelines.



This ensures flexibility for production environments.



---



## Appendices



### Contact Information



For support or inquiries, visit:



[Uninterrupted](https://u11d.com)



---



:heart: _Technology made with passion by [u11d](https://u11d.com)_