Refactor deployment documentation for ScriptShare, consolidating deployment guides into a single comprehensive document while removing outdated Docker deployment files and scripts. Enhance clarity on deployment options across various platforms and streamline the application structure overview.

2025-08-20 00:43:09 +01:00
parent 68a02d1e5f
commit 58d8886480
17 changed files with 588 additions and 1893 deletions
--- a/DEPLOYMENT.md
+++ b/DEPLOYMENT.md
@ -1,248 +1,261 @@
-# DigitalOcean Deployment Guide
+# 🚀 ScriptShare - Platform Deployment Guide

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

-## Prerequisites
+ScriptShare is a modern React application with a Node.js API backend, designed to work seamlessly with any deployment platform including **Vercel**, **Coolify**, **DigitalOcean App Platform**, **Railway**, **Render**, and others.

- DigitalOcean account
- GitHub repository containing your code
- Basic familiarity with DigitalOcean App Platform
+## 📦 Application Structure

-## Architecture Overview
+### Frontend (React + Vite)
+- **Dockerfile**: `Dockerfile` 
+- **Build**: Vite-based React application
+- **Output**: Static files served by Nginx
+- **Port**: 80

-The deployment consists of:
- **Frontend**: Static site (React/Vite build)
- **Backend API**: Node.js service with Express
- **Database**: DigitalOcean Managed MySQL Database
+### Backend API (Node.js + Express)
+- **Dockerfile**: `Dockerfile.api`
+- **Runtime**: Node.js 18 with TypeScript
+- **Port**: 3000
+- **Health Check**: `/api/health`

-## Step 1: Prepare Your Repository
+## 🔧 Deployment Options

-1. Ensure all the deployment files are in your GitHub repository:
+### Option 1: Vercel (Recommended for Frontend)
+
+**Frontend Deployment:**
+1. Connect your repository to Vercel
+2. Set build command: `npm run build`
+3. Set output directory: `dist`
+4. Configure environment variables:
   ```
-   .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
+   VITE_APP_NAME=ScriptShare
+   VITE_APP_URL=https://your-domain.vercel.app
+   VITE_ANALYTICS_ENABLED=true
   ```

-2. Commit and push all changes to your main branch.
+**API Deployment:**
+- Deploy API separately to platforms like Railway, Render, or DigitalOcean
+- Or use Vercel Functions (requires code modification)

-## Step 2: Create the DigitalOcean App
+### Option 2: Coolify (Full Stack)

-### Option A: Using the DigitalOcean Console
+**Deploy both frontend and API:**
+1. Create application from Git repository
+2. **Frontend**: 
+   - Use `Dockerfile` 
+   - Port: 80
+3. **API**: 
+   - Use `Dockerfile.api`
+   - Port: 3000
+4. Configure environment variables

-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 3: DigitalOcean App Platform

-### Option B: Using the CLI
+Create `app.yaml`:
+```yaml
+name: scriptshare
+services:
+- name: frontend
+  source_dir: /
+  dockerfile_path: Dockerfile
+  github:
+    repo: your-username/scriptshare-cursor
+    branch: main
+  http_port: 80
+  routes:
+  - path: /
+- name: api
+  source_dir: /
+  dockerfile_path: Dockerfile.api
+  github:
+    repo: your-username/scriptshare-cursor
+    branch: main
+  http_port: 3000
+  routes:
+  - path: /api
+  envs:
+  - key: NODE_ENV
+    value: production
+  - key: DATABASE_URL
+    value: ${DATABASE_URL}
+databases:
+- name: scriptshare-db
+  engine: MYSQL
+  version: "8"
+```

+### Option 4: Railway
+
+1. **Frontend**: Connect repo, Railway auto-detects Dockerfile
+2. **API**: Deploy from same repo using `Dockerfile.api`
+3. **Database**: Add MySQL service
+4. Configure environment variables
+
+### Option 5: Render
+
+1. **Frontend**: 
+   - Static Site
+   - Build Command: `npm run build`
+   - Publish Directory: `dist`
+2. **API**: 
+   - Web Service
+   - Docker build using `Dockerfile.api`
+3. **Database**: Add MySQL database
+
+## 🏗️ Build Commands
+
+### Frontend
 ```bash
-# Install doctl CLI
-# On macOS: brew install doctl
-# On Linux: snap install doctl
+# Install dependencies
+npm install

-# Authenticate
-doctl auth init
+# Build for production
+npm run build

-# Create the app
-doctl apps create --spec .do/app.yaml
+# Preview build
+npm run preview
 ```

