scriptshare-cursor/DOCKER_DEPLOYMENT.md

# 🐳 ScriptShare Docker Deployment Guide

## Overview

This guide covers deploying ScriptShare to any generic Docker server using Docker Compose. The setup includes:

- **Frontend**: React application served by Nginx
- **Backend API**: Node.js Express server
- **Database**: MySQL 8.0
- **Reverse Proxy**: Nginx with load balancing
- **Cache**: Redis (optional)
- **Monitoring**: Health checks and logging

## Prerequisites

- Docker Engine 20.10+
- Docker Compose 2.0+
- At least 2GB RAM
- 10GB+ disk space
- Linux/macOS server (Windows with WSL2)

## Quick Start

### 1. **Prepare Environment**

```bash
# Clone the repository
git clone <your-repo-url>
cd scriptshare-cursor

# Copy and configure environment
cp env.production .env
# Edit .env with your specific settings
nano .env
```

### 2. **Deploy Application**

```bash
# Make scripts executable (Linux/macOS)
chmod +x scripts/*.sh

# Run deployment
./scripts/deploy.sh
```

### 3. **Verify Deployment**

```bash
# Check service status
./scripts/manage.sh status

# View logs
./scripts/manage.sh logs
```

## Configuration

### Environment Variables

Edit `env.production` before deployment:

```bash
# Domain Configuration
APP_URL=https://your-domain.com
FRONTEND_URL=https://your-domain.com
CORS_ORIGIN=https://your-domain.com

# Security (CHANGE THESE!)
JWT_SECRET=your-super-secret-jwt-key
DB_PASSWORD=your-secure-database-password
DB_ROOT_PASSWORD=your-root-password
REDIS_PASSWORD=your-redis-password

# Ports (adjust if needed)
PROXY_PORT=80
PROXY_SSL_PORT=443
API_PORT=3001
```

### SSL Configuration

1. **Place SSL certificates** in `./certs/`:
   ```
   certs/
   ├── fullchain.pem
   └── privkey.pem
   ```

2. **Enable HTTPS** in `nginx/conf.d/scriptshare.conf`:
   - Uncomment the SSL server block
   - Update `server_name` with your domain

3. **Restart proxy**:
   ```bash
   ./scripts/manage.sh restart scriptshare-proxy
   ```

## Service Architecture

```
┌─────────────────┐    ┌─────────────────┐
│   Nginx Proxy   │────│   Frontend      │
│   Port 80/443   │    │   (React+Nginx) │
└─────────────────┘    └─────────────────┘
         │                       │
         │              ┌─────────────────┐
         └──────────────│   Backend API   │
                        │   (Node.js)     │
                        └─────────────────┘
                                 │
                        ┌─────────────────┐
                        │   MySQL 8.0     │
                        │   Database      │
                        └─────────────────┘
                                 │
                        ┌─────────────────┐
                        │   Redis Cache   │
                        │   (Optional)    │
                        └─────────────────┘
```

## Management Commands

### Service Management

```bash
# Start all services
./scripts/manage.sh start

# Stop all services
./scripts/manage.sh stop

# Restart services
./scripts/manage.sh restart

# View service status
./scripts/manage.sh status

# View logs (all services)
./scripts/manage.sh logs

# View logs (specific service)
./scripts/manage.sh logs scriptshare-api
```

### Database Management

```bash
# Connect to database
./scripts/manage.sh db

# Create backup
./scripts/manage.sh backup

# Run migrations (from API container)
docker-compose -f docker-compose.prod.yml exec scriptshare-api npm run db:migrate:prod
```

### Maintenance

```bash
# Update application
./scripts/manage.sh update

# Clean up Docker resources
./scripts/manage.sh clean

# Open shell in container
./scripts/manage.sh shell scriptshare-api
```

## Port Configuration

| Service | Internal Port | External Port | Description |
|---------|---------------|---------------|-------------|
| Proxy | 80, 443 | 8080, 8443 | Main entry point |
| Frontend | 80 | - | React application |
| API | 3000 | 3001 | REST API |
| Database | 3306 | 3306 | MySQL database |
| Redis | 6379 | 6379 | Cache store |

