easystream-main/DOCKER_DEPLOYMENT_GUIDE.md

# EasyStream - Complete Docker Deployment Guide

## Table of Contents
- [Prerequisites](#prerequisites)
- [Quick Start (Development)](#quick-start-development)
- [Production Deployment](#production-deployment)
- [Folder Sync Setup](#folder-sync-setup)
- [Database Management](#database-management)
- [Troubleshooting](#troubleshooting)
- [Security Checklist](#security-checklist)

---

## Prerequisites

### System Requirements
- **OS**: Windows 10/11, Linux, or macOS
- **Docker**: Version 20.10 or higher
- **Docker Compose**: Version 2.0 or higher
- **RAM**: Minimum 4GB (8GB recommended)
- **Disk**: Minimum 20GB free space

### Check Your Installation
```bash
docker --version
docker-compose --version
```

---

## Quick Start (Development)

### 1. Clone or Navigate to Project
```bash
cd E:\repos\easystream-main
```

### 2. Configure Environment
```bash
# Copy the example environment file
copy .env.example .env

# Edit .env with your settings (optional for development)
notepad .env
```

### 3. Start All Services
```bash
# Start in detached mode
docker-compose up -d

# View logs
docker-compose logs -f
```

### 4. Wait for Database Initialization
The database will automatically initialize with all tables and default data. This takes about 2-3 minutes.

```bash
# Check database health
docker-compose ps

# Watch database logs
docker-compose logs -f db
```

### 5. Access the Application
- **Frontend**: http://localhost:8083
- **Admin Panel**: http://localhost:8083/admin
- **Default Admin Credentials**:
  - Username: `admin`
  - Password: `admin123` (⚠️ **CHANGE THIS IMMEDIATELY!**)

### 6. Test RTMP Streaming
```bash
# Stream URL (use in OBS or streaming software)
rtmp://localhost:1935/live/testkey

# View HLS stream
http://localhost:8083/hls/testkey/index.m3u8
```

---

## Production Deployment

### Step 1: Prepare Production Environment

#### 1.1 Copy Production Configuration
```bash
copy .env.production .env
```

#### 1.2 Generate Secure Secrets
Create the secrets directory:
```bash
mkdir secrets
```

Generate secure random keys (use one of these methods):

**Method A: Using OpenSSL (Linux/Mac)**
```bash
openssl rand -hex 32 > secrets/api_key.txt
openssl rand -hex 32 > secrets/jwt_secret.txt
openssl rand -hex 32 > secrets/encryption_key.txt
openssl rand -hex 32 > secrets/cron_secret.txt
openssl rand -hex 24 > secrets/db_password.txt
openssl rand -hex 24 > secrets/db_root_password.txt
```

**Method B: Using PowerShell (Windows)**
```powershell
.\generate-secrets.ps1
```

**Method C: Using Docker**
```bash
docker run --rm alpine sh -c "head -c 32 /dev/urandom | base64" > secrets/api_key.txt
docker run --rm alpine sh -c "head -c 32 /dev/urandom | base64" > secrets/jwt_secret.txt
docker run --rm alpine sh -c "head -c 32 /dev/urandom | base64" > secrets/encryption_key.txt
docker run --rm alpine sh -c "head -c 32 /dev/urandom | base64" > secrets/cron_secret.txt
docker run --rm alpine sh -c "head -c 24 /dev/urandom | base64" > secrets/db_password.txt
docker run --rm alpine sh -c "head -c 24 /dev/urandom | base64" > secrets/db_root_password.txt
```

#### 1.3 Update Production Configuration
Edit `.env` and update these critical values:
```env
MAIN_URL=https://your-domain.com
DB_PASS=<content of secrets/db_password.txt>
API_KEY=<content of secrets/api_key.txt>
JWT_SECRET=<content of secrets/jwt_secret.txt>
ENCRYPTION_KEY=<content of secrets/encryption_key.txt>
```

### Step 2: Set Up SSL/TLS

#### Option A: Let's Encrypt (Automatic - Recommended)
Update your `Caddyfile`:
```
your-domain.com {
    encode gzip
    root * /srv/easystream
    php_fastcgi php:9000
    file_server
}
```

Caddy will automatically obtain and renew SSL certificates.

#### Option B: Custom Certificates
Place your certificates in `./deploy/ssl/`:
```bash
mkdir -p deploy/ssl
# Copy your certificate files
copy your-cert.pem deploy/ssl/
copy your-key.pem deploy/ssl/
```

### Step 3: Create Production Volumes
```bash
# Create directories for persistent data
mkdir -p /var/lib/easystream/db
mkdir -p /var/lib/easystream/uploads
mkdir -p /var/lib/easystream/recordings
mkdir -p /var/log/easystream
```

### Step 4: Deploy Production Stack
```bash
# Pull latest images
docker-compose -f docker-compose.prod.yml pull

# Build custom images
docker-compose -f docker-compose.prod.yml build

# Start services
docker-compose -f docker-compose.prod.yml up -d

# Check status
docker-compose -f docker-compose.prod.yml ps

# View logs
docker-compose -f docker-compose.prod.yml logs -f
```

### Step 5: Post-Deployment Verification
```bash
# Test database connection
docker-compose -f docker-compose.prod.yml exec php php -r "new PDO('mysql:host=db;dbname=easystream', 'easystream', getenv('DB_PASS')); echo 'DB OK\n';"

# Test Redis connection
docker-compose -f docker-compose.prod.yml exec php php -r "\$redis = new Redis(); \$redis->connect('redis', 6379); echo 'Redis OK\n';"

# Check all services are healthy
docker-compose -f docker-compose.prod.yml ps
```

---

## Folder Sync Setup

EasyStream includes an automatic folder sync tool to keep your development and Docker directories in sync.

### Windows Setup

#### One-Time Sync
```bash
# Navigate to project directory
cd E:\repos\easystream-main

# Run one-time sync
.\sync-to-docker-progs.bat
```

#### Continuous Sync (Watch Mode)
```bash
# Start file watcher
.\sync-to-docker-progs.bat watch

# This will continuously monitor E:\repos\easystream-main
# and sync changes to E:\docker-progs\easystream-main
```

#### Using PowerShell Directly
```powershell
# One-time sync
.\sync-to-docker-progs.ps1

# Watch mode
.\sync-to-docker-progs.ps1 -Watch

# Verbose mode
.\sync-to-docker-progs.ps1 -Watch -Verbose

# Dry run (see what would be synced)
.\sync-to-docker-progs.ps1 -DryRun
```

### What Gets Synced
- All source code files (PHP, CSS, JS, etc.)
- Configuration files
- Templates
- Database schema files
- Docker configuration

### What Gets Excluded
- `.git` directory
- `node_modules`
- `vendor` (Composer dependencies)
- Cache and temporary files
- Log files
- Uploaded media files
- Session files

---

## Database Management

### Initial Setup
The database is automatically initialized on first startup with:
1. **Main Schema** (270 tables) - Core platform
2. **Advanced Features** (40 tables) - API, analytics, monetization, etc.
3. **Default Settings** - Site configuration
4. **Default Admin User** - `admin` / `admin123`
5. **Default Categories** - 10 video categories
6. **Template Builder Components** - 7 pre-built components

### Manual Database Operations

#### Access Database CLI
```bash
# Development
docker-compose exec db mysql -u easystream -peasystream easystream

# Production
docker-compose -f docker-compose.prod.yml exec db mysql -u easystream -p easystream
```

#### Backup Database
```bash
# Create backup directory
mkdir -p backups

# Backup with compression
docker-compose exec db mysqldump -u easystream -peasystream easystream | gzip > backups/easystream-$(date +%Y%m%d-%H%M%S).sql.gz

# Backup without compression
docker-compose exec db mysqldump -u easystream -peasystream easystream > backups/easystream-$(date +%Y%m%d-%H%M%S).sql
```

#### Restore Database
```bash
# From compressed backup
gunzip -c backups/easystream-20250101-120000.sql.gz | docker-compose exec -T db mysql -u easystream -peasystream easystream

# From uncompressed backup
docker-compose exec -T db mysql -u easystream -peasystream easystream < backups/easystream-20250101-120000.sql
```

#### Reset Database
```bash
# Stop services
docker-compose down

# Remove database volume
docker volume rm easystream-main_db_data

# Start services (will re-initialize)
docker-compose up -d
```

### Database Schema Updates

#### Apply New Tables
If you have new SQL files to apply:
```bash
docker-compose exec -T db mysql -u easystream -peasystream easystream < new_schema.sql
```

#### Check Table Count
```bash
docker-compose exec db mysql -u easystream -peasystream easystream -e "SELECT COUNT(*) as table_count FROM information_schema.tables WHERE table_schema = 'easystream';"
```

#### List All Tables
```bash
docker-compose exec db mysql -u easystream -peasystream easystream -e "SHOW TABLES;"
```

---

## Troubleshooting

### Common Issues

#### 1. Database Container Won't Start
```bash
# Check logs
docker-compose logs db

# Common causes:
# - Volume mount errors (missing SQL files)
# - Port 3306 already in use
# - Insufficient memory

# Fix: Check if SQL files exist
ls -la __install/easystream.sql
ls -la __install/add_advanced_features.sql
ls -la deploy/init_settings.sql
```

#### 2. Port Already in Use
```bash
# Check what's using the port
netstat -ano | findstr :8083   # Windows
lsof -i :8083                   # Linux/Mac

# Solution: Either stop the other service or change port in docker-compose.yml
```

#### 3. PHP Container Can't Connect to Database
```bash
# Check if database is healthy
docker-compose ps

# Wait for database to be ready (may take 2-3 minutes)
docker-compose logs -f db

# Verify database connection from PHP container
docker-compose exec php php -r "new PDO('mysql:host=db;dbname=easystream', 'easystream', 'easystream'); echo 'OK\n';"
```

#### 4. Video Upload Not Working
```bash
# Check PHP upload limits
docker-compose exec php php -i | grep upload_max_filesize
docker-compose exec php php -i | grep post_max_size

# Check directory permissions
docker-compose exec php ls -la /srv/easystream/f_data/uploads

# Fix permissions
docker-compose exec php chown -R www-data:www-data /srv/easystream/f_data/uploads
```

#### 5. RTMP Streaming Not Working
```bash
# Check SRS logs
docker-compose logs srs

# Test RTMP connection
docker-compose exec srs curl http://localhost:1985/api/v1/streams

# Verify HLS output directory
docker-compose exec php ls -la /var/www/hls
```

#### 6. Sync Script Not Working
```bash
# Check PowerShell execution policy
Get-ExecutionPolicy

# If Restricted, allow scripts to run:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# Check if paths exist
Test-Path E:\repos\easystream-main
Test-Path E:\docker-progs\easystream-main
```

### Service Management

#### View All Logs
```bash
docker-compose logs -f
```

#### View Specific Service Logs
```bash
docker-compose logs -f php
docker-compose logs -f db
docker-compose logs -f caddy
docker-compose logs -f srs
```

#### Restart Specific Service
```bash
docker-compose restart php
docker-compose restart caddy
```

#### Rebuild Service
```bash
docker-compose up -d --build php
```

#### Check Service Health
```bash
docker-compose ps
docker-compose top
```

### Performance Issues

#### Check Resource Usage
```bash
docker stats
```

#### Optimize Database
```bash
docker-compose exec db mysql -u easystream -peasystream easystream -e "OPTIMIZE TABLE db_videofiles, db_accountuser, db_sessions;"
```

#### Clear Cache
```bash
docker-compose exec php rm -rf /srv/easystream/f_data/cache/*
docker-compose exec redis redis-cli FLUSHALL
```

---

## Security Checklist

### Pre-Production Checklist

- [ ] **Changed default admin password** (`admin123` → strong password)
- [ ] **Generated secure API keys** (not using defaults)
- [ ] **Generated secure JWT secret** (not using defaults)
- [ ] **Generated secure encryption key** (not using defaults)
- [ ] **Changed database password** (not using `easystream`)
- [ ] **Set up SSL/TLS certificates** (HTTPS enabled)
- [ ] **Configured firewall rules** (only necessary ports exposed)
- [ ] **Set up database backups** (automated daily backups)
- [ ] **Configured email server** (for notifications)
- [ ] **Set up monitoring** (health checks, alerts)
- [ ] **Reviewed file permissions** (proper ownership)
- [ ] **Enabled rate limiting** (API and login protection)
- [ ] **Configured CORS properly** (only allow trusted domains)
- [ ] **Set secure session cookies** (httpOnly, secure, sameSite)
- [ ] **Disabled debug mode** (`DEBUG=false`)
- [ ] **Set up log rotation** (prevent disk fill)
- [ ] **Configured Redis password** (if exposed)
- [ ] **Reviewed .env file** (no defaults in production)
- [ ] **Set up CDN** (for static assets)
- [ ] **Configured S3/object storage** (for user uploads)

### File Permissions (Linux/Mac)
```bash
# Set proper ownership
chown -R www-data:www-data /srv/easystream

# Set secure permissions
chmod 755 /srv/easystream
chmod 644 /srv/easystream/.env
chmod 600 /srv/easystream/secrets/*
chmod 755 /srv/easystream/f_data/uploads
chmod 755 /srv/easystream/f_data/cache
```

### Network Security
```bash
# Only expose necessary ports to public
# In production docker-compose.yml:
# - Database: 127.0.0.1:3306 (localhost only)
# - Redis: 127.0.0.1:6379 (localhost only)
# - HTTP: 80 (public)
# - HTTPS: 443 (public)
# - RTMP: 1935 (public, if needed)
```

---

## Maintenance Tasks

### Daily
- Monitor application logs
- Check disk space usage
- Review error logs

### Weekly
- Backup database
- Review security logs
- Check service health

### Monthly
- Update Docker images
- Review and optimize database
- Test backup restoration
- Security audit

### Backup Strategy
```bash
# Create automated backup script
cat > backup.sh << 'EOF'
#!/bin/bash
DATE=$(date +%Y%m%d-%H%M%S)
BACKUP_DIR="/backups/easystream"
mkdir -p $BACKUP_DIR

# Database backup
docker-compose exec -T db mysqldump -u easystream -peasystream easystream | gzip > $BACKUP_DIR/db-$DATE.sql.gz

# Files backup (user uploads)
tar czf $BACKUP_DIR/uploads-$DATE.tar.gz /var/lib/easystream/uploads

# Cleanup old backups (keep last 30 days)
find $BACKUP_DIR -type f -mtime +30 -delete

echo "Backup completed: $DATE"
EOF

chmod +x backup.sh

# Add to crontab (daily at 2 AM)
# 0 2 * * * /path/to/backup.sh >> /var/log/easystream-backup.log 2>&1
```

---

## Additional Resources

- **Docker Documentation**: https://docs.docker.com/
- **Caddy Web Server**: https://caddyserver.com/docs/
- **SRS Streaming Server**: https://github.com/ossrs/srs
- **MariaDB**: https://mariadb.org/documentation/
- **Redis**: https://redis.io/documentation

---

## Support

For issues, questions, or contributions:
- Check the troubleshooting section above
- Review application logs
- Check Docker container health
- Consult the main README.md file

---

**Last Updated**: 2025-10-25
**Version**: 2.0