Skip to main content

​
Environment Variables

This page lists all environment variables that Medusa recognizes and uses for configuration.
Environment variables are loaded from .env files in development. In production, set them in your hosting environment.

​
Required Variables

These variables are required for Medusa to run:

​
DATABASE_URL

PostgreSQL connection string. 
DATABASE_URL=postgres://user:password@host:port/dbname
Format: postgres://[user][:password]@[host][:port]/[dbname] Default: postgres://localhost/medusa-starter-default

​
JWT_SECRET

Secret key for signing JWT tokens. 
JWT_SECRET=your-super-secret-jwt-key
Default: supersecret (development only)
In production, this must be set to a strong, random value. Use at least 32 random characters.
Generate a secure secret: 
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"
Secret key for signing session cookies. 
COOKIE_SECRET=your-super-secret-cookie-key
Default: supersecret (development only)
In production, this must be set to a strong, random value different from JWT_SECRET.

​
HTTP Configuration

​
PORT

Port number for the HTTP server. 
PORT=9000
Default: 9000

​
NODE_ENV

Application environment. 
NODE_ENV=production
Values: development, production, prod Default: development

​
STORE_CORS

Allowed CORS origins for store routes. 
STORE_CORS=https://storefront.example.com,https://shop.example.com
Default: http://localhost:8000 Format: Comma-separated list of URLs

​
ADMIN_CORS

Allowed CORS origins for admin routes. 
ADMIN_CORS=https://admin.example.com,https://dashboard.example.com
Default: http://localhost:7000,http://localhost:7001,http://localhost:5173 Format: Comma-separated list of URLs

​
AUTH_CORS

Allowed CORS origins for auth routes. 
AUTH_CORS=https://admin.example.com
Default: Same as ADMIN_CORS Format: Comma-separated list of URLs

​
JWT Configuration

​
JWT_PUBLIC_KEY

Public key for asymmetric JWT verification. 
JWT_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\nMIIBIjAN...\n-----END PUBLIC KEY-----"
Default: Not set (uses symmetric signing with JWT_SECRET)
When using asymmetric JWT, configure jwtOptions.algorithm and jwtVerifyOptions.algorithms in medusa-config.ts.

​
Redis Configuration

​
REDIS_URL

Redis connection URL. 
REDIS_URL=redis://localhost:6379
Format: redis://[user][:password]@[host][:port] Default: Not set (uses in-memory implementations)
For production, Redis is strongly recommended for the event bus, cache, and workflow engine.

​
CACHE_REDIS_URL

Separate Redis instance for caching. 
CACHE_REDIS_URL=redis://localhost:6380
Default: Falls back to REDIS_URL

​
Worker Mode

​
MEDUSA_WORKER_MODE

Determines how the instance handles HTTP requests and background jobs. 
MEDUSA_WORKER_MODE=server
Values:
  • shared: Handle both HTTP and jobs (default)
  • server: Only handle HTTP requests
  • worker: Only handle background jobs
Default: shared Production setup: 
# Server instance
MEDUSA_WORKER_MODE=server npm run start

# Worker instance
MEDUSA_WORKER_MODE=worker npm run start

​
Admin Configuration

​
MEDUSA_BACKEND_URL

Backend URL for the admin dashboard. 
MEDUSA_BACKEND_URL=https://api.example.com
Default: / (browser origin)

​
DISABLE_ADMIN

Disable the admin dashboard. 
DISABLE_ADMIN=true
Default: false

​
STOREFRONT_URL

Storefront URL for generating customer-facing links from admin. 
STOREFRONT_URL=https://shop.example.com
Default: Not set

​
Logging

​
LOG_LEVEL

Logging level for the application. 
LOG_LEVEL=info
Values: error, warn, info, debug Default: info Production recommendation: error or warn

​
Medusa Cloud

These variables are used when deploying to Medusa Cloud:

​
EXECUTION_CONTEXT

