Medusa Deploy

Medusa v2 Deployment

Before writing code

Fetch live docs:

1. Web-search site:docs.medusajs.com deployment production for production deployment guides
2. Web-search site:docs.medusajs.com medusa build for build process details
3. Fetch https://docs.medusajs.com/learn/fundamentals/cli for CLI command reference
4. Web-search site:docs.medusajs.com environment variables configuration for env var reference
5. Web-search site:docs.medusajs.com redis cache events for Redis caching and event bus setup

Build Process

Build Commands

The build step compiles TypeScript, bundles admin extensions (Vite), and prepares the .medusa/ output directory.

Build Output Structure

.medusa/
├── server/           — Compiled server code
│   ├── src/          — Custom modules, routes, workflows
│   └── medusa-config.js
└── admin/            — Bundled admin dashboard (static)

Server vs Worker Mode

Medusa v2 supports running the server and background workers as separate processes:

When to Separate

• Development — combined mode is fine
• Production — separate for reliability and independent scaling
• High traffic — scale server instances independently from workers
• Worker mode requires Redis for job queue communication between processes

Environment Variables

Required Variables

Optional but Recommended

Database Configuration

PostgreSQL Requirements

• PostgreSQL required (see official docs for version compatibility)
• Enable SSL in production: append ?sslmode=require to DATABASE_URL
• Connection pooling recommended for high-traffic deployments

Migration Workflow

# Generate migration after DML model changes
npx medusa db:generate <module_name>
# Apply migrations
npx medusa db:migrate

• Always run migrations before starting the new server version
• Back up the database before running migrations in production
• Test migrations against a staging database first

Redis Configuration

Redis serves three roles in production Medusa:

Configure in medusa-config.ts by registering the Redis modules:

// Fetch live docs for Redis module registration
// in medusa-config.ts modules array

• Use separate Redis databases (db index) for cache vs events vs queues
• Set appropriate maxmemory and eviction policies for cache
• Monitor Redis memory usage and connection count in production

Hosting Options

Docker Deployment

# Fetch live docs for official Medusa Dockerfile
# and docker-compose.yml patterns

A typical Docker Compose setup includes three services: Medusa server, PostgreSQL, and Redis.

Production Checklist

Pre-Deploy

• Set NODE_ENV=production
• Configure unique COOKIE_SECRET and JWT_SECRET
• Set DATABASE_URL with SSL mode enabled
• Configure REDIS_URL for events, cache, and worker queue
• Set CORS variables (STORE_CORS, ADMIN_CORS, AUTH_CORS)
• Run npx medusa build successfully
• Run npx medusa db:migrate against production database

Infrastructure

• PostgreSQL with automated backups and point-in-time recovery
• Redis with persistence enabled (RDB or AOF)
• HTTPS termination (TLS certificate) via reverse proxy or load balancer
• Health check endpoint configured for load balancer
• Log aggregation (stdout/stderr to centralized logging)

Post-Deploy

• Verify admin dashboard loads and login works
• Verify store API responds with publishable key
• Confirm background workers are processing jobs
• Test payment provider webhooks reach the server
• Monitor error rates and response times

Scaling Strategies

Horizontal Scaling

• Run multiple server instances behind a load balancer
• Use Redis-backed sessions for sticky-session-free scaling
• Run multiple worker instances for parallel job processing

Vertical Scaling

• Increase PostgreSQL connection pool size for heavier workloads
• Allocate more memory to Redis for larger cache datasets
• Use --max-old-space-size for Node.js memory limits

Best Practices

• Separate server and worker — run as independent processes in production; scale each based on demand; use Redis as the communication backbone
• Environment variable hygiene — never commit secrets to source control; use platform-native secret management (AWS Secrets Manager, Railway variables, etc.); rotate secrets periodically
• Database management — always test migrations on staging first; automate backups; use connection pooling (PgBouncer) for high concurrency
• Monitoring — track API response times, worker queue depth, database connection count, and Redis memory; set alerts for anomalies

Fetch the Medusa deployment documentation for exact build flags, Docker configuration, and platform-specific deployment guides before deploying.