PyGuardian/DOCKER_DEPLOYMENT.md

🐳 PyGuardian Docker Deployment Guide

Complete containerized deployment solution for PyGuardian v2.1.0 enterprise security system.

🚀 Quick Start

One-Command Deployment

# Standalone deployment (recommended for single server)
./deploy-docker.sh standalone

# Production cluster with 3 agents
./deploy-docker.sh cluster --scale 3 --monitoring

# Development environment
./deploy-docker.sh development

Using Makefile (Advanced)

# Setup environment and start production
make -f Makefile.docker setup-env
make -f Makefile.docker prod-up

# Development environment
make -f Makefile.docker dev-up

# Check status
make -f Makefile.docker status

📋 Prerequisites

System Requirements

• Docker: 20.10+
• Docker Compose: 2.0+
• Memory: 2GB+ RAM
• Disk: 10GB+ available space
• OS: Linux (Ubuntu 20.04+, CentOS 8+, etc.)

Install Docker

# Ubuntu/Debian
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER

# Enable and start
sudo systemctl enable docker
sudo systemctl start docker

🏗️ Architecture

Container Images

Image	Purpose	Size	Target
pyguardian:controller	Cluster controller	~200MB	Production
pyguardian:agent	Security agent	~180MB	Production
pyguardian:standalone	All-in-one	~220MB	Single server
pyguardian:development	Dev tools	~350MB	Development

Network Architecture

┌─────────────────────────────────────────────────────────────┐
│                    Host Network                              │
│  ┌─────────────────┐  ┌─────────────────┐  ┌──────────────┐ │
│  │   Controller    │  │     Agent 1     │  │   Agent 2    │ │
│  │   Port: 8443    │  │  (monitoring)   │  │ (monitoring) │ │
│  │                 │◄─┤                 │◄─┤              │ │
│  └─────────────────┘  └─────────────────┘  └──────────────┘ │
└─────────────────────────────────────────────────────────────┘

⚙️ Configuration

Environment Variables

Copy and customize the environment file:

cp .env.docker .env
nano .env

Essential Variables

# Telegram integration
TELEGRAM_BOT_TOKEN=1234567890:ABCDEFGHIJKLMNOPQRSTUVWXYZ

# Security secrets (generate with: openssl rand -hex 32)
CLUSTER_SECRET=your_32_byte_hex_secret
JWT_SECRET=your_32_byte_jwt_secret

# Logging
LOG_LEVEL=INFO  # DEBUG, INFO, WARNING, ERROR

Advanced Configuration

# Performance tuning
CONTAINER_MEMORY_LIMIT=512m
CONTAINER_CPU_LIMIT=1.0

# Monitoring
PROMETHEUS_ENABLED=true
HEALTH_CHECK_INTERVAL=30

# Security
FIREWALL_ENABLED=true
IDS_ENABLED=true

🏭 Deployment Modes

1. Standalone Mode

Best for: Single server deployments, testing, small environments

# Quick start
./deploy-docker.sh standalone

# With custom config
./deploy-docker.sh standalone --env .env.custom

# Manual Docker command
docker run -d \
  --name pyguardian-standalone \
  --privileged \
  --network host \
  --restart unless-stopped \
  --env-file .env \
  -v /opt/pyguardian/data:/opt/pyguardian/data \
  -v /var/log:/var/log:ro \
  pyguardian:standalone

Features:

• ✅ Complete security monitoring
• ✅ Telegram notifications
• ✅ Web API (port 8443)
• ✅ Firewall management
• ✅ Intrusion detection

2. Cluster Mode

Best for: Multi-server environments, high availability

# Controller + 2 agents
./deploy-docker.sh cluster --scale 2

# With monitoring stack
./deploy-docker.sh cluster --scale 3 --monitoring

# Using docker-compose directly
docker-compose -f docker-compose.prod.yml up -d

Architecture:

Controller (Server 1) ←── Agent (Server 2) 
                     ←── Agent (Server 3)
                     ←── Agent (Server N)

Features:

• ✅ Centralized management
• ✅ JWT-based authentication
• ✅ Real-time agent communication
• ✅ Scalable to 100+ agents
• ✅ Health monitoring

3. Production Mode

Best for: Enterprise deployments, 24/7 operations

