PrivyDrop/docs/DEPLOYMENT_docker.md

# PrivyDrop Docker Deployment Guide

This guide provides a one-click Docker deployment solution for PrivyDrop, supporting both private and public network environments without complex manual configuration.

## 🎯 Deployment Advantages

Compared to traditional deployment methods, Docker deployment offers the following advantages:

| Comparison | Traditional Deployment | Docker Deployment |
|-----------|----------------------|------------------|
| **Deploy Time** | 30-60 minutes | 5 minutes |
| **Technical Requirements** | Linux ops experience | Basic Docker knowledge |
| **Environment Requirements** | Public IP + Domain | Works on private networks |
| **Configuration Complexity** | 10+ manual steps | One-click auto configuration |
| **Success Rate** | ~70% | >95% |
| **Maintenance Difficulty** | Manual multi-service management | Automatic container management |

## 📋 System Requirements

### Minimum Configuration
- **CPU**: 1 core
- **Memory**: 512MB
- **Disk**: 2GB available space
- **Network**: Any network environment (private/public)

### Recommended Configuration
- **CPU**: 2+ cores
- **Memory**: 1GB+ 
- **Disk**: 5GB+ available space
- **Network**: 100Mbps+

### Software Dependencies
- Docker 20.10+
- Docker Compose 2.0+ (or docker-compose 1.27+)
- curl (for health checks)
- openssl (for SSL certificate generation)

## 🚀 Quick Start

### 1. Get the Code

```bash
# Clone the project
git clone https://github.com/david-bai00/PrivyDrop.git
cd PrivyDrop
```

### 2. One-Click Deployment

```bash
# Basic deployment (recommended for beginners)
bash deploy.sh

# After deployment completes, visit:
# http://localhost:3000
```

That's it! 🎉

## 📚 Deployment Modes

### Basic Mode (Default)
**Use Case**: Private network file transfer, personal use, testing environment

```bash
bash deploy.sh
```

**Features**:
- ✅ HTTP access
- ✅ Private network P2P transfer
- ✅ Uses public STUN servers  
- ✅ Zero configuration startup

### Public Mode
**Use Case**: Servers with public IP but no domain

```bash
bash deploy.sh --mode public --with-turn
```

**Features**:
- ✅ HTTP access
- ✅ Built-in TURN server
- ✅ Supports complex network environments
- ✅ Automatic NAT traversal configuration

### Full Mode
**Use Case**: Production environment, public servers with domain

```bash
bash deploy.sh --domain your-domain.com --mode full --with-nginx --with-turn
```

**Features**:
- ✅ HTTPS secure access
- ✅ Self-signed SSL certificates
- ✅ Nginx reverse proxy
- ✅ Built-in TURN server
- ✅ Complete production environment configuration

## 🔧 Advanced Configuration

### Custom Ports

```bash
# Modify .env file
FRONTEND_PORT=8080
BACKEND_PORT=8081
HTTP_PORT=8000
```

### Enable Specific Services

```bash
# Enable only Nginx reverse proxy
bash deploy.sh --with-nginx

# Enable only TURN server
bash deploy.sh --with-turn

# Enable all services
bash deploy.sh --with-nginx --with-turn
```

### Development Mode Deployment

```bash
# Enable development mode (supports hot code reloading)
bash deploy.sh --dev
```

## 🌐 Access Methods

### Local Access
- **Frontend App**: http://localhost:3000
- **API Interface**: http://localhost:3001
- **Health Check**: http://localhost:3001/health

### LAN Access
After deployment, the script automatically displays LAN access addresses:
```
🌐 LAN Access:
   Frontend App: http://192.168.1.100:3000
   Backend API: http://192.168.1.100:3001
```

### HTTPS Access (if enabled)
- **Secure Access**: https://localhost
- **Certificate Location**: `docker/ssl/ca-cert.pem`

**Note**: When first accessing HTTPS, the browser will warn about an untrusted certificate. This is normal. You can:
1. Click "Advanced" → "Continue to site"
2. Or import the `docker/ssl/ca-cert.pem` certificate into your browser

## 🔍 Management Commands

### View Service Status
```bash
docker-compose ps
```

### View Service Logs
```bash
# View all service logs
docker-compose logs -f

# View specific service logs
docker-compose logs -f backend
docker-compose logs -f frontend
docker-compose logs -f redis
```

### Restart Services
```bash
# Restart all services
docker-compose restart

# Restart specific service
docker-compose restart backend
```

### Stop Services
```bash
# Stop services but keep data
docker-compose stop

# Stop services and remove containers
docker-compose down
```

### Complete Cleanup
```bash
# Clean all containers, images and data
bash deploy.sh --clean
```

## 🛠️ Troubleshooting

### Common Issues

#### 1. Port Already in Use
**Symptom**: Deployment shows port occupation warning
```
⚠️  The following ports are already in use: 3000, 3001
```

**Solution**:
```bash
# Method 1: Modify port configuration
echo "FRONTEND_PORT=8080" >> .env
echo "BACKEND_PORT=8081" >> .env

# Method 2: Stop programs using the ports
sudo ss -tulpn | grep :3000
sudo kill -9 <PID>
```

