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](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 <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**:
   ```bash
   # 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**:
   ```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.