scriptshare-cursor/DEPLOYMENT.md

DigitalOcean Deployment Guide

This guide walks you through deploying ScriptShare to DigitalOcean App Platform with a managed MySQL database.

Prerequisites

• DigitalOcean account
• GitHub repository containing your code
• Basic familiarity with DigitalOcean App Platform

Architecture Overview

The deployment consists of:

• Frontend: Static site (React/Vite build)
• Backend API: Node.js service with Express
• Database: DigitalOcean Managed MySQL Database

Step 1: Prepare Your Repository

1. Ensure all the deployment files are in your GitHub repository:

   .do/app.yaml              # App Platform configuration
   Dockerfile.api            # Backend API container
   drizzle.config.production.ts  # Production DB config
   scripts/migrate-production.js # Migration script
   scripts/setup-production-db.js # DB setup script
   env.production.example    # Environment variables template
   

2. Commit and push all changes to your main branch.

Step 2: Create the DigitalOcean App

Option A: Using the DigitalOcean Console

1. Go to the DigitalOcean App Platform
2. Click "Create App"
3. Choose "GitHub" as your source
4. Select your repository and branch (usually main)
5. DigitalOcean will automatically detect the app.yaml configuration

Option B: Using the CLI

# Install doctl CLI
# On macOS: brew install doctl
# On Linux: snap install doctl

# Authenticate
doctl auth init

# Create the app
doctl apps create --spec .do/app.yaml

Step 3: Configure Environment Variables

In the DigitalOcean dashboard, go to your app's Settings > Environment Variables and set:

Required Variables

JWT_SECRET=your-super-secret-jwt-key-here-change-this-in-production
ADMIN_EMAIL=admin@yourcompany.com
ADMIN_USERNAME=admin
ADMIN_PASSWORD=your-secure-password

Optional Variables

VITE_ANALYTICS_ENABLED=true
RATE_LIMIT_ENABLED=true
RATE_LIMIT_WINDOW_MS=900000
RATE_LIMIT_MAX_REQUESTS=100

⚠️ Security Note: Generate a strong JWT secret:

node -e "console.log(require('crypto').randomBytes(64).toString('hex'))"

Step 4: Database Setup

The managed MySQL database will be automatically created. After the first deployment:

1. Run Database Migrations:

   # In your app's console (or via GitHub Actions)
   npm run db:setup:prod
   

2. Verify Database Connection: Check the API health endpoint: https://your-api-url/api/health

Step 5: Update App Configuration

1. Update Frontend URLs: After deployment, update the environment variables with actual URLs:

   VITE_APP_URL=https://your-frontend-url.ondigitalocean.app
   VITE_API_URL=https://your-api-url.ondigitalocean.app/api
   CORS_ORIGIN=https://your-frontend-url.ondigitalocean.app
   

2. Redeploy: The app will automatically redeploy when you change environment variables.

Step 6: Custom Domain (Optional)

1. In your app settings, go to Domains
2. Click Add Domain
3. Enter your domain name
4. Configure DNS records as instructed

Database Management

Connecting to the Database

# Get connection string from DigitalOcean dashboard
mysql -h your-db-host -P 25060 -u your-username -p your-database-name --ssl-mode=REQUIRED

Running Migrations

# Production migration
npm run db:migrate:prod

# Create new migration
npm run db:generate

Backup and Restore

DigitalOcean provides automatic daily backups. For manual backups:

# Create backup
mysqldump -h your-db-host -P 25060 -u your-username -p your-database-name --ssl-mode=REQUIRED > backup.sql

# Restore backup
mysql -h your-db-host -P 25060 -u your-username -p your-database-name --ssl-mode=REQUIRED < backup.sql

Monitoring and Logs

Application Logs

• View logs in DigitalOcean Console: App → Runtime Logs
• Or via CLI: doctl apps logs <app-id> --type=run

Database Monitoring

• Database metrics available in DigitalOcean dashboard
• Set up alerts for CPU, memory, and connection usage

Health Checks

• API: https://your-api-url/api/health
• Frontend: Built-in App Platform health checks

Scaling

Vertical Scaling

• Increase instance size in App Platform settings
• Database can be scaled up (not down) in database settings

Horizontal Scaling

• Increase instance count for API service
• Frontend is automatically scaled as a static site

Security Best Practices

1. Environment Variables: Never commit secrets to Git
2. Database Access: Use DigitalOcean's private networking
3. SSL/TLS: Enabled by default on App Platform
4. Database Backups: Verify daily backups are working
5. Access Control: Use DigitalOcean teams for access management

Troubleshooting

Common Issues

1. Build Failures:

   # Check build logs
   doctl apps logs <app-id> --type=build
   

2. Database Connection Issues:

   • Verify DATABASE_URL format
   • Check firewall settings
   • Ensure SSL is enabled

3. CORS Errors:

   • Verify CORS_ORIGIN matches frontend URL
   • Check environment variable casing

4. Missing Dependencies:

   # Clear npm cache and rebuild
   npm ci --clean-cache
   

Getting Support

• DigitalOcean Community: https://www.digitalocean.com/community
• Support tickets: https://cloud.digitalocean.com/support
• Documentation: https://docs.digitalocean.com/products/app-platform/

Cost Optimization

Current Configuration Costs (Approximate)

• API Service: $5/month (Basic plan)
• Database: $15/month (1GB RAM, 1 vCPU)
• Static Site: $0 (included with API service)
• Total: ~$20/month

Cost Reduction Tips

1. Use development database for testing
2. Scale down during low usage periods
3. Monitor and optimize database queries
4. Use CDN for static assets

Deployment Checklist

• Repository configured with deployment files
• Environment variables set in DigitalOcean
• JWT secret generated and configured
• Database migrations run successfully
• Health check endpoints responding
• Frontend can communicate with API
• Admin user created and accessible
• Custom domain configured (if applicable)
• Monitoring and alerts set up
• Backup strategy verified

Next Steps

1. Set up CI/CD: Configure GitHub Actions for automated deployments
2. Monitoring: Set up application performance monitoring
3. CDN: Configure CDN for static assets
4. Analytics: Integrate application analytics
5. Error Tracking: Set up error monitoring service

Support

For issues specific to this deployment setup, please check:

1. DigitalOcean App Platform documentation
2. Application logs in the DigitalOcean console
3. Database connection and query logs

Remember to regularly update dependencies and monitor security advisories for your application stack.