#### 2. Insufficient Memory
**Symptom**: Containers fail to start or restart frequently

**Solution**:
```bash
# Check memory usage
free -h

# Add swap space (temporary solution)
sudo fallocate -l 1G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
```

#### 3. Docker Permission Issues
**Symptom**: Permission denied errors

**Solution**:
```bash
# Add user to docker group
sudo usermod -aG docker $USER

# Re-login or refresh group permissions
newgrp docker
```

#### 4. Service Inaccessible
**Symptom**: Browser cannot open pages

**Solution**:
```bash
# 1. Check service status
docker-compose ps

# 2. Check health status
curl http://localhost:3001/health
curl http://localhost:3000/api/health

# 3. View detailed logs
docker-compose logs -f

# 4. Check firewall
sudo ufw status
```

#### 5. WebRTC Connection Failure
**Symptom**: Cannot establish P2P connections

**Solution**:
```bash
# Enable TURN server
bash deploy.sh --with-turn

# Check network connectivity
curl -I http://localhost:3001/api/get_room
```

### Health Checks

The project provides comprehensive health check functionality:

```bash
# Run health check tests
bash test-health-apis.sh

# Manual service checks
curl http://localhost:3001/health          # Backend basic check
curl http://localhost:3001/health/detailed # Backend detailed check
curl http://localhost:3000/api/health      # Frontend check
```

### Performance Monitoring

```bash
# View container resource usage
docker stats

# View disk usage
docker system df

# Clean unused resources
docker system prune -f
```

## 📊 Performance Optimization

### Production Environment Optimization

1. **Enable Nginx Caching**:
```bash
bash deploy.sh --with-nginx
```

2. **Configure Resource Limits**:
```yaml
# Add to docker-compose.yml
services:
  backend:
    deploy:
      resources:
        limits:
          memory: 256M
        reservations:
          memory: 128M
```

3. **Enable Log Rotation**:
```bash
# Configure log size limits
echo '{"log-driver":"json-file","log-opts":{"max-size":"10m","max-file":"3"}}' | sudo tee /etc/docker/daemon.json
sudo systemctl restart docker
```

### Network Optimization

1. **Use Dedicated Network**:
```yaml
networks:
  privydrop-network:
    driver: bridge
    ipam:
      config:
        - subnet: 172.20.0.0/16
```

2. **Enable HTTP/2**:
```bash
# Auto-enabled (requires HTTPS)
bash deploy.sh --mode full --with-nginx
```

## 🔒 Security Configuration

### SSL/TLS Configuration

1. **Self-signed Certificates** (default):
   - Automatically generated and configured
   - Suitable for private networks and testing
   - Certificate location: `docker/ssl/`

2. **Let's Encrypt Certificates** (planned):
   - Automatic application and renewal
   - Suitable for production with domain names

### Network Security

1. **Firewall Configuration**:
```bash
# Ubuntu/Debian
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 3478/udp  # TURN server
```

2. **Container Network Isolation**:
   - All services run in isolated networks
   - Only necessary ports exposed
   - Internal services communicate using container names

## 📈 Monitoring and Logging

### Log Management

All service logs are centrally stored in the `logs/` directory:

```
logs/
├── nginx/          # Nginx access and error logs
├── backend/        # Backend application logs
├── frontend/       # Frontend application logs
└── coturn/         # TURN server logs
```

### Monitoring Integration (optional)

Can integrate Prometheus + Grafana monitoring stack:

```bash
# Enable monitoring (planned)
bash deploy.sh --with-monitoring
```

## 🔄 Updates and Maintenance

### Update Application

```bash
# Pull latest code
git pull origin main

# Redeploy
bash deploy.sh
```

### Data Backup

```bash
# Backup Redis data
docker-compose exec redis redis-cli BGSAVE

# Backup SSL certificates
tar -czf ssl-backup.tar.gz docker/ssl/

# Backup configuration files
cp .env .env.backup
```

### Regular Maintenance

```bash
# Clean unused images and containers
docker system prune -f

# Update base images
docker-compose pull
docker-compose up -d
```

## 🆘 Getting Help

### Command Line Help
```bash
bash deploy.sh --help
```

### Online Resources
- [Project Homepage](https://github.com/david-bai00/PrivyDrop)
- [Live Demo](https://www.privydrop.app/)
- [Issue Reporting](https://github.com/david-bai00/PrivyDrop/issues)

### Community Support
- GitHub Issues: Technical questions and bug reports
- GitHub Discussions: Usage discussions and feature suggestions

---

## 📝 Changelog

### v1.0.0 (Docker Version)
- ✅ Added Docker one-click deployment support
- ✅ Added health check APIs
- ✅ Added automatic environment detection and configuration generation
- ✅ Added multiple deployment modes
- ✅ Added comprehensive troubleshooting guide
- ✅ Support for private network deployment without public IP requirement

---

**🎉 Congratulations! You have successfully deployed PrivyDrop. Start enjoying secure, private file sharing!**