Add new build and database setup scripts to package.json for production
This commit is contained in:
248
DEPLOYMENT.md
Normal file
248
DEPLOYMENT.md
Normal file
@ -0,0 +1,248 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user