EXECUTION_CONTEXT=medusa-cloud
Enables Medusa Cloud-specific configurations.

​
MEDUSA_CLOUD_ENVIRONMENT_HANDLE

MEDUSA_CLOUD_ENVIRONMENT_HANDLE=prod-env-abc123

​
MEDUSA_CLOUD_SANDBOX_HANDLE

MEDUSA_CLOUD_SANDBOX_HANDLE=sandbox-abc123

​
MEDUSA_CLOUD_API_KEY

MEDUSA_CLOUD_API_KEY=mck_abc123...

​
MEDUSA_CLOUD_WEBHOOK_SECRET

MEDUSA_CLOUD_WEBHOOK_SECRET=whsec_abc123...

​
MEDUSA_CLOUD_EMAILS_ENDPOINT

MEDUSA_CLOUD_EMAILS_ENDPOINT=https://emails.medusacloud.com

​
MEDUSA_CLOUD_PAYMENTS_ENDPOINT

MEDUSA_CLOUD_PAYMENTS_ENDPOINT=https://payments.medusacloud.com

​
MEDUSA_CLOUD_OAUTH_AUTHORIZE_ENDPOINT

MEDUSA_CLOUD_OAUTH_AUTHORIZE_ENDPOINT=https://oauth.medusacloud.com/authorize

​
MEDUSA_CLOUD_OAUTH_TOKEN_ENDPOINT

MEDUSA_CLOUD_OAUTH_TOKEN_ENDPOINT=https://oauth.medusacloud.com/token

​
MEDUSA_CLOUD_OAUTH_CALLBACK_URL

MEDUSA_CLOUD_OAUTH_CALLBACK_URL=https://admin.example.com/app/login?auth_provider=cloud

​
MEDUSA_CLOUD_OAUTH_DISABLED

MEDUSA_CLOUD_OAUTH_DISABLED=true

​
Session Configuration

​
SESSION_STORE

Session storage backend. 
SESSION_STORE=dynamodb
Values: dynamodb (when using DynamoDB for sessions) Default: In-memory or Redis (based on REDIS_URL)

​
DynamoDB Session Variables

When using DynamoDB for session storage: 
DYNAMO_DB_SESSIONS_TABLE=medusa-sessions
DYNAMO_DB_SESSIONS_PREFIX=sess:
DYNAMO_DB_SESSIONS_HASH_KEY=id
DYNAMO_DB_SESSIONS_READ_UNITS=5
DYNAMO_DB_SESSIONS_WRITE_UNITS=5
DYNAMO_DB_SESSIONS_CREATE_TABLE=true

​
File Storage (S3)

When using S3 for file storage:

​
S3_BUCKET

S3_BUCKET=my-medusa-files

​
S3_REGION

S3_REGION=us-east-1

​
S3_ACCESS_KEY_ID

S3_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE

​
S3_SECRET_ACCESS_KEY

S3_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

​
S3_ENDPOINT

S3_ENDPOINT=https://s3.us-east-1.amazonaws.com

​
S3_FILE_URL

S3_FILE_URL=https://my-bucket.s3.amazonaws.com

​
S3_PREFIX

S3_PREFIX=uploads/

​
Payment Providers

​
Stripe

STRIPE_API_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

​
PayPal

PAYPAL_CLIENT_ID=...
PAYPAL_CLIENT_SECRET=...
PAYPAL_MODE=sandbox  # or 'live'

​
Notification Providers

​
SendGrid

SENDGRID_API_KEY=SG....
SENDGRID_FROM=[email protected]

​
Mailchimp

MAILCHIMP_API_KEY=...
MAILCHIMP_LIST_ID=...

​
Feature Flags

​
MEDUSA_FF_TRANSLATION

Enable translation module. 
MEDUSA_FF_TRANSLATION=true
Default: false

​
MEDUSA_FF_RBAC

Enable role-based access control. 
MEDUSA_FF_RBAC=true
Default: false

​
ENABLE_INDEX_MODULE

