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

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

2. One-Click Deployment

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

# After deployment completes, visit:
# http://localhost:3002

That's it! 🎉

📚 Deployment Modes

Basic Mode (Default)

Use Case: Private network file transfer, personal use, testing environment

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

Tip: If your network uses carrier-grade NAT or proxy and is mis-detected as public, append --mode private to skip public-IP probing and force basic mode. When the detected LAN IP is not the one you expect, append --local-ip 192.168.x.x to override it explicitly.

🔧 Advanced Configuration

Custom Ports

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

Build-Time Proxy (optional)

Set the following variables in .env (or export them before running deploy.sh) when the build needs to go through a proxy. The configuration generator now preserves these fields on subsequent runs.

HTTP_PROXY=http://your-proxy:7890
HTTPS_PROXY=http://your-proxy:7890
NO_PROXY=localhost,127.0.0.1,backend,frontend,redis,coturn

docker-compose passes these values as build args; the Dockerfiles expose them as environment variables so npm/pnpm automatically reuse the proxy. Leave them blank if you don't need a proxy.

Enable Specific Services

# 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

🌐 Access Methods

Local Access

• Frontend App: http://localhost:3002
• 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:3002
   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

docker-compose ps

View Service Logs

# 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

# Restart all services
docker-compose restart

# Restart specific service
docker-compose restart backend

Stop Services

# Stop services but keep data
docker-compose stop

# Stop services and remove containers
docker-compose down

Complete Cleanup

# 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: 3002, 3001

Solution:

# First try cleaning previous containers
bash deploy.sh --clean   # or docker-compose down

# If the port is still occupied, locate the process
sudo ss -tulpn | grep :3002
sudo kill -9 <PID>

# Finally, adjust the exposed ports in .env if necessary
vim .env   # Update FRONTEND_PORT / BACKEND_PORT

2. Insufficient Memory

Symptom: Containers fail to start or restart frequently

Solution:

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

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

# 1. Check service status
docker-compose ps

# 2. Check health status
curl http://localhost:3001/health
curl http://localhost:3002/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:

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

# 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:3002/api/health      # Frontend check

Performance Monitoring

# 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 deploy.sh --with-nginx

2. Configure Resource Limits:

# Add to docker-compose.yml
services:
  backend:
    deploy:
      resources:
        limits:
          memory: 256M
        reservations:
          memory: 128M

3. Enable Log Rotation:

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

networks:
  privydrop-network:
    driver: bridge
    ipam:
      config:
        - subnet: 172.20.0.0/16

2. Enable HTTP/2:

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

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

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

🔄 Updates and Maintenance

Update Application

# Pull latest code
git pull origin main

# Redeploy
bash deploy.sh

Data Backup

# 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

# 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 deploy.sh --help

Online Resources

• Project Homepage
• Live Demo
• Issue Reporting

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!