## Monitoring

### Health Checks

All services include health checks:

```bash
# Check health status
curl http://localhost:8080/health

# API health
curl http://localhost:3001/api/health

# Individual service health
docker ps --format "table {{.Names}}\t{{.Status}}"
```

### Logging

Logs are stored in Docker volumes and can be accessed via:

```bash
# All services
docker-compose -f docker-compose.prod.yml logs -f

# Specific service
docker-compose -f docker-compose.prod.yml logs -f scriptshare-api

# Save logs to file
docker-compose -f docker-compose.prod.yml logs > scriptshare.log
```

## Backup & Recovery

### Automated Backups

Configure automated backups by adding to crontab:

```bash
# Edit crontab
crontab -e

# Add daily backup at 2 AM
0 2 * * * /path/to/scriptshare/scripts/backup.sh
```

### Manual Backup

```bash
# Create backup
./scripts/backup.sh

# Backups are stored in ./backups/
ls -la backups/
```

### Recovery

```bash
# Stop database
docker-compose -f docker-compose.prod.yml stop scriptshare-db

# Restore from backup
gunzip -c backups/scriptshare_backup_YYYYMMDD_HHMMSS.sql.gz | \
docker exec -i scriptshare-db mysql -u root -p'your-root-password'

# Start database
docker-compose -f docker-compose.prod.yml start scriptshare-db
```

## Security Considerations

### 1. **Change Default Passwords**
- Update all passwords in `env.production`
- Use strong, unique passwords
- Consider using environment variable files

### 2. **Network Security**
- Configure firewall rules
- Use reverse proxy for SSL termination
- Implement rate limiting (configured in nginx)

### 3. **SSL/TLS**
- Use Let's Encrypt for free SSL certificates
- Configure HSTS headers
- Use modern TLS protocols only

### 4. **Container Security**
- Keep Docker images updated
- Run containers with non-root users where possible
- Use Docker secrets for sensitive data

## Troubleshooting

### Common Issues

1. **Services won't start**:
   ```bash
   # Check logs
   docker-compose -f docker-compose.prod.yml logs
   
   # Check disk space
   df -h
   
   # Check memory
   free -h
   ```

2. **Database connection errors**:
   ```bash
   # Test database connectivity
   docker exec scriptshare-db mysqladmin ping -u root -p'password'
   
   # Check database logs
   docker-compose -f docker-compose.prod.yml logs scriptshare-db
   ```

3. **API not responding**:
   ```bash
   # Check API health
   curl http://localhost:3001/api/health
   
   # Check API logs
   docker-compose -f docker-compose.prod.yml logs scriptshare-api
   ```

### Performance Tuning

1. **Database Optimization**:
   - Adjust `innodb_buffer_pool_size` in MySQL configuration
   - Monitor slow query log
   - Add database indexes as needed

2. **Nginx Optimization**:
   - Enable gzip compression (configured)
   - Adjust worker processes
   - Configure caching headers

3. **Resource Limits**:
   - Set memory and CPU limits in docker-compose.prod.yml
   - Monitor resource usage with `docker stats`

## Scaling

### Horizontal Scaling

To scale the application:

```bash
# Scale API containers
docker-compose -f docker-compose.prod.yml up -d --scale scriptshare-api=3

# Scale frontend containers
docker-compose -f docker-compose.prod.yml up -d --scale scriptshare-frontend=2
```

### Load Balancing

Nginx automatically load balances between multiple container instances.

## Production Checklist

- [ ] Update all default passwords
- [ ] Configure SSL certificates
- [ ] Set up automated backups
- [ ] Configure monitoring and alerting
- [ ] Set up log rotation
- [ ] Configure firewall rules
- [ ] Test disaster recovery procedures
- [ ] Set up domain and DNS
- [ ] Configure SMTP for emails (if applicable)
- [ ] Set up monitoring dashboard

## Support

For issues and questions:

1. Check the logs first
2. Review this documentation
3. Check Docker and system resources
4. Create an issue in the repository

**Your ScriptShare application is now ready for production deployment! 🚀**