Skip to main content

​
Deployment Overview

This guide covers the essential requirements and considerations for deploying a Medusa application to production.

​
Requirements

​
Node.js Version

Medusa requires Node.js 20 or higher. Make sure your production environment meets this requirement: 
node --version
# Should output v20.0.0 or higher

​
PostgreSQL Database

Medusa uses PostgreSQL as its primary database. Your production environment needs:
  • PostgreSQL 12 or higher (PostgreSQL 14+ recommended)
  • Database user with create privileges
  • Network access from your Medusa application to the database
For production environments, Redis is recommended for:
  • Event Bus: Reliable event processing
  • Cache: Improved performance
  • Workflow Engine: Distributed workflow execution
  • Locking: Distributed locks for concurrent operations
While Redis is optional for development, it is strongly recommended for production deployments to ensure reliability and performance.

​
Deployment Options

​
Self-Hosted

Deploy Medusa on your own infrastructure:
  • Virtual Private Server (VPS): DigitalOcean, Linode, Vultr
  • Cloud Providers: AWS EC2, Google Cloud Compute Engine, Azure VMs
  • Containerized: Docker, Kubernetes
  • Platform as a Service: Heroku, Railway, Render

​
Medusa Cloud

Medusa Cloud provides managed hosting with:
  • Automatic scaling
  • Built-in Redis and PostgreSQL
  • Integrated monitoring and logging
  • Simplified deployment workflow
Set EXECUTION_CONTEXT=medusa-cloud to enable cloud-specific configurations.

​
Production Considerations

​
Environment Variables

Always use environment variables for sensitive configuration like database credentials, API keys, and secrets. Never commit these to version control.
Essential environment variables for production: 
# Required
DATABASE_URL=postgres://user:password@host:port/dbname
JWT_SECRET=your-secure-random-secret
COOKIE_SECRET=your-secure-random-secret

# Recommended
NODE_ENV=production
REDIS_URL=redis://user:password@host:port
STORE_CORS=https://your-storefront.com
ADMIN_CORS=https://your-admin.com
See the Environment Variables page for a complete list.

​
Database Migrations

Before starting your application in production, always run migrations: 
npx medusa db:migrate
This command:
  1. Creates the database if it doesn’t exist
  2. Runs all pending module migrations
  3. Synchronizes link definitions
  4. Executes migration scripts
Never skip migrations in production. Running the application without migrations will cause errors.

​
Build Process

For production deployments, build your application: 
# Build the Medusa application
npm run build

# Start the production server
npm run start
The build process:
  • Compiles TypeScript to JavaScript
  • Bundles the admin dashboard (if enabled)
  • Optimizes dependencies

​
Worker Mode

Medusa supports different worker modes for scaling:
  • shared (default): Single process handles both HTTP and background jobs
  • server: Process only handles HTTP requests
  • worker: Process only handles background jobs
Set via environment variable: 
MEDUSA_WORKER_MODE=server  # or 'worker' or 'shared'
For production, run separate server and worker processes: 
# Server process
MEDUSA_WORKER_MODE=server npm run start

# Worker process (separate instance)
MEDUSA_WORKER_MODE=worker npm run start

​
Health Checks

Implement health checks for your deployment: 
# Check if the server is running
curl http://localhost:9000/health

​
Monitoring and Logging

Configure logging level for production: 
LOG_LEVEL=info  # Options: error, warn, info, debug
Use error or warn in production to reduce log volume. Use debug only for troubleshooting.

​
Security Best Practices

​
Secrets Management

  1. Generate strong secrets: Use at least 32 random characters for JWT_SECRET and COOKIE_SECRET
  2. Rotate secrets regularly: Update secrets periodically and after any security incidents
  3. Use environment-specific secrets: Different secrets for development, staging, and production
# Generate a secure random secret
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

​
CORS Configuration

Properly configure CORS for your domains: 
STORE_CORS=https://shop.example.com
ADMIN_CORS=https://admin.example.com
AUTH_CORS=https://admin.example.com

​
HTTPS

Always use HTTPS in production:
  • Use a reverse proxy (nginx, Caddy, Traefik)
  • Configure SSL/TLS certificates (Let’s Encrypt recommended)
  • Enable HTTP to HTTPS redirects

​
Next Steps

Configuration

Learn how to configure Medusa via medusa-config.js

Database Setup

PostgreSQL configuration and migrations

Environment Variables

Complete reference of all environment variables

Build docs developers (and LLMs) love

Get started for freeTalk to us