-## 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:
+### API
 ```bash
-node -e "console.log(require('crypto').randomBytes(64).toString('hex'))"
+# Install dependencies
+npm install
+
+# Build TypeScript
+npm run build:api
+
+# Start API server
+npm run start:api
 ```

-## Step 4: Database Setup
+## 🔐 Environment Variables

-The managed MySQL database will be automatically created. After the first deployment:
+### Frontend (Build-time)
+- `VITE_APP_NAME` - Application name
+- `VITE_APP_URL` - Frontend URL
+- `VITE_ANALYTICS_ENABLED` - Enable analytics (true/false)

-1. **Run Database Migrations**:
-   ```bash
-   # In your app's console (or via GitHub Actions)
-   npm run db:setup:prod
-   ```
+### API (Runtime)
+- `NODE_ENV` - Environment (production/development)
+- `PORT` - Server port (default: 3000)
+- `DATABASE_URL` - MySQL connection string
+- `JWT_SECRET` - JWT secret key
+- `CORS_ORIGIN` - Allowed CORS origins

-2. **Verify Database Connection**:
-   Check the API health endpoint: `https://your-api-url/api/health`
+## 🗄️ Database Setup

-## 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
+### MySQL Connection String Format:
+```
+DATABASE_URL=mysql://username:password@host:port/database
+```

+### Required Tables:
+The application uses Drizzle ORM. Run migrations after deployment:
 ```bash
-# Get connection string from DigitalOcean dashboard
-mysql -h your-db-host -P 25060 -u your-username -p your-database-name --ssl-mode=REQUIRED
+npm run db:migrate
 ```

-### Running Migrations
+## 🔍 Health Checks

+### Frontend Health Check:
+```
+GET /health
+```
+
+### API Health Check:
+```
+GET /api/health
+```
+
+## 📝 Platform-Specific Notes
+
+### Vercel
+- Frontend deploys automatically
+- Use Vercel Functions for API (requires modification)
+- Environment variables in Vercel dashboard
+
+### Coolify
+- Supports full Docker deployment
+- Easy environment variable management
+- Built-in SSL and domain management
+
+### DigitalOcean App Platform
+- Use `app.yaml` for configuration
+- Automatic HTTPS
+- Managed database available
+
+### Railway
+- Auto-deployment from Git
+- Environment variables in dashboard
+- Add-on database services
+
+### Render
+- Separate frontend (static) and backend (web service)
+- Auto-deployment from Git
+- Environment variables in dashboard
+
+## 🐳 Docker Commands
+
+### Build Frontend:
 ```bash
-# Production migration
-npm run db:migrate:prod
-
-# Create new migration
-npm run db:generate
+docker build -t scriptshare-frontend .
+docker run -p 3000:80 scriptshare-frontend
 ```

-### Backup and Restore
-
-DigitalOcean provides automatic daily backups. For manual backups:
-
+### Build API:
 ```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
+docker build -f Dockerfile.api -t scriptshare-api .
+docker run -p 3001:3000 scriptshare-api
 ```

-## Monitoring and Logs
+### Local Development:
+```bash
+docker-compose up
+```

-### Application Logs
- View logs in DigitalOcean Console: App → Runtime Logs
- Or via CLI: `doctl apps logs <app-id> --type=run`
+## 🔧 Local Development

-### Database Monitoring
- Database metrics available in DigitalOcean dashboard
- Set up alerts for CPU, memory, and connection usage
+### Frontend:
+```bash
+npm run dev
+```

-### Health Checks
- API: `https://your-api-url/api/health`
- Frontend: Built-in App Platform health checks
+### API:
+```bash
+npm run build:api
+npm run start:api
+```

-## Scaling
+### Database:
+```bash
+npm run db:studio  # Drizzle Studio
+npm run db:migrate # Run migrations
+```

-### Vertical Scaling
- Increase instance size in App Platform settings
- Database can be scaled up (not down) in database settings
+## 🚀 Quick Deploy Examples

-### Horizontal Scaling
- Increase instance count for API service
- Frontend is automatically scaled as a static site
+### Deploy to Vercel (Frontend):
+```bash
+vercel --prod
+```

-## Security Best Practices
+### Deploy to Railway:
+```bash
+railway deploy
+```

-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
+### Deploy to Render:
+Connect GitHub repository in Render dashboard

-## Troubleshooting
+## 📞 Support

-### Common Issues
+- **Documentation**: Check platform-specific documentation
+- **Environment**: Ensure all required environment variables are set
+- **Health Checks**: Monitor `/health` and `/api/health` endpoints
+- **Logs**: Check platform logs for deployment 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
+**Your ScriptShare application is ready for deployment on any modern platform! 🎉**

-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.
+Choose the platform that best fits your needs - from simple static hosting to full-stack container deployments.