# Medusa + PostgreSQL + Redis + MinIO

> Headless commerce platform with full backend services.

- Category: E-Commerce & Business
- Difficulty: advanced
- Components: medusa-backend, postgresql, redis, minio, medusa-admin
- Tags: medusa, headless, ecommerce, api, storefront
- Source: https://docker.recipes/ecommerce/medusa-complete

## Overview

Medusa is a modern headless commerce platform built with Node.js that provides a flexible, API-first approach to e-commerce. Unlike monolithic platforms like Shopify or WooCommerce, Medusa separates the backend commerce logic from the frontend presentation layer, enabling developers to build custom storefronts using any technology stack. The platform handles core commerce operations including product catalog management, order processing, customer management, and payment integration through a comprehensive REST API. This stack combines Medusa's commerce engine with PostgreSQL for transactional data storage, Redis for session management and caching, and MinIO for S3-compatible object storage of product images and digital assets. The architecture provides enterprise-grade data persistence through PostgreSQL's ACID compliance, sub-millisecond response times via Redis caching, and scalable media storage through MinIO's high-performance object store. This configuration creates a complete headless commerce backend that can power multiple storefronts, mobile applications, or integrate with existing business systems. The combination is ideal for businesses requiring custom e-commerce experiences, multi-channel selling, or complex B2B commerce workflows. Companies choose this stack when they need the flexibility of headless architecture without vendor lock-in, full control over their commerce data, and the ability to scale each component independently based on traffic patterns.

## Features

- Headless commerce API supporting product catalogs, orders, customers, and multi-region selling
- PostgreSQL JSONB storage for flexible product attributes and complex catalog structures
- Redis-powered session management and cart persistence for high-performance checkout flows
- MinIO S3-compatible storage for product images, digital downloads, and media assets
- Built-in admin dashboard for managing products, orders, and customer data
- Multi-currency and multi-region support with tax and shipping calculations
- Pluggable payment processor integration supporting Stripe, PayPal, and custom gateways
- Event-driven architecture with Redis pub/sub for real-time inventory and order updates

## Use cases

- Headless e-commerce for React, Vue, or mobile app storefronts
- Multi-brand retailers managing separate storefronts from unified inventory
- B2B marketplaces requiring custom pricing and approval workflows
- Digital product stores selling downloads, subscriptions, or SaaS offerings
- International commerce with multi-currency and region-specific catalogs
- Marketplace platforms connecting multiple vendors with centralized order management
- Custom commerce integrations for existing business applications or ERPs

## Prerequisites

- Minimum 4GB RAM for full stack operation (1GB PostgreSQL, 512MB Redis, 2GB MinIO, 512MB Medusa)
- Docker Engine 20.10+ and Docker Compose 2.0+ for container orchestration
- Ports 7001, 9000, and 9001 available for admin interface, API, and MinIO console
- Basic understanding of REST APIs and headless architecture concepts
- Node.js knowledge for customizing Medusa plugins and business logic
- PostgreSQL familiarity for database maintenance and backup procedures

## docker-compose.yml

```yaml
services:
  medusa:
    image: medusajs/medusa:latest
    environment:
      - DATABASE_URL=postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/medusa
      - REDIS_URL=redis://redis:6379
      - NODE_ENV=production
      - JWT_SECRET=${JWT_SECRET}
      - COOKIE_SECRET=${COOKIE_SECRET}
      - STORE_CORS=http://localhost:8000
      - ADMIN_CORS=http://localhost:7001
      - MINIO_ENDPOINT=minio
      - MINIO_PORT=9000
      - MINIO_ACCESS_KEY=${MINIO_ACCESS_KEY}
      - MINIO_SECRET_KEY=${MINIO_SECRET_KEY}
      - MINIO_BUCKET=medusa
    ports:
      - "9000:9000"
    depends_on:
      - postgres
      - redis
      - minio
    networks:
      - medusa-network
    restart: unless-stopped

  postgres:
    image: postgres:15
    environment:
      - POSTGRES_USER=${POSTGRES_USER}
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
      - POSTGRES_DB=medusa
    volumes:
      - postgres-data:/var/lib/postgresql/data
    networks:
      - medusa-network
    restart: unless-stopped

  redis:
    image: redis:alpine
    volumes:
      - redis-data:/data
    networks:
      - medusa-network
    restart: unless-stopped

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

  admin:
    image: medusajs/admin:latest
    environment:
      - MEDUSA_BACKEND_URL=http://localhost:9000
    ports:
      - "7001:7001"
    depends_on:
      - medusa
    networks:
      - medusa-network
    restart: unless-stopped

volumes:
  postgres-data:
  redis-data:
  minio-data:

networks:
  medusa-network:
    driver: bridge
```

## .env

```bash
# Medusa
POSTGRES_USER=medusa
POSTGRES_PASSWORD=secure_postgres_password
JWT_SECRET=your-super-secret-jwt-key
COOKIE_SECRET=your-super-secret-cookie-key

# MinIO
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=secure_minio_password
```

## Usage notes

- API at http://localhost:9000
- Admin at http://localhost:7001
- MinIO console at http://localhost:9001
- Seed store: medusa seed -f data/seed.json
- Create admin: medusa user -e admin@example.com -p password

## Troubleshooting

- Medusa fails to connect to PostgreSQL: Verify POSTGRES_USER and POSTGRES_PASSWORD match in both services, ensure postgres container starts before medusa
- Redis connection timeout errors: Check Redis container health with docker logs redis, verify redis:6379 hostname resolves within medusa-network
- MinIO bucket access denied: Confirm MINIO_ACCESS_KEY and MINIO_SECRET_KEY are set correctly, create medusa bucket manually via MinIO console at localhost:9001
- Admin dashboard shows 'Backend unreachable': Ensure medusa container is running and MEDUSA_BACKEND_URL points to http://localhost:9000, check CORS settings
- Database migration failures on startup: Run docker exec -it medusa-container medusa migrations run, check PostgreSQL logs for permission or disk space issues
- High memory usage by PostgreSQL: Tune shared_buffers and work_mem in PostgreSQL config, consider adding postgresql.conf volume mount for custom settings

