> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/medusajs/medusa/llms.txt
> Use this file to discover all available pages before exploring further.

# Deployment Overview

> Learn about deployment options and requirements for Medusa applications

# 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:

```bash theme={null}
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

### Redis (Optional but Recommended)

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

<Warning>
  While Redis is optional for development, it is **strongly recommended** for production deployments to ensure reliability and performance.
</Warning>

## 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

<Note>
  Always use environment variables for sensitive configuration like database credentials, API keys, and secrets. Never commit these to version control.
</Note>

Essential environment variables for production:

```bash theme={null}
# 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](/deployment/environment-variables) page for a complete list.

### Database Migrations

Before starting your application in production, always run migrations:

```bash theme={null}
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

<Warning>
  Never skip migrations in production. Running the application without migrations will cause errors.
</Warning>

### Build Process

For production deployments, build your application:

```bash theme={null}
# 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:

```bash theme={null}
MEDUSA_WORKER_MODE=server  # or 'worker' or 'shared'
```

For production, run separate server and worker processes:

```bash theme={null}
# 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:

```bash theme={null}
# Check if the server is running
curl http://localhost:9000/health
```

### Monitoring and Logging

Configure logging level for production:

```bash theme={null}
LOG_LEVEL=info  # Options: error, warn, info, debug
```

<Note>
  Use `error` or `warn` in production to reduce log volume. Use `debug` only for troubleshooting.
</Note>

## 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

```bash theme={null}
# Generate a secure random secret
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"
```

### CORS Configuration

Properly configure CORS for your domains:

```bash theme={null}
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

<CardGroup cols={2}>
  <Card title="Configuration" icon="gear" href="/deployment/configuration">
    Learn how to configure Medusa via medusa-config.js
  </Card>

  <Card title="Database Setup" icon="database" href="/deployment/database">
    PostgreSQL configuration and migrations
  </Card>

  <Card title="Environment Variables" icon="key" href="/deployment/environment-variables">
    Complete reference of all environment variables
  </Card>
</CardGroup>