# Complete E-Commerce Stack

> Medusa e-commerce backend with PostgreSQL, Redis, MinIO storage, and admin dashboard

- Category: E-Commerce & Business
- Difficulty: intermediate
- Components: medusa, postgres, redis, minio, medusa-admin
- Tags: medusa, ecommerce, shop, postgres, redis, headless
- Source: https://docker.recipes/ecommerce/complete-ecommerce-stack

## Overview

Medusa is a modern, open-source headless commerce engine built on Node.js that provides a flexible foundation for e-commerce applications. Unlike traditional monolithic platforms like Magento or Shopify, Medusa separates the backend commerce logic from the frontend presentation layer, allowing developers to build custom storefronts using any technology stack while leveraging powerful commerce APIs for cart management, order processing, inventory tracking, and customer management. This architecture enables faster performance, better developer experience, and unlimited customization possibilities.

This complete e-commerce stack combines Medusa's headless backend with essential supporting services: PostgreSQL handles transactional data and complex product catalogs with full ACID compliance, Redis provides high-speed session storage and caching for cart persistence and real-time inventory updates, MinIO offers S3-compatible object storage for product images and digital assets, and the Medusa admin dashboard delivers an intuitive interface for managing products, orders, and customers. Together, these components create a production-ready commerce platform that can handle everything from startup marketplaces to enterprise retail operations.

This stack is ideal for developers building custom e-commerce experiences, agencies creating white-label solutions for clients, and businesses requiring flexible commerce functionality without platform lock-in. The headless architecture allows integration with modern frontend frameworks like Next.js, React, or Vue.js, while the robust backend handles complex commerce workflows including multi-region sales, subscription billing, and marketplace functionality. Unlike SaaS platforms, this self-hosted approach provides complete data ownership, unlimited customization, and no transaction fees.

## Features

- Headless commerce architecture with RESTful APIs for cart, checkout, product catalog, and order management
- PostgreSQL-powered product catalog with support for variants, collections, complex pricing rules, and inventory tracking
- Redis-based session management for persistent shopping carts and real-time inventory caching
- MinIO S3-compatible storage for product images, digital downloads, and media assets with built-in CDN capabilities
- Multi-region and multi-currency support with tax calculation and shipping rate management
- Extensible plugin system for payment processors, fulfillment providers, and third-party integrations
- Advanced discount engine supporting percentage, fixed amount, and buy-X-get-Y promotions
- Customer segmentation and analytics with order history and behavioral tracking

## Use cases

- Building custom storefronts with modern frameworks while maintaining robust commerce backend functionality
- Creating marketplace platforms with multiple vendors and complex product catalogs
- Developing subscription-based e-commerce sites with recurring billing and customer management
- Launching headless commerce solutions for mobile apps with API-driven shopping experiences
- Building white-label e-commerce platforms for agencies serving multiple retail clients
- Migrating from monolithic platforms like Magento to gain development flexibility and performance
- Creating omnichannel retail experiences connecting online stores with POS and inventory systems

## Prerequisites

- Docker and Docker Compose installed with minimum 4GB RAM available for all services
- Ports 9000, 7001, 9001, and 9002 available for Medusa API, admin dashboard, and MinIO interfaces
- Basic understanding of REST APIs and headless commerce concepts for integration development
- Environment variables configured for database credentials, JWT secrets, and MinIO access keys
- Node.js knowledge helpful for Medusa plugin development and custom business logic
- PostgreSQL familiarity recommended for database optimization and backup strategies

## docker-compose.yml

```yaml
services:
  medusa:
    image: medusajs/medusa:latest
    container_name: medusa
    restart: unless-stopped
    ports:
      - "${MEDUSA_PORT:-9000}:9000"
    environment:
      - DATABASE_URL=postgres://${DB_USER}:${DB_PASSWORD}@medusa-db:5432/medusa
      - REDIS_URL=redis://medusa-redis:6379
      - JWT_SECRET=${JWT_SECRET}
      - COOKIE_SECRET=${COOKIE_SECRET}
      - STORE_CORS=http://localhost:8000
      - ADMIN_CORS=http://localhost:7001
    depends_on:
      - medusa-db
      - medusa-redis

  medusa-admin:
    image: medusajs/admin:latest
    container_name: medusa-admin
    restart: unless-stopped
    ports:
      - "${ADMIN_PORT:-7001}:7001"
    environment:
      - MEDUSA_BACKEND_URL=http://medusa:9000
    depends_on:
      - medusa

  medusa-db:
    image: postgres:15-alpine
    container_name: medusa-db
    restart: unless-stopped
    environment:
      - POSTGRES_USER=${DB_USER}
      - POSTGRES_PASSWORD=${DB_PASSWORD}
      - POSTGRES_DB=medusa
    volumes:
      - medusa_db_data:/var/lib/postgresql/data

  medusa-redis:
    image: redis:7-alpine
    container_name: medusa-redis
    restart: unless-stopped
    volumes:
      - medusa_redis_data:/data

  minio:
    image: minio/minio:latest
    container_name: medusa-minio
    restart: unless-stopped
    ports:
      - "${MINIO_PORT:-9001}:9000"
      - "${MINIO_CONSOLE:-9002}:9001"
    environment:
      - MINIO_ROOT_USER=${MINIO_USER}
      - MINIO_ROOT_PASSWORD=${MINIO_PASSWORD}
    volumes:
      - minio_data:/data
    command: server /data --console-address ":9001"

volumes:
  medusa_db_data:
  medusa_redis_data:
  minio_data:
```

## .env

```bash
# E-Commerce Stack
MEDUSA_PORT=9000
ADMIN_PORT=7001
MINIO_PORT=9001
MINIO_CONSOLE=9002

# Database
DB_USER=medusa
DB_PASSWORD=medusa_password

# Secrets (generate with: openssl rand -hex 32)
JWT_SECRET=your-jwt-secret
COOKIE_SECRET=your-cookie-secret

# MinIO
MINIO_USER=minioadmin
MINIO_PASSWORD=minioadmin
```

## Usage notes

- Medusa API at http://localhost:9000
- Admin dashboard at http://localhost:7001
- MinIO for product images at http://localhost:9002
- Create admin: docker exec medusa medusa user -e admin@test.com -p password
- Seed data: docker exec medusa medusa seed
- Headless - connect any frontend (Next.js, Gatsby)

## Troubleshooting

- Medusa API returns 500 errors on startup: Check DATABASE_URL connection string and ensure PostgreSQL container is fully initialized before Medusa starts
- Admin dashboard shows 'Cannot connect to Medusa backend': Verify MEDUSA_BACKEND_URL environment variable points to http://medusa:9000 and containers are on same network
- Redis connection timeouts during checkout: Increase Redis memory limits and check REDIS_URL format matches redis://medusa-redis:6379 exactly
- MinIO image uploads fail with access denied: Create bucket through MinIO console and configure proper IAM policies for Medusa file plugin
- JWT authentication errors: Ensure JWT_SECRET and COOKIE_SECRET environment variables are set and consistent between container restarts
- Database migration failures: Run 'docker exec medusa medusa migrations run' manually and check PostgreSQL logs for constraint violations