Enable the index/search module. 
ENABLE_INDEX_MODULE=true
Default: false

​
Database Internal Variables

These are used internally for database connection handling:

​
__MEDUSA_DB_CONNECTION_MAX_RETRIES

Maximum retries for database connection. 
__MEDUSA_DB_CONNECTION_MAX_RETRIES=5
Default: 5

​
__MEDUSA_DB_CONNECTION_RETRY_DELAY

Delay between connection retries in milliseconds. 
__MEDUSA_DB_CONNECTION_RETRY_DELAY=1000
Default: 1000

​
DB_MIGRATION_CONCURRENCY

Number of concurrent migrations to run. 
DB_MIGRATION_CONCURRENCY=5
Default: Unlimited (or 1 if using pgstream)

​
Module-Specific Database URLs

You can configure separate databases for specific modules:

​
MEDUSA_DATABASE_URL

Shared database for all modules. 
MEDUSA_DATABASE_URL=postgres://localhost/medusa_shared

​
Module Database URLs

# Product module
PRODUCT_DATABASE_URL=postgres://localhost/medusa_products

# Order module
ORDER_DATABASE_URL=postgres://localhost/medusa_orders

# Customer module
CUSTOMER_DATABASE_URL=postgres://localhost/medusa_customers
Format: {MODULE_NAME}_DATABASE_URL

​
Example .env File

Here’s a complete example for production:
.env
# Environment
NODE_ENV=production
PORT=9000
LOG_LEVEL=warn

# Database
DATABASE_URL=postgres://medusa:[email protected]:5432/medusa_prod?sslmode=require

# Redis
REDIS_URL=redis://:[email protected]:6379

# Secrets
JWT_SECRET=<generated-secret-key>
COOKIE_SECRET=<generated-secret-key>

# CORS
STORE_CORS=https://shop.example.com
ADMIN_CORS=https://admin.example.com
AUTH_CORS=https://admin.example.com

# Admin
MEDUSA_BACKEND_URL=https://api.example.com
STOREFRONT_URL=https://shop.example.com

# File Storage (S3)
S3_BUCKET=medusa-prod-files
S3_REGION=us-east-1
S3_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
S3_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

# Payment (Stripe)
STRIPE_API_KEY=sk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...

# Notifications (SendGrid)
SENDGRID_API_KEY=SG....
SENDGRID_FROM=[email protected]

# Worker Mode
MEDUSA_WORKER_MODE=server

​
Security Best Practices

Never commit .env files to version control. Add .env to your .gitignore file.
  1. Use strong secrets: Generate random values for JWT_SECRET and COOKIE_SECRET
  2. Different secrets per environment: Don’t reuse secrets between development, staging, and production
  3. Rotate secrets regularly: Update secrets periodically and after security incidents
  4. Use secret management: Consider using AWS Secrets Manager, HashiCorp Vault, or similar
  5. Limit access: Only grant access to environment variables to those who need it
  6. Audit changes: Track who changes environment variables and when

​
Loading Environment Variables

​
Development

Medusa automatically loads variables from .env files: 
# .env file in project root
DATABASE_URL=postgres://localhost/medusa_dev
JWT_SECRET=dev-secret

​
Production

Set environment variables in your hosting platform:
  • Docker: Use -e flag or docker-compose.yml
  • Kubernetes: ConfigMaps and Secrets
  • Heroku: Config Vars in dashboard or CLI
  • AWS: Systems Manager Parameter Store or Secrets Manager
  • Vercel/Netlify: Environment variables in dashboard

​
Multiple Environment Files

You can use different .env files: 
# .env.development
DATABASE_URL=postgres://localhost/medusa_dev

# .env.staging  
DATABASE_URL=postgres://staging-db/medusa_staging

# .env.production
DATABASE_URL=postgres://prod-db/medusa_prod
Load specific file: 
node -r dotenv/config --env-file=.env.staging server.js

Build docs developers (and LLMs) love

Get started for freeTalk to us