# =============================================================================
# WATCHTOWER - AUTOMATED DOCKER CONTAINER UPDATES
# =============================================================================
#
# SERVICE OVERVIEW:
# - Automatically updates Docker containers to latest versions
# - Monitors Docker Hub for image updates every 2 hours
# - Gracefully restarts containers with new images
# - Cleans up old images to save disk space
# - Provides metrics for Prometheus monitoring
#
# DISASTER RECOVERY PRIORITY: MEDIUM
# - Helpful for maintaining updated containers
# - Not critical for immediate disaster recovery
# - Can be disabled during recovery operations
#
# RECOVERY TIME OBJECTIVE (RTO): 1 hour
# RECOVERY POINT OBJECTIVE (RPO): N/A (stateless service)
#
# DEPENDENCIES:
# - Docker socket access (read-only)
# - Network connectivity to Docker Hub
# - Prometheus network for metrics
# - Sufficient disk space for image downloads
#
# SECURITY CONSIDERATIONS:
# - Read-only Docker socket access
# - No new privileges security option
# - Read-only container filesystem
# - Automatic cleanup of old images
#
# =============================================================================

services:
  watchtower:
    # CONTAINER IMAGE:
    # - containrrr/watchtower:latest: Official Watchtower image
    # - Community-maintained Docker container updater
    # - Regular updates with new features and security patches
    image: containrrr/watchtower:latest

    # CONTAINER IDENTIFICATION:
    # - WATCHTOWER: Clear identification for logs and monitoring
    # - watchtower: Internal hostname for service communication
    container_name: WATCHTOWER
    hostname: watchtower

    # PORT CONFIGURATION:
    # - 8082:8080: HTTP API for metrics (8082 to avoid conflicts)
    # - Allows Prometheus to scrape metrics endpoint
    ports:
      - "8082:8080"

    # NETWORK CONFIGURATION:
    # - prometheus-net: Connected to monitoring network
    # - Allows Prometheus to scrape metrics
    # - Isolated from other services for security
    networks:
      - prometheus-net

    # RESOURCE ALLOCATION:
    # - mem_limit: 128MB maximum (lightweight service)
    # - mem_reservation: 50MB guaranteed memory
    # - cpu_shares: 256 (low priority, background task)
    mem_limit: 128m
    mem_reservation: 50m
    cpu_shares: 256

    # SECURITY CONFIGURATION:
    # - no-new-privileges: Prevents privilege escalation
    # - read_only: Container filesystem is read-only
    # - Minimal attack surface for automated service
    security_opt:
      - no-new-privileges=true
    read_only: true

    # DOCKER SOCKET ACCESS:
    # - /var/run/docker.sock: Read-only access to Docker daemon
    # - Required for monitoring and updating containers
    # - SECURITY: Read-only prevents malicious container creation
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro

    environment:
      # TIMEZONE CONFIGURATION:
      # - TZ: Timezone for scheduling and logging
      # - Must match system timezone for accurate scheduling
      TZ: America/Los_Angeles

      # IMAGE CLEANUP CONFIGURATION:
      # - WATCHTOWER_CLEANUP: true - Remove old images after updating
      # - Prevents disk space issues from accumulated old images
      # - CRITICAL: Saves significant disk space over time
      WATCHTOWER_CLEANUP: true # Remove old images after updating

      # VOLUME HANDLING:
      # - WATCHTOWER_REMOVE_VOLUMES: false - Preserve data volumes
      # - CRITICAL: Prevents data loss during container updates
      # - Volumes contain persistent application data
      WATCHTOWER_REMOVE_VOLUMES: false # Remove attached volumes after updating

      # DOCKER API CONFIGURATION:
      # - DOCKER_API_VERSION: 1.43 - Docker API version compatibility
      # - Must match or be compatible with Docker daemon version
      DOCKER_API_VERSION: 1.43 # Synology DSM max supported API version

      # UPDATE BEHAVIOR:
      # - WATCHTOWER_INCLUDE_RESTARTING: true - Update restarting containers
      # - WATCHTOWER_INCLUDE_STOPPED: false - Skip stopped containers
      # - Ensures only active services are automatically updated
      WATCHTOWER_INCLUDE_RESTARTING: true # Restart containers after update
      WATCHTOWER_INCLUDE_STOPPED: false # Update stopped containers

      # SCHEDULING CONFIGURATION:
      # - WATCHTOWER_SCHEDULE: "0 0 */2 * * *" - Every 2 hours
      # - Cron format: second minute hour day month weekday
      # - Frequent enough for security updates, not too disruptive
      WATCHTOWER_SCHEDULE: "0 0 */2 * * *" # Update & Scan containers every 2 hours

      # LABEL-BASED FILTERING:
      # - WATCHTOWER_LABEL_ENABLE: false - Update all containers
      # - Alternative: true (only update containers with watchtower labels)
      WATCHTOWER_LABEL_ENABLE: false

      # RESTART BEHAVIOR:
      # - WATCHTOWER_ROLLING_RESTART: true - Restart containers one by one
      # - Minimizes service disruption during updates
      # - WATCHTOWER_TIMEOUT: 30s - Wait time for graceful shutdown
      WATCHTOWER_ROLLING_RESTART: false # Disabled due to dependent containers
      WATCHTOWER_TIMEOUT: 30s

      # MONITORING INTEGRATION:
      # - WATCHTOWER_HTTP_API_METRICS: true - Enable Prometheus metrics
      # - WATCHTOWER_HTTP_API_TOKEN: "REDACTED_HTTP_TOKEN" token for metrics endpoint
      # - Allows monitoring of update frequency and success rates
      # - HTTP_API_UPDATE disabled to allow scheduled runs
      WATCHTOWER_HTTP_API_METRICS: true # Metrics for Prometheus
      WATCHTOWER_HTTP_API_TOKEN: "REDACTED_HTTP_TOKEN" # Token for Prometheus

    # RESTART POLICY:
    # - on-failure:5: Restart up to 5 times on failure
    # - Ensures automatic updates continue even after failures
    # - Prevents infinite restart loops
    restart: on-failure:5

networks:
  prometheus-net:
    external: true