Environment Variables

Complete reference of environment variables used by Medusa

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'))"

COOKIE_SECRET

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=[e-mail]

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:[e-mail]:5432/medusa_prod?sslmode=require

# Redis
REDIS_URL=redis://:[e-mail]: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=[e-mail]

# 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