docker.recipes

Medusa Commerce

intermediate

Open-source Shopify alternative.

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.

Key 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

Common Use Cases

  • 1Building custom storefronts with React, Next.js, or Gatsby for unique brand experiences
  • 2Creating B2B marketplaces with complex pricing structures and buyer approval workflows
  • 3Developing mobile commerce apps with native iOS/Android frontends consuming Medusa APIs
  • 4Launching subscription box services with recurring billing and inventory automation
  • 5Building omnichannel retail solutions connecting online stores with POS systems
  • 6Creating marketplace platforms where multiple vendors can manage their own products
  • 7Developing 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

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

docker-compose.yml
1services: 
2  medusa: 
3    image: medusajs/medusa:latest
4    container_name: medusa
5    restart: unless-stopped
6    environment: 
7      DATABASE_URL: postgres://${DB_USER}:${DB_PASSWORD}@postgres:5432/${DB_NAME}
8      REDIS_URL: redis://redis:6379
9      JWT_SECRET: ${JWT_SECRET}
10      COOKIE_SECRET: ${COOKIE_SECRET}
11    ports: 
12      - "9000:9000"
13    depends_on: 
14      - postgres
15      - redis
16    networks: 
17      - medusa
18
19  postgres: 
20    image: postgres:16-alpine
21    container_name: medusa-postgres
22    environment: 
23      POSTGRES_DB: ${DB_NAME}
24      POSTGRES_USER: ${DB_USER}
25      POSTGRES_PASSWORD: ${DB_PASSWORD}
26    volumes: 
27      - postgres_data:/var/lib/postgresql/data
28    networks: 
29      - medusa
30
31  redis: 
32    image: redis:alpine
33    container_name: medusa-redis
34    networks: 
35      - medusa
36
37volumes: 
38  postgres_data: 
39
40networks: 
41  medusa: 
42    driver: bridge

.env Template

.env
1DB_NAME=medusa
2DB_USER=medusa
3DB_PASSWORD=changeme
4JWT_SECRET=your-jwt-secret
5COOKIE_SECRET=your-cookie-secret

Usage Notes

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

Individual Services(3 services)

Copy individual services to mix and match with your existing compose files.

medusa
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
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
redis:
  image: redis:alpine
  container_name: medusa-redis
  networks:
    - medusa

Quick Start

terminal
1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  medusa:
5    image: medusajs/medusa:latest
6    container_name: medusa
7    restart: unless-stopped
8    environment:
9      DATABASE_URL: postgres://${DB_USER}:${DB_PASSWORD}@postgres:5432/${DB_NAME}
10      REDIS_URL: redis://redis:6379
11      JWT_SECRET: ${JWT_SECRET}
12      COOKIE_SECRET: ${COOKIE_SECRET}
13    ports:
14      - "9000:9000"
15    depends_on:
16      - postgres
17      - redis
18    networks:
19      - medusa
20
21  postgres:
22    image: postgres:16-alpine
23    container_name: medusa-postgres
24    environment:
25      POSTGRES_DB: ${DB_NAME}
26      POSTGRES_USER: ${DB_USER}
27      POSTGRES_PASSWORD: ${DB_PASSWORD}
28    volumes:
29      - postgres_data:/var/lib/postgresql/data
30    networks:
31      - medusa
32
33  redis:
34    image: redis:alpine
35    container_name: medusa-redis
36    networks:
37      - medusa
38
39volumes:
40  postgres_data:
41
42networks:
43  medusa:
44    driver: bridge
45EOF
46
47# 2. Create the .env file
48cat > .env << 'EOF'
49DB_NAME=medusa
50DB_USER=medusa
51DB_PASSWORD=changeme
52JWT_SECRET=your-jwt-secret
53COOKIE_SECRET=your-cookie-secret
54EOF
55
56# 3. Start the services
57docker compose up -d
58
59# 4. View logs
60docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal
1curl -fsSL https://docker.recipes/api/recipes/medusa/run | bash

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

Community Notes

Loading...
Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

medusapostgresredis

Tags

#medusa#ecommerce#headless#api

Category

E-Commerce & Business

Related Recipes

Ad Space