easystream-main/DOCKER_DEPLOYMENT_GUIDE.md

EasyStream - Complete Docker Deployment Guide

Table of Contents

• Prerequisites
• Quick Start (Development)
• Production Deployment
• Folder Sync Setup
• Database Management
• Troubleshooting
• 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

docker --version
docker-compose --version

---

Quick Start (Development)

1. Clone or Navigate to Project

cd E:\repos\easystream-main

2. Configure Environment

# Copy the example environment file
copy .env.example .env

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

3. Start All Services

# 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.

# 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

# 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

copy .env.production .env

1.2 Generate Secure Secrets

Create the secrets directory:

mkdir secrets

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

Method A: Using OpenSSL (Linux/Mac)

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)

.\generate-secrets.ps1

Method C: Using Docker

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:

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/:

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

# 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

# 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

# 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

# Navigate to project directory
cd E:\repos\easystream-main

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

Continuous Sync (Watch Mode)

# 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

# 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

# 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

# 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

# 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

# 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:

docker-compose exec -T db mysql -u easystream -peasystream easystream < new_schema.sql

Check Table Count

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

docker-compose exec db mysql -u easystream -peasystream easystream -e "SHOW TABLES;"

---

Troubleshooting

Common Issues

1. Database Container Won't Start

# 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

# 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

# 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

# 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

# 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

# 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

docker-compose logs -f

View Specific Service Logs

docker-compose logs -f php
docker-compose logs -f db
docker-compose logs -f caddy
docker-compose logs -f srs

Restart Specific Service

docker-compose restart php
docker-compose restart caddy

Rebuild Service

docker-compose up -d --build php

Check Service Health

docker-compose ps
docker-compose top

Performance Issues

Check Resource Usage

docker stats

Optimize Database

docker-compose exec db mysql -u easystream -peasystream easystream -e "OPTIMIZE TABLE db_videofiles, db_accountuser, db_sessions;"

Clear Cache

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)

# 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

# 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

# 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