shell/docker-deployment/README.md

# 🐳 Docker Deployment Management

This directory contains scripts and tools for managing Docker stack deployments across multiple servers in a coordinated, automated fashion.

## 📋 Overview

The Docker deployment system provides centralized management for deploying specific Docker stacks to designated servers while maintaining a monorepo structure. It integrates with the existing environment backup system to ensure proper configuration management.

## 🚀 Available Scripts

### Core Deployment Scripts

- **`docker-deployment-manager.sh`**: Main orchestrator for managing Docker stack deployments across multiple servers
- **`deployment-env-integration.sh`**: Integration bridge between the deployment manager and existing environment backup system
- **`stack-assignment-helper.sh`**: Intelligent stack analysis and server assignment recommendations

## 🎯 Key Features

### Multi-Server Deployment

- **Centralized Control**: Manage deployments across multiple servers from a single interface
- **Stack-to-Server Mapping**: Intelligent assignment of Docker stacks to appropriate servers
- **Configuration Synchronization**: Automated sync of environment files and configurations

### Environment Integration

- **Backup Integration**: Seamless integration with existing backup-env-files system
- **Configuration Management**: Automated management of environment variables and secrets
- **Deployment Verification**: Post-deployment validation and health checks

### Intelligent Stack Management

- **Pattern Recognition**: Automatic categorization of stacks based on content analysis
- **Resource Optimization**: Server assignment based on resource requirements and capabilities
- **Conflict Detection**: Prevention of conflicting stack deployments

## 📊 System Architecture

```
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Central Repo  │──▶│ Deployment Mgr   │──▶│  Target Servers │
│   (Monorepo)    │    │                  │    │                 │
└─────────────────┘    └──────────────────┘    └─────────────────┘
         │                       │                       │
         ▼                       ▼                       ▼
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│ Stack Analysis  │    │ Env Integration  │    │ Health Checks   │
│    Helper       │    │                  │    │                 │
└─────────────────┘    └──────────────────┘    └─────────────────┘
```

## 🛠️ Usage Examples

### Basic Deployment

```bash
# Deploy a specific stack to assigned server
./docker-deployment-manager.sh deploy plex

# Deploy multiple stacks
./docker-deployment-manager.sh deploy plex immich nextcloud

# Deploy to specific server
./docker-deployment-manager.sh deploy --server europa plex
```

### Stack Analysis and Assignment

```bash
# Analyze all stacks and suggest assignments
./stack-assignment-helper.sh analyze

# Get recommendations for a specific stack
./stack-assignment-helper.sh recommend plex

# Show current stack assignments
./stack-assignment-helper.sh list-assignments
```

### Environment Integration

```bash
# Sync environment files before deployment
./deployment-env-integration.sh sync

# Deploy with automatic env backup
./deployment-env-integration.sh deploy-with-backup plex

# Validate environment configuration
./deployment-env-integration.sh validate
```

## ⚙️ Configuration

### Server Configuration

The deployment system uses hostname-based server configuration:

- **europa** - Media server (Plex, Immich, media-related stacks)
- **io** - Download/acquisition server (download tools, VPN services)
- **racknerd** - Backup server (backup services, monitoring)

### Stack Categories

#### Media Server Stacks

- Plex, Jellyfin, Emby
- Immich, PhotoPrism
- Nextcloud, file sharing services

#### Download/Acquisition Stacks

- qBittorrent, Transmission
- Sonarr, Radarr, Lidarr
- VPN services, proxy tools

#### Backup & Monitoring Stacks

- Backup services
- Monitoring tools (Prometheus, Grafana)
- Notification services

#### Multi-Server Stacks

- Traefik (reverse proxy)
- Watchtower (auto-updates)
- Portainer (management)

## 🔧 Integration Points

### Environment Backup System

- Automatic backup of environment files before deployment
- Restoration capabilities for rollback scenarios
- Configuration validation and consistency checks

### Monitoring Integration

- Deployment status tracking
- Health check integration
- Alert system for failed deployments

### Documentation Integration

- Links to [Docker Stack Deployment Strategy](../docs/docker-stack-deployment-strategy.md)
- Integration with [Production Deployment Guide](../docs/production-deployment-guide.md)

## 🧪 Validation and Testing

### Pre-Deployment Checks

- Environment file validation
- Docker stack syntax verification
- Server resource availability

### Post-Deployment Validation

- Container health status
- Service accessibility checks
- Integration point verification

### Rollback Capabilities

- Automatic rollback on deployment failure
- Manual rollback commands
- Configuration restoration

## 📝 Logging and Monitoring

- **Deployment Logs**: Detailed logs for all deployment activities
- **Error Tracking**: Comprehensive error logging and reporting
- **Performance Metrics**: Deployment time and resource usage tracking

## 🔗 Related Documentation

- [Docker Stack Deployment Strategy](../docs/docker-stack-deployment-strategy.md) - Comprehensive deployment strategy
- [Production Deployment Guide](../docs/production-deployment-guide.md) - Production deployment procedures
- [Environment Backup System](../docs/env-backup-system.md) - Environment backup integration
- [Crontab Management](../crontab/README.md) - Automated scheduling integration

## 🎯 Future Enhancements

- **Blue-Green Deployments**: Zero-downtime deployment strategies
- **Canary Releases**: Gradual rollout capabilities
- **Auto-Scaling**: Dynamic resource allocation
- **Multi-Cloud Support**: Cross-cloud deployment capabilities

---

*For detailed usage instructions and advanced configuration options, see the individual script documentation and related guides.*