# Full production stack
./deploy-docker.sh production --monitoring

# Manual with all features
make -f Makefile.docker prod-up monitoring-up

Includes:

• 🔒 Enhanced security: SSL/TLS, secrets management
• 📊 Monitoring: Prometheus, health checks
• 💾 Data persistence: Volume management
• 🔄 Auto-restart: unless-stopped policy
• 📝 Logging: Structured logs, rotation

4. Development Mode

Best for: Development, testing, debugging

# Development environment
./deploy-docker.sh development

# Access development tools
make -f Makefile.docker dev-shell

Features:

• 🔧 Hot reload: Code changes reflected live
• 🧪 Testing tools: pytest, coverage, linting
• 📔 Jupyter Lab: http://localhost:8888
• 🐛 Debug mode: Verbose logging
• 🗄️ Test database: PostgreSQL + Redis

🔧 Management Commands

Using deploy-docker.sh

# Deployment
./deploy-docker.sh standalone          # Single container
./deploy-docker.sh cluster --scale 3   # 3-agent cluster
./deploy-docker.sh production          # Production ready

# Build options
./deploy-docker.sh standalone --build --no-cache

# Custom environment
./deploy-docker.sh cluster --env .env.production

Using Makefile

# Environment setup
make -f Makefile.docker setup-env     # Create .env file
make -f Makefile.docker generate-secrets  # Generate secure secrets

# Production operations
make -f Makefile.docker prod-up       # Start production
make -f Makefile.docker prod-down     # Stop production  
make -f Makefile.docker prod-restart  # Restart production
make -f Makefile.docker prod-logs     # View logs

# Development operations  
make -f Makefile.docker dev-up        # Start development
make -f Makefile.docker dev-shell     # Access container shell
make -f Makefile.docker dev-logs      # View dev logs

# Cluster management
make -f Makefile.docker cluster-up    # Start cluster
make -f Makefile.docker cluster-scale AGENTS=5  # Scale to 5 agents
make -f Makefile.docker cluster-status # Check cluster

# Maintenance
make -f Makefile.docker backup        # Create data backup
make -f Makefile.docker clean         # Clean containers
make -f Makefile.docker health        # Health check

📊 Monitoring & Logs

Health Checks

# Container health
docker ps --format "table {{.Names}}\t{{.Status}}"

# Application health
curl -k https://localhost:8443/health

# Detailed status
make -f Makefile.docker health

Log Management

# Real-time logs
docker logs -f pyguardian-controller
docker logs -f pyguardian-agent-1

# Production logs
make -f Makefile.docker prod-logs

# Development logs
make -f Makefile.docker dev-logs

# Log analysis
docker exec pyguardian-controller tail -f /opt/pyguardian/logs/pyguardian.log

Prometheus Monitoring

When monitoring is enabled:

# Start with monitoring
./deploy-docker.sh production --monitoring

# Access Prometheus
open http://localhost:9090

# Key metrics
- pyguardian_agents_connected
- pyguardian_security_incidents  
- pyguardian_system_cpu_percent
- pyguardian_system_memory_percent

🗄️ Data Management

Volume Structure

/opt/pyguardian/
├── controller/
│   ├── data/          # SQLite database, auth keys
│   ├── logs/          # Application logs
│   └── config/        # Configuration files
├── agent1/
│   ├── data/          # Agent data, cache
│   ├── logs/          # Agent logs  
│   └── config/        # Agent configuration
└── backups/           # Automated backups

Backup & Restore

# Create backup
make -f Makefile.docker backup

# Restore from backup
make -f Makefile.docker restore BACKUP=pyguardian_backup_20231125_143022.tar.gz

# Manual backup
docker run --rm \
  -v pyguardian_controller_data:/source \
  -v $(pwd)/backups:/backup \
  alpine tar czf /backup/manual_backup.tar.gz -C /source .

Database Access

# SQLite database access
docker exec -it pyguardian-controller \
  sqlite3 /opt/pyguardian/data/pyguardian.db

# View agent registrations
docker exec pyguardian-controller \
  python3 -c "
import sqlite3
conn = sqlite3.connect('/opt/pyguardian/data/pyguardian.db')
cursor = conn.cursor()
cursor.execute('SELECT * FROM agent_auth')
print(cursor.fetchall())
"

