Deploying a Medusa Backend on DigitalOcean App Platform

This guide describes how to set up and deploy a Medusa backend using DigitalOcean App Platform with managed PostgreSQL and Valkey databases.

Prerequisites

Before you begin, make sure you have the following:

• A DigitalOcean account
• Git installed on your local machine
• A GitHub account

1. Create Managed Database Instances

PostgreSQL Configuration

1. In your DigitalOcean dashboard, go to Databases and click Create Database Cluster.

2. Choose PostgreSQL as the database type.

3. Configure your instance with the following options:

   • CPU options: Regular
   • Plan: 1 vCPU / 1 GB RAM / 10 GB Storage / Connection limit: 22
   • Storage size: 10 GB
   • Optional: Enable autoscaling if desired
   • Region: Choose the same region you plan to deploy your app in
   • Expected cost: $15.15 per month

4. Once the database is created, open the Connection Details tab and copy the connection string. It should look like this:

   postgres://<user>:<password>@<host>:<port>/<database>?sslmode=require
   

5. Save this connection string. You will need to modify it later to set sslmode=no-verify.

Valkey Configuration

1. Go to Databases again and click Create Database Cluster.

2. Choose Valkey.

3. Use the $15 per month plan.

4. Copy the connection string, which typically looks like:

   redis://<user>:<password>@<host>:<port>
   

5. Save this string for use in your environment variables.

2. Prepare the Medusa Project

1. Fork the official Medusa starter project: https://github.com/medusajs/medusa-starter-default

2. In your forked repository:

   • Download and use the Medusa configuration file from: https://github.com/u11d-com/medusa-starter/blob/main/backend/medusa-config.ts
   • Download and use the startup script from: https://github.com/u11d-com/medusa-starter/blob/main/backend/start.sh

3. Modify the package.json file to update the start command only:

   {
     "scripts": {
       "start": "./start.sh"
     }
   }
   

4. Commit and push your changes to GitHub.

3. Deploy on DigitalOcean App Platform

1. In your DigitalOcean dashboard, go to Apps and click Create App.

2. Connect your GitHub account and select the repository you forked.

3. Choose the branch you want to deploy (for example, main).

4. In the deployment settings, provide the following:

   • Build Command: yarn run build
   • Run Command: yarn run start
   • Network: Public
   • Port: 9000

5. Under Environment Variables, add the following variables:

   Variable	Description
   DATABASE_URL	PostgreSQL connection string, but replace sslmode=require with sslmode=no-verify
   REDIS_URL	Valkey connection string
   CACHE_REDIS_URL	Same as Valkey connection string
   LOCKING_REDIS_URL	Same as Valkey connection string
   EVENTS_REDIS_URL	Same as Valkey connection string
   WE_REDIS_URL	Same as Valkey connection string
   NODE_ENV	production
   MEDUSA_CREATE_ADMIN_USER	Set to true to create an admin user on startup
   MEDUSA_ADMIN_EMAIL	Email address for the initial admin user
   MEDUSA_ADMIN_PASSWORD	Password for the initial admin user

6. Make sure to select the same data center region as your PostgreSQL and Valkey databases.

7. Set a health check path to /health.

4. Build and Verify

1. Click Deploy App.

2. Wait for the build process to complete. This may take several minutes.

3. Once deployed, test your Medusa backend by visiting:

   https://<your-app>.ondigitalocean.app/health
   

   You should receive a healthy response if everything is set up correctly.

4. The Medusa Admin panel will be available at the following path:

   https://<your-app>.ondigitalocean.app/app
   

Summary

You have now deployed a Medusa backend on DigitalOcean App Platform using managed PostgreSQL and Valkey services. Your environment is configured for production with an optional admin user creation process and accessible admin panel at the /app path.