# Medusa Headless Commerce

> Open-source Shopify alternative with headless architecture.

- Category: E-Commerce & Business
- Difficulty: intermediate
- Components: medusa-server, postgresql, redis, minio, admin-ui
- Tags: medusa, ecommerce, headless, shopify-alternative, nodejs
- Source: https://docker.recipes/ecommerce/medusa-ecommerce

## Overview

Medusa is a modern Node.js-based headless commerce platform that provides a flexible alternative to Shopify, focusing on API-first architecture and developer experience. Built with TypeScript and designed for customization, Medusa offers comprehensive e-commerce functionality including product management, order processing, customer management, and payment handling through a robust REST API. The platform emphasizes modularity and extensibility, allowing developers to build custom storefronts using any frontend technology while maintaining powerful backend commerce capabilities. This stack combines Medusa's commerce engine with PostgreSQL for transactional data integrity, Redis for session management and caching, and MinIO for self-hosted object storage, creating a complete commerce infrastructure. PostgreSQL ensures ACID compliance for critical order and payment data, while Redis provides fast session storage and job queue processing for background tasks like email notifications and inventory updates. MinIO handles product images, digital downloads, and media assets with S3-compatible APIs, eliminating dependency on external cloud storage providers. E-commerce startups, agencies building custom storefronts, and companies migrating from monolithic platforms like Shopify Plus will benefit from this stack's flexibility and cost-effectiveness. The headless architecture enables omnichannel commerce experiences across web, mobile, and IoT devices while maintaining centralized inventory and order management through Medusa's comprehensive admin interface.

## Features

- Complete headless commerce API with product catalog, inventory, orders, and customer management
- Multi-region and multi-currency support with localized pricing and tax calculation
- Built-in payment provider integrations including Stripe, PayPal, and manual payment methods
- Advanced product variant management with unlimited options and custom attributes
- Discount engine supporting percentage, fixed amount, and buy-X-get-Y promotional rules
- PostgreSQL JSONB fields for flexible product metadata and custom attributes storage
- Redis-powered job queue system for asynchronous email sending and webhook processing
- MinIO integration for product images, digital downloads, and customer file uploads with S3-compatible URLs

## Use cases

- Building custom D2C e-commerce stores with React, Vue, or Next.js frontends
- Creating multi-tenant marketplace platforms with separate vendor catalogs and commission tracking
- Developing mobile commerce apps with native iOS/Android frontends consuming Medusa APIs
- Implementing B2B wholesale portals with custom pricing tiers and approval workflows
- Setting up subscription commerce platforms with recurring billing and customer portals
- Deploying white-label e-commerce solutions for agencies serving multiple clients
- Creating omnichannel retail experiences connecting online stores with POS systems

## Prerequisites

- Minimum 4GB RAM (2GB for PostgreSQL, 1GB for Medusa server, 512MB each for Redis and MinIO)
- Node.js 18+ knowledge for Medusa customization and plugin development
- PostgreSQL administration skills for backup, maintenance, and performance tuning
- Understanding of JWT authentication and session management concepts
- Ports 7001, 9000, and 9001 available for admin interface, API server, and MinIO console
- Basic S3 API knowledge for implementing file upload workflows in custom frontends

## docker-compose.yml

```yaml
services:
  medusa-server:
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - "9000:9000"
    environment:
      NODE_ENV: development
      DATABASE_URL: postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}
      REDIS_URL: redis://redis:6379
      JWT_SECRET: ${JWT_SECRET}
      COOKIE_SECRET: ${COOKIE_SECRET}
      MINIO_ENDPOINT: minio
      MINIO_BUCKET: medusa
      MINIO_ACCESS_KEY: ${MINIO_ACCESS_KEY}
      MINIO_SECRET_KEY: ${MINIO_SECRET_KEY}
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_started
    networks:
      - medusa-net
    restart: unless-stopped

  medusa-admin:
    image: medusajs/admin:latest
    ports:
      - "7001:80"
    environment:
      MEDUSA_BACKEND_URL: http://medusa-server:9000
    depends_on:
      - medusa-server
    networks:
      - medusa-net
    restart: unless-stopped

  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: ${POSTGRES_DB}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - medusa-net
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    volumes:
      - redis_data:/data
    networks:
      - medusa-net
    restart: unless-stopped

  minio:
    image: minio/minio:latest
    ports:
      - "9001:9001"
    environment:
      MINIO_ROOT_USER: ${MINIO_ACCESS_KEY}
      MINIO_ROOT_PASSWORD: ${MINIO_SECRET_KEY}
    volumes:
      - minio_data:/data
    command: server /data --console-address ":9001"
    networks:
      - medusa-net
    restart: unless-stopped

volumes:
  postgres_data:
  redis_data:
  minio_data:

networks:
  medusa-net:
    driver: bridge
```

## .env

```bash
# Medusa Configuration
JWT_SECRET=$(openssl rand -hex 32)
COOKIE_SECRET=$(openssl rand -hex 32)

# PostgreSQL
POSTGRES_USER=medusa
POSTGRES_PASSWORD=secure_postgres_password
POSTGRES_DB=medusa

# MinIO
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=secure_minio_password
```

## Usage notes

- Create Medusa project: npx create-medusa-app
- Medusa Admin at http://localhost:7001
- API at http://localhost:9000
- Run migrations: medusa migrations run

## Troubleshooting

- Medusa migrations fail with 'relation does not exist': Run 'medusa migrations run' after PostgreSQL is fully initialized and healthy
- Admin UI shows 'Cannot connect to server': Verify MEDUSA_BACKEND_URL environment variable points to http://medusa-server:9000, not localhost
- Product image uploads return 403 errors: Check MinIO bucket policy allows public read access and MINIO_ENDPOINT uses service name 'minio'
- Redis connection timeouts during high traffic: Increase Redis maxmemory setting and configure appropriate eviction policy for session data
- PostgreSQL connection pool exhausted errors: Adjust Medusa database pool size in medusa-config.js based on expected concurrent users
- JWT token validation fails after container restart: Ensure JWT_SECRET and COOKIE_SECRET environment variables are persistent across deployments

