Medusa v2 Deployment
Before writing code
Fetch live docs:
- Web-search
site:docs.medusajs.com deployment production for production deployment guides
- Web-search
site:docs.medusajs.com medusa build for build process details
- Fetch
https://docs.medusajs.com/resources/medusa-cli for CLI command reference
- Web-search
site:docs.medusajs.com environment variables configuration for env var reference
- Web-search
site:docs.medusajs.com redis cache events for Redis caching and event bus setup
Build Process
Build Commands
| Command |
Purpose |
npx medusa build |
Compile server + admin dashboard for production |
npx medusa db:migrate |
Run pending database migrations |
npx medusa start |
Start the production server |
npx medusa worker |
Start the background worker process |
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:
| Mode |
Command |
Handles |
| Server |
npx medusa start |
HTTP requests, API routes, admin dashboard |
| Worker |
npx medusa worker |
Workflows, scheduled jobs, event subscribers |
| Combined |
Default start behavior |
Both server and worker (single process) |
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
| Variable |
Purpose |
Example |
DATABASE_URL |
PostgreSQL connection string |
postgres://user:pass@host:5432/medusa |
COOKIE_SECRET |
Session cookie signing |
Random 32+ character string |
JWT_SECRET |
JWT token signing |
Random 32+ character string |
NODE_ENV |
Runtime environment |
production |
Optional but Recommended
| Variable |
Purpose |
Default |
REDIS_URL |
Redis connection for cache/events/workers |
None (in-memory) |
STORE_CORS |
Store API CORS origins |
http://localhost:8000 |
ADMIN_CORS |
Admin API CORS origins |
http://localhost:9000 |
AUTH_CORS |
Auth route CORS origins |
Combination of store + admin |
PORT |
Server listen port |
9000 |
MEDUSA_ADMIN_ONBOARDING_TYPE |
Admin onboarding flow |
default |
MEDUSA_WORKER_MODE |
server, worker, or shared |
shared |
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:
| Role |
Purpose |
Required? |
| Event Bus |
Pub/sub for event-driven subscribers |
Recommended |
| Cache |
Module data caching layer |
Recommended |
| Worker Queue |
Job queue for background workflows |
Required for worker mode |
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
| Platform |
Type |
Notes |
| Railway |
PaaS |
One-click deploy, managed PostgreSQL and Redis |
| DigitalOcean App Platform |
PaaS |
Managed infrastructure, auto-scaling |
| AWS (EC2/ECS/Fargate) |
IaaS/CaaS |
Full control, use with RDS and ElastiCache |
| Google Cloud Run |
Serverless containers |
Auto-scaling, pay-per-use |
| Render |
PaaS |
Simple deploy, managed databases |
| Self-hosted (Docker) |
Container |
Full control, use Docker Compose or Kubernetes |
| Vercel |
Serverless |
Admin/storefront hosting only (not the Medusa server) |
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
Infrastructure
Post-Deploy
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.
1---2name: medusa-deploy-23description: Deploy Medusa v2 to production — build process, server vs worker mode, environment variables, hosting options, Redis caching, database configuration, and production checklist. Use when deploying Medusa applications.4allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch5metadata:6 source: https://skillmd.com/skills/orcaqubits/medusa-deploy-27---89# Medusa v2 Deployment1011## Before writing code1213**Fetch live docs**:141. Web-search `site:docs.medusajs.com deployment production` for production deployment guides152. Web-search `site:docs.medusajs.com medusa build` for build process details163. Fetch `https://docs.medusajs.com/resources/medusa-cli` for CLI command reference174. Web-search `site:docs.medusajs.com environment variables configuration` for env var reference185. Web-search `site:docs.medusajs.com redis cache events` for Redis caching and event bus setup1920## Build Process2122### Build Commands2324| Command | Purpose |25|---------|---------|26| `npx medusa build` | Compile server + admin dashboard for production |27| `npx medusa db:migrate` | Run pending database migrations |28| `npx medusa start` | Start the production server |29| `npx medusa worker` | Start the background worker process |3031The build step compiles TypeScript, bundles admin extensions (Vite), and prepares the `.medusa/` output directory.3233### Build Output Structure3435```36.medusa/37├── server/ — Compiled server code38│ ├── src/ — Custom modules, routes, workflows39│ └── medusa-config.js40└── admin/ — Bundled admin dashboard (static)41```4243## Server vs Worker Mode4445Medusa v2 supports running the server and background workers as separate processes:4647| Mode | Command | Handles |48|------|---------|---------|49| **Server** | `npx medusa start` | HTTP requests, API routes, admin dashboard |50| **Worker** | `npx medusa worker` | Workflows, scheduled jobs, event subscribers |51| **Combined** | Default `start` behavior | Both server and worker (single process) |5253### When to Separate5455- **Development** — combined mode is fine56- **Production** — separate for reliability and independent scaling57- **High traffic** — scale server instances independently from workers58- Worker mode requires Redis for job queue communication between processes5960## Environment Variables6162### Required Variables6364| Variable | Purpose | Example |65|----------|---------|---------|66| `DATABASE_URL` | PostgreSQL connection string | `postgres://user:pass@host:5432/medusa` |67| `COOKIE_SECRET` | Session cookie signing | Random 32+ character string |68| `JWT_SECRET` | JWT token signing | Random 32+ character string |69| `NODE_ENV` | Runtime environment | `production` |7071### Optional but Recommended7273| Variable | Purpose | Default |74|----------|---------|---------|75| `REDIS_URL` | Redis connection for cache/events/workers | None (in-memory) |76| `STORE_CORS` | Store API CORS origins | `http://localhost:8000` |77| `ADMIN_CORS` | Admin API CORS origins | `http://localhost:9000` |78| `AUTH_CORS` | Auth route CORS origins | Combination of store + admin |79| `PORT` | Server listen port | `9000` |80| `MEDUSA_ADMIN_ONBOARDING_TYPE` | Admin onboarding flow | `default` |81| `MEDUSA_WORKER_MODE` | `server`, `worker`, or `shared` | `shared` |8283## Database Configuration8485### PostgreSQL Requirements8687- PostgreSQL required (see official docs for version compatibility)88- Enable SSL in production: append `?sslmode=require` to `DATABASE_URL`89- Connection pooling recommended for high-traffic deployments9091### Migration Workflow9293```bash94# Generate migration after DML model changes95npx medusa db:generate <module_name>96# Apply migrations97npx medusa db:migrate98```99100- Always run migrations before starting the new server version101- Back up the database before running migrations in production102- Test migrations against a staging database first103104## Redis Configuration105106Redis serves three roles in production Medusa:107108| Role | Purpose | Required? |109|------|---------|-----------|110| **Event Bus** | Pub/sub for event-driven subscribers | Recommended |111| **Cache** | Module data caching layer | Recommended |112| **Worker Queue** | Job queue for background workflows | Required for worker mode |113114Configure in `medusa-config.ts` by registering the Redis modules:115116```ts117// Fetch live docs for Redis module registration118// in medusa-config.ts modules array119```120121- Use separate Redis databases (db index) for cache vs events vs queues122- Set appropriate `maxmemory` and eviction policies for cache123- Monitor Redis memory usage and connection count in production124125## Hosting Options126127| Platform | Type | Notes |128|----------|------|-------|129| **Railway** | PaaS | One-click deploy, managed PostgreSQL and Redis |130| **DigitalOcean App Platform** | PaaS | Managed infrastructure, auto-scaling |131| **AWS (EC2/ECS/Fargate)** | IaaS/CaaS | Full control, use with RDS and ElastiCache |132| **Google Cloud Run** | Serverless containers | Auto-scaling, pay-per-use |133| **Render** | PaaS | Simple deploy, managed databases |134| **Self-hosted (Docker)** | Container | Full control, use Docker Compose or Kubernetes |135| **Vercel** | Serverless | Admin/storefront hosting only (not the Medusa server) |136137### Docker Deployment138139```dockerfile140# Fetch live docs for official Medusa Dockerfile141# and docker-compose.yml patterns142```143144A typical Docker Compose setup includes three services: Medusa server, PostgreSQL, and Redis.145146## Production Checklist147148### Pre-Deploy149150- [ ] Set `NODE_ENV=production`151- [ ] Configure unique `COOKIE_SECRET` and `JWT_SECRET`152- [ ] Set `DATABASE_URL` with SSL mode enabled153- [ ] Configure `REDIS_URL` for events, cache, and worker queue154- [ ] Set CORS variables (`STORE_CORS`, `ADMIN_CORS`, `AUTH_CORS`)155- [ ] Run `npx medusa build` successfully156- [ ] Run `npx medusa db:migrate` against production database157158### Infrastructure159160- [ ] PostgreSQL with automated backups and point-in-time recovery161- [ ] Redis with persistence enabled (RDB or AOF)162- [ ] HTTPS termination (TLS certificate) via reverse proxy or load balancer163- [ ] Health check endpoint configured for load balancer164- [ ] Log aggregation (stdout/stderr to centralized logging)165166### Post-Deploy167168- [ ] Verify admin dashboard loads and login works169- [ ] Verify store API responds with publishable key170- [ ] Confirm background workers are processing jobs171- [ ] Test payment provider webhooks reach the server172- [ ] Monitor error rates and response times173174## Scaling Strategies175176### Horizontal Scaling177178- Run multiple server instances behind a load balancer179- Use Redis-backed sessions for sticky-session-free scaling180- Run multiple worker instances for parallel job processing181182### Vertical Scaling183184- Increase PostgreSQL connection pool size for heavier workloads185- Allocate more memory to Redis for larger cache datasets186- Use `--max-old-space-size` for Node.js memory limits187188## Best Practices189190- **Separate server and worker** — run as independent processes in production; scale each based on demand; use Redis as the communication backbone191- **Environment variable hygiene** — never commit secrets to source control; use platform-native secret management (AWS Secrets Manager, Railway variables, etc.); rotate secrets periodically192- **Database management** — always test migrations on staging first; automate backups; use connection pooling (PgBouncer) for high concurrency193- **Monitoring** — track API response times, worker queue depth, database connection count, and Redis memory; set alerts for anomalies194195Fetch the Medusa deployment documentation for exact build flags, Docker configuration, and platform-specific deployment guides before deploying.