# 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](https://cloud.digitalocean.com/apps) 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 ```bash # 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: ```bash 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**: ```bash # 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 ```bash # 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 ```bash # 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: ```bash # 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 --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**: ```bash # Check build logs doctl apps logs --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**: ```bash # 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.