# Medusa Commerce

> Open-source Shopify alternative.

- Category: E-Commerce & Business
- Difficulty: intermediate
- Components: medusa, postgres, redis
- Tags: medusa, ecommerce, headless, api
- Source: https://docker.recipes/ecommerce/medusa

## Overview

Medusa is an open-source, headless commerce platform built with Node.js that provides a modern alternative to Shopify and other traditional e-commerce solutions. Developed as a composable commerce engine, Medusa separates the backend commerce logic from the frontend presentation layer, enabling developers to build custom storefronts using any technology stack while maintaining powerful commerce functionality including inventory management, order processing, customer management, and payment handling. The platform emphasizes developer experience with a plugin-based architecture and comprehensive REST APIs.

This Docker stack combines Medusa with PostgreSQL and Redis to create a production-ready headless commerce backend. PostgreSQL serves as the primary database storing product catalogs, customer data, orders, and inventory information, leveraging its ACID compliance and JSON support for complex e-commerce data structures. Redis handles session management, caching frequently accessed product data, and managing background job queues for order processing and email notifications. This combination provides the data persistence, performance, and reliability needed for modern e-commerce operations.

This configuration is ideal for developers building custom e-commerce solutions, agencies creating unique shopping experiences for clients, and businesses requiring commerce functionality that traditional platforms cannot provide. The headless architecture allows frontend teams to use React, Vue.js, or mobile frameworks while the backend handles all commerce operations, making it perfect for omnichannel retail strategies, B2B marketplaces, and businesses with complex product catalogs or unique checkout flows.

## Features

- Headless commerce API with complete product, order, and customer management endpoints
- Built-in multi-region and multi-currency support for global e-commerce operations
- Extensible plugin system supporting Stripe, PayPal, and custom payment processors
- Advanced inventory management with variant tracking and stock location handling
- PostgreSQL JSON columns for flexible product attributes and custom metadata storage
- Redis-powered session management and background job processing for order fulfillment
- Discount engine supporting percentage, fixed-amount, and free shipping promotions
- Tax calculation system with region-based tax rates and exemption handling

## Use cases

- Building custom storefronts with React, Next.js, or Gatsby for unique brand experiences
- Creating B2B marketplaces with complex pricing structures and buyer approval workflows
- Developing mobile commerce apps with native iOS/Android frontends consuming Medusa APIs
- Launching subscription box services with recurring billing and inventory automation
- Building omnichannel retail solutions connecting online stores with POS systems
- Creating marketplace platforms where multiple vendors can manage their own products
- Developing international e-commerce sites requiring multi-currency and tax compliance

## Prerequisites

- Docker and Docker Compose installed with at least 2GB available RAM for all services
- Port 9000 available for the Medusa API and admin panel access
- Basic understanding of REST APIs and headless commerce concepts
- Node.js knowledge for customizing Medusa plugins and configurations
- Frontend framework experience (React, Vue.js, or mobile) for building storefronts
- Environment variables configured for JWT_SECRET, COOKIE_SECRET, and database credentials

## docker-compose.yml

```yaml
services:
  medusa:
    image: medusajs/medusa:latest
    container_name: medusa
    restart: unless-stopped
    environment:
      DATABASE_URL: postgres://${DB_USER}:${DB_PASSWORD}@postgres:5432/${DB_NAME}
      REDIS_URL: redis://redis:6379
      JWT_SECRET: ${JWT_SECRET}
      COOKIE_SECRET: ${COOKIE_SECRET}
    ports:
      - "9000:9000"
    depends_on:
      - postgres
      - redis
    networks:
      - medusa

  postgres:
    image: postgres:16-alpine
    container_name: medusa-postgres
    environment:
      POSTGRES_DB: ${DB_NAME}
      POSTGRES_USER: ${DB_USER}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - medusa

  redis:
    image: redis:alpine
    container_name: medusa-redis
    networks:
      - medusa

volumes:
  postgres_data:

networks:
  medusa:
    driver: bridge
```

## .env

```bash
DB_NAME=medusa
DB_USER=medusa
DB_PASSWORD=changeme
JWT_SECRET=your-jwt-secret
COOKIE_SECRET=your-cookie-secret
```

## Usage notes

- Docs: https://docs.medusajs.com/
- API at http://localhost:9000, admin at http://localhost:9000/app
- Seed data: docker exec medusa medusa seed --seed-file=data/seed.json
- Headless commerce: use Next.js or Gatsby storefront templates
- Built-in support for Stripe, PayPal, manual payments
- Extensible plugin system for custom functionality

## Troubleshooting

- Medusa container exits with 'Cannot connect to database': Ensure PostgreSQL container is fully initialized before Medusa starts, add healthcheck or delay
- Admin panel shows 'Unauthorized' errors: Verify JWT_SECRET and COOKIE_SECRET environment variables are set and consistent across restarts
- Product images not loading: Configure S3 or local file service plugin, check file upload permissions and storage volume mounts
- Redis connection errors during checkout: Confirm Redis container is running and REDIS_URL environment variable matches the service name
- Database migration failures on startup: Clear postgres_data volume and restart with fresh database, or run migrations manually with docker exec
- API requests timing out: Increase container memory allocation, PostgreSQL may need more RAM for complex product queries and indexing

