# Docker Stack Deployment Strategy

## Overview

This document outlines a deployment strategy for managing Docker stacks across multiple servers while maintaining the monorepo structure. The goal is to deploy only specific stacks to their designated servers while keeping centralized configuration management.

## Current Infrastructure Analysis

Based on your existing system, you have:

- **Monorepo Structure**: All Docker stacks in `~/docker/*` directories
- **Environment Backup System**: Automated backup of `.env` files to Gitea
- **Multi-Server Crontab Management**: Different cron configurations per server
- **Existing Servers**:
  - `europa` (based on crontab-europa.txt)
  - `io` (download/acquisition server)
  - `racknerd` (backup server)

## Server-Specific Stack Mapping

### Current Server Assignments (based on analysis)

| Server       | Purpose             | Server-Specific Stacks                                                                      |
| ------------ | ------------------- | ------------------------------------------------------------------------------------------- |
| **europa**   | Media/Services      | Plex, Immich, Caddy, Nginx Proxy Manager, Filebrowser, Paperless-NG, Docmost, Wiki, Hoarder |
| **io**       | Download/Processing | Media pipeline, Metube, Pinchflat, PDF tools, N8N, Golinks                                  |
| **racknerd** | Backup/Utility      | Uptime-Kuma, Vaultwarden, Authentik, Gatus, NTFY, Adguard, Database, etc.                   |

### Multi-Server Stacks (deployed to ALL servers)

| Stack      | Purpose                      | Why on All Servers                |
| ---------- | ---------------------------- | --------------------------------- |
| **dozzle** | Docker log viewer            | Monitor containers on each server |
| **dockge** | Docker compose management    | Manage stacks on each server      |
| **diun**   | Docker image update notifier | Track updates per server          |

### Stack Categories

1. **Server-Specific**: Deployed only to designated servers
2. **Multi-Server**: Deployed to ALL servers (monitoring/management tools)
3. **Optional Multi-Server**: Can be deployed to specific servers or all (like NTFY)

## Deployment Strategies

### Strategy 1: Metadata-Driven Deployment (Recommended)

Create deployment metadata files that specify which stacks belong on which servers.

#### Implementation

1. **Stack Metadata Files**

   ```yaml
   # ~/docker/plex/.deploy.yml
   servers:
     - europa
   dependencies:
     - traefik
   priority: high
   health_check: "curl -f http://localhost:32400/web || exit 1"
   ```

2. **Server Configuration**

   ```yaml
   # ~/.docker-deployment/servers.yml
   servers:
     europa:
       role: media-server
       stacks:
         - plex
         - jellyfin
         - traefik
       resources:
         cpu_limit: "4"
         memory_limit: "8G"

     io:
       role: download-server
       stacks:
         - radarr
         - sonarr
         - sabnzbd
         - qbittorrent
       resources:
         cpu_limit: "2"
         memory_limit: "4G"

     racknerd:
       role: backup-server
       stacks:
         - grafana
         - prometheus
         - uptime-kuma
       resources:
         cpu_limit: "1"
         memory_limit: "2G"
   ```

#### Deployment Script

Create a smart deployment script that:

- Reads metadata to determine target servers
- Syncs only relevant stacks to each server
- Handles dependencies automatically
- Manages environment files securely

### Strategy 2: Branch-Based Deployment

Create server-specific branches that contain only the relevant stacks for each server.

#### Implementation

1. **Main Branch**: Contains all stacks
2. **Server Branches**:
   - `deploy/europa` - Contains only europa stacks
   - `deploy/io` - Contains only io stacks
   - `deploy/racknerd` - Contains only racknerd stacks

#### Workflow

```bash
# Automated branch creation
git checkout main
git subtree push --prefix=docker/plex deploy/europa
git subtree push --prefix=docker/radarr deploy/io
```

### Strategy 3: Selective Sync with Configuration

Use your existing infrastructure with selective synchronization.

#### Implementation

Extend your current backup system to include deployment management:

1. **Deployment Configuration**
2. **Selective Sync Script**
3. **Integration with Existing Crontab System**

## Recommended Solution: Enhanced Deployment Manager

Let me create a deployment manager that integrates with your existing infrastructure:

### Features

1. **Server-Aware Deployment**: Knows which stacks belong where
2. **Secure Environment Sync**: Integrates with your existing `.env` backup system
3. **Dependency Management**: Handles stack dependencies automatically
4. **Health Monitoring**: Checks stack health after deployment
5. **Rollback Capability**: Can revert to previous versions
6. **Integration with Existing Tools**: Works with your crontab and backup systems

### Configuration Structure

```
~/.docker-deployment/
├── config.yml              # Global deployment configuration
├── servers/
│   ├── europa.yml          # Europa-specific configuration
│   ├── io.yml              # IO-specific configuration
│   └── racknerd.yml        # Racknerd-specific configuration
├── stacks/
│   ├── plex.yml            # Plex deployment metadata
│   ├── radarr.yml          # Radarr deployment metadata
│   └── ...
└── logs/
    └── deployment.log
```

## Integration Points

### 1. Environment File Management

- Leverage your existing `backup-env-files.sh` system
- Add server-specific filtering
- Secure transfer of environment files

### 2. Crontab Integration

- Extend your multi-system crontab management
- Add deployment automation to existing cron jobs

### 3. Monitoring Integration

- Use your existing logging infrastructure
- Integrate with notification systems (you already use ntfy)

## Benefits

1. **Maintains Centralized Management**: All configurations in one repo
2. **Server-Specific Deployment**: Only relevant stacks on each server
3. **Security**: Environment files handled securely
4. **Automation**: Integrates with existing cron infrastructure
5. **Monitoring**: Health checks and rollback capabilities
6. **Simplicity**: Clear mapping of what goes where

## Next Steps

1. **Define Stack Assignments**: Document which stacks run on which servers
2. **Create Deployment Metadata**: Add `.deploy.yml` files to each stack
3. **Implement Deployment Manager**: Create the deployment script
4. **Test on Non-Production**: Validate the system before production deployment
5. **Integrate with Existing Infrastructure**: Connect to crontab and backup systems

Would you like me to proceed with implementing the deployment manager script and configuration files?
