Deploy to DigitalOcean

DigitalOcean App Platform is the recommended deployment target for Open Sky Commerce. It handles building, running, and scaling your Next.js app without server administration, and pairs naturally with DigitalOcean Managed Databases and Spaces.

Prerequisites

• A DigitalOcean account (digitalocean.com)
• Your code in a private GitHub, GitLab, or Bitbucket repository
• All services you plan to use configured and ready: Spaces bucket, payment credentials, SendGrid API key

Step 1 — Create a Managed PostgreSQL Database

1. In the DigitalOcean dashboard, click Create → Database.
2. Select PostgreSQL. For most stores the smallest plan (1 vCPU / 1 GB RAM) is sufficient to start.
3. Choose the same datacenter region you plan to use for the app (e.g. SFO3, NYC3). Co-locating the app and database reduces latency.
4. Click Create Database Cluster and wait for provisioning.
5. Once running, go to the cluster overview and click the Connection Details tab.
6. Copy the Connection String (URI format). It will look like:

   postgresql://doadmin:[email protected]:25060/defaultdb?sslmode=require

7. You may optionally create a dedicated database user and database name instead of using doadmin / defaultdb. Either works.

Step 2 — Create a Spaces Bucket (if not already done)

See Media Storage for full instructions. You need the bucket created and the environment variables ready before configuring the app.

Step 3 — Push Your Code to a Git Repository

App Platform deploys directly from a Git branch. Push your code to a private repository on GitHub, GitLab, or Bitbucket. DigitalOcean will ask for authorization to read that repository during app creation.

git remote add origin https://github.com/yourname/yourrepo.git
git push -u origin main

Step 4 — Create an App Platform App

1. In the DigitalOcean dashboard, click Create → App.
2. Select GitHub (or GitLab / Bitbucket) and authorize the connection if prompted.
3. Select your repository and the branch to deploy (e.g. main).
4. DigitalOcean will auto-detect a Node.js / Next.js app. Confirm or set:
   • Build Command: npm run build
   • Run Command: npm start
   • HTTP Port: 3000
5. On the Environment Variables screen, add all required variables. At minimum:

   DATABASE_URL=postgresql://...?sslmode=require
   NEXTAUTH_URL=https://your-app.ondigitalocean.app
   NEXTAUTH_SECRET=your-random-secret-min-32-chars
   NEXT_PUBLIC_SITE_URL=https://your-app.ondigitalocean.app

   Then add all optional service keys. See Environment Variables for the full list. Mark sensitive keys as Encrypted using the lock icon.
6. Choose a plan. The Basic tier starts at $5/month.
7. Click Create Resources. The first build will begin.

Step 5 — Run Database Migrations

After the app is deployed, run your Prisma migrations against the production database. Use the App Platform console:

1. In your app's page, go to the Console tab.
2. Run:

   npx prisma migrate deploy

Use migrate deploy (not migrate dev) in production — it applies existing migration files only, without interactive prompts or creating new ones.

Alternatively, you can run migrations from your local machine by temporarily setting DATABASE_URL in your local .env to the production connection string:

DATABASE_URL="postgresql://doadmin:...@db-host:25060/defaultdb?sslmode=require"   npx prisma migrate deploy

Step 6 — (Optional) Import Seed Data

If starting fresh, you can seed demo data against the production database from your local machine using the same temporary connection string approach:

DATABASE_URL="postgresql://..." npm run import-demo-data

Only do this on a brand-new database — the seed script may conflict with existing records.

Step 7 — Add a Custom Domain

1. In your app's Settings → Domains, click Add Domain.
2. Enter your domain (e.g. store.yourbrand.com).
3. Follow the CNAME or A record instructions — add them in your domain registrar's DNS settings.
4. Wait for DNS propagation (up to 48 hours but usually minutes). App Platform provisions a free Let's Encrypt SSL certificate automatically.
5. Update your environment variables to use the custom domain:

   NEXTAUTH_URL=https://store.yourbrand.com
   NEXT_PUBLIC_SITE_URL=https://store.yourbrand.com

   Trigger a new deploy after changing env vars (App Platform does this automatically when you save).

Step 8 — Configure the Stripe Webhook (if using Stripe)

1. In the Stripe dashboard (Developers → Webhooks), click Add endpoint.
2. Set the endpoint URL to:

   https://yourdomain.com/api/webhooks/stripe

3. Subscribe to payment_intent.succeeded and payment_intent.payment_failed.
4. Copy the webhook signing secret and add it as STRIPE_WEBHOOK_SECRET in your app environment variables.

Automatic Deployments

App Platform automatically redeploys your app every time you push to the configured branch. To deploy a change:

git add .
git commit -m "your change"
git push origin main

A new build starts within seconds. You can monitor build progress and logs under the Activity tab in your app's dashboard.

Scaling

To handle more traffic, go to Settings → Resources and increase the plan size or instance count. App Platform supports horizontal scaling (multiple instances) without configuration changes to the app itself.

Troubleshooting

Build fails with "prisma: command not found"

This happens when Prisma is in devDependencies and the platform prunes dev dependencies before build. Ensure prisma is in dependencies (not just devDependencies) in your package.json, or set the environment variable NPM_CONFIG_PRODUCTION=false.

Database connection refused

Check that ?sslmode=require is appended to your DATABASE_URL. DigitalOcean Managed Databases require SSL.

NEXTAUTH_URL mismatch errors

NEXTAUTH_URL must exactly match the URL your app is served from — including the protocol (https://) and without a trailing slash.