🔐 Security

SSL/TLS Configuration

# Generate SSL certificates
mkdir -p ssl
openssl req -x509 -newkey rsa:4096 -keyout ssl/key.pem -out ssl/cert.pem -days 365 -nodes

# Update environment
echo "SSL_ENABLED=true" >> .env
echo "SSL_CERT_PATH=/opt/pyguardian/ssl/cert.pem" >> .env
echo "SSL_KEY_PATH=/opt/pyguardian/ssl/key.pem" >> .env

Secrets Management

# Generate secure secrets
make -f Makefile.docker generate-secrets

# Docker secrets (for Swarm)
echo "your_secret" | docker secret create cluster_secret -
echo "your_jwt_secret" | docker secret create jwt_secret -

Firewall Integration

# Container needs privileged mode for iptables
--privileged

# Custom iptables rules
docker exec pyguardian-controller \
  sudo iptables -A INPUT -p tcp --dport 22 -j DROP

🚨 Troubleshooting

Common Issues

1. Permission Denied

# Fix data directory permissions
sudo chown -R $USER:$USER /opt/pyguardian
chmod -R 755 /opt/pyguardian

2. Port Already in Use

# Check what's using port 8443
sudo lsof -i :8443
sudo netstat -tulpn | grep 8443

# Kill conflicting process
sudo kill -9 <PID>

3. Container Health Check Failed

# Check container logs
docker logs pyguardian-controller

# Manual health check
docker exec pyguardian-controller python3 -c "import requests; print(requests.get('http://localhost:8443/health').text)"

# Restart unhealthy container
docker restart pyguardian-controller

4. Agent Connection Issues

# Check network connectivity
docker exec pyguardian-agent-1 curl -k https://controller:8443/health

# Verify cluster secret
docker exec pyguardian-controller env | grep CLUSTER_SECRET
docker exec pyguardian-agent-1 env | grep CLUSTER_SECRET

# Check agent logs
docker logs pyguardian-agent-1 | grep -i error

Debug Commands

# Container resource usage
docker stats

# Inspect container configuration
docker inspect pyguardian-controller

# Network debugging
docker exec pyguardian-controller ip addr show
docker exec pyguardian-controller ss -tulpn

# System debugging inside container
docker exec -it pyguardian-controller bash
ps aux
netstat -tulpn
tail -f /opt/pyguardian/logs/pyguardian.log

Performance Tuning

# Increase memory limit
echo "CONTAINER_MEMORY_LIMIT=1g" >> .env

# Optimize for production
echo "PYGUARDIAN_LOG_LEVEL=WARNING" >> .env
echo "WORKER_PROCESSES=4" >> .env

📚 Advanced Usage

Multi-Host Cluster

For deploying across multiple servers:

# Server 1 (Controller)
./deploy-docker.sh production
echo "CONTROLLER_HOST=$(hostname -I | awk '{print $1}')" >> .env

# Server 2+ (Agents)  
export CONTROLLER_HOST=<controller_ip>
./deploy-docker.sh agent --env .env.agent

CI/CD Integration

# Build for CI
docker build -f deployment/docker/Dockerfile.optimized --target controller .

# Test deployment
make -f Makefile.docker test-build

# Automated deployment
./deploy-docker.sh production --build --no-cache

Custom Images

# Build custom controller
docker build -f deployment/docker/Dockerfile.optimized \
  --target controller \
  --build-arg PYGUARDIAN_VERSION=2.1.0-custom \
  -t pyguardian:controller-custom .

# Use custom image
sed -i 's/pyguardian:controller/pyguardian:controller-custom/g' docker-compose.prod.yml

📞 Support

• Documentation: /documentation/
• Issues: GitHub Issues
• Logs: Check /opt/pyguardian/*/logs/
• Health: https://localhost:8443/health

🎯 Quick Reference

Task	Command
Quick Start	./deploy-docker.sh standalone
Production	./deploy-docker.sh production --monitoring
Development	./deploy-docker.sh development
Scale Cluster	make cluster-scale AGENTS=5
View Logs	make prod-logs
Health Check	make health
Backup	make backup
Clean Up	make clean

---

🚀 PyGuardian v2.1.0 - Enterprise Security Made Simple!