[groupsky]

Summary

Adds support for both docker-compose 1.x (with dash) and docker compose 2.x (plugin) versions by creating a shared helper library and refactoring all deployment scripts to use it.

Fixes production deployment issue where scripts failed with docker-compose 1.27.4 due to hardcoded docker compose (without dash) commands and missing JSON format support.

Changes

Commit 1: Initial Refactoring (2558d9d)

New File: scripts/docker-helper.sh

• Comprehensive helper library with 30+ utility functions
• Auto-detects docker-compose version (prefers 2.x, falls back to 1.x)
• Provides common utilities: logging, confirmations, notifications, validation
• Service management: health checks, locking, emergency restart
• File operations: atomic writes, version management, backup references
• Git helpers: commit hash, branch name, detached HEAD detection

Refactored Scripts:

• backup.sh: Reduced by ~60 lines
• restore.sh: Reduced by ~61 lines
• deploy.sh: Reduced by ~113 lines (31% reduction)
• rollback.sh: Reduced by ~100+ lines
• Total: Eliminated ~441 lines of duplicate code

Key Improvements:

• 27 docker compose commands replaced with dc_run() wrapper
• Standardized variables: Integer flags (0/1), consistent naming
• Better security: Input validation, path traversal prevention
• Explicit dependency checks: jq, flock, curl with helpful errors

Commit 2: Follow-up Improvements (f08494a)

New High-Priority Helpers:

• format_version_short() - Truncate git SHAs for display
• determine_backup_name() - Consolidate backup name determination
• validate_backup_or_exit() - Wrapper for validation with error handling
• require_services_stopped() - Check and exit if services running
• determine_previous_version() - Consolidate version fallback logic
• checkout_git_version() - Safe git checkout with validation

Constants Added:

• HEALTH_CHECK_TIMEOUT_DEPLOY (300s)
• HEALTH_CHECK_TIMEOUT_ROLLBACK (120s)
• HEALTH_CHECK_TIMEOUT_DEFAULT (300s)

Bug Fixes:

• Removed eval usage from backup.sh (eliminates command injection risk)
• Added documentation for SERVICES_STOPPED_LOCAL variable
• Fixed hardcoded help text in restore.sh to use $DOCKER_COMPOSE_CMD
• Simplified using new helpers (restore.sh: 44% reduction)

Commit 3: Docker-Compose v1.27.4 Compatibility (986158a)

CRITICAL FIX: JSON Format Fallback

The --format json flag was added in docker-compose v1.28.0 (Nov 2020). Production runs v1.27.4 (Jun 2020) which doesn't support this flag, causing all health checks to fail.

Solution:

• Added supports_json_format() to detect JSON support
• Created version-aware helper functions:
  • get_running_services_count() - Uses JSON or grep fallback
  • get_unhealthy_services() - Uses JSON or skips gracefully
  • get_starting_services() - Uses JSON or skips gracefully
• Updated wait_for_health() to skip health checks on v1.27.4 with warning
• Updated require_services_stopped() to use grep fallback

Version Detection Priority:

• Now prefers docker compose (2.x plugin) over docker-compose (1.x standalone)
• Ensures newer version is used when both are available

Impact:

• ✅ Works with docker-compose 1.27.4 (production)
• ✅ Works with docker compose 2.x (modern)
• ✅ Graceful degradation when JSON format unavailable
• ✅ No breaking changes to external interfaces

Commit 4: Critical Robustness Fixes (1cdc1a1)

Addresses code review findings - 5 critical fixes:

1. Fixed grep pattern bug (get_running_services_count)

   • Changed pattern from " Up " to " Up\b" (added word boundary)
   • Now correctly matches services with health checks: Up (healthy), Up (health: starting)
   • Prevents false positives like "Upgrading", "Uploaded", "Uptime"
   • Fixes service detection on docker-compose 1.27.4

2. Added sourcing validation (all scripts)

   • Validates docker-helper.sh exists before sourcing
   • Error handling if sourcing fails with clear error messages
   • Prevents cryptic bash errors if helper file missing/corrupted
   • Added shellcheck source directive

3. Prevented trap double-firing (deploy.sh → rollback.sh)

   • Disarms emergency restart trap before calling rollback
   • Eliminates duplicate service restart attempts
   • Prevents service state management conflicts

4. Added atomic write error handling (atomic_write())

   • Proper error handling for file operations
   • Unique temp filenames with PID (*.tmp.$$)
   • Cleanup on failure with clear error messages
   • Prevents silent failures on disk full/permissions

5. Fixed error logging in quiet mode

   • New error() function never suppressed by QUIET mode
   • Always outputs to stderr and log file
   • Updated all validation functions to use error()
   • Ensures critical errors are always visible

BONUS:

• Made services_running() version-aware (now uses get_running_services_count())

Commit 5: Complete Error Logging Migration (9f46ca0)

Remaining grep pattern fixes:

• Updated get_running_services_count() to use word boundary \b consistently
• Fixed comment documentation to explain the word boundary requirement

Commit 6: Error Handling and Robustness Improvements (fecffa5)

Based on multi-aspect code review findings:

Error Handling Standardization:

• Use error() function consistently instead of echo "ERROR: ..." >&2
• Consolidate error messages with installation instructions in single calls
• Improve error logging in atomic_write(), require_jq(), require_curl()
• Add proper error handling for service restart failures in backup.sh

Security Improvements:

• Make DOCKER_COMPOSE_CMD readonly to prevent modification
• Quote $DOCKER_COMPOSE_CMD in dc_run() to prevent word splitting
• Remove unnecessary export of secrets (TELEGRAM_BOT_TOKEN, TELEGRAM_CHAT_ID)

Code Quality:

• Rename validate_and_check_backup() to validate_backup_or_exit() for clarity
• Consolidate duplicate backup error handling in backup.sh
• Replace non-portable grep -P with grep -o | sed for BSD/macOS compatibility

Code Reduction

• Initial refactoring: ~441 lines eliminated
• Follow-up improvements: ~105 lines eliminated
• Final improvements: ~12 lines eliminated
• Total duplicate code removed: ~558 lines
• Net change: +802 additions (new helpers), -713 deletions

Testing

• ✅ All scripts pass syntax validation (bash -n)
• ✅ Compatible with docker-compose 1.27.4 (uses text parsing fallback)
• ✅ Compatible with docker compose 2.x (uses JSON format)
• ✅ All existing functionality preserved
• ✅ Code review findings addressed (all critical and medium-priority fixes)
• ✅ Portable grep implementation tested and verified
• ✅ DOCKER_COMPOSE_CMD verified as readonly

Compatibility

Minimum Requirements:

• Bash 3.0+
• Git 1.8.5+
• jq (for health checks with JSON support)
• flock (for deployment locking)
• curl (for notifications, optional)

Supported Docker Compose Versions:

• docker-compose 1.27.4+ (text parsing fallback)
• docker compose 2.x (JSON format support)

Platform Support:

• Linux (primary target)
• BSD/macOS (portable grep implementation)

Security Improvements

1. Removed eval usage from backup.sh (no command injection risk)
2. Centralized input validation prevents injection attacks
3. Path traversal prevention in backup names
4. Image tag validation prevents malicious tags
5. Atomic writes for all critical file operations with error handling
6. Proper locking with flock prevents race conditions
7. Error logging never suppressed (always visible to operators)
8. NEW: DOCKER_COMPOSE_CMD is readonly and properly quoted
9. NEW: Secrets no longer exported to child processes

Breaking Changes

None. All external interfaces remain unchanged.

Migration Notes

Scripts automatically detect and use the appropriate docker-compose command. No manual configuration needed.

If both docker-compose 1.x and docker compose 2.x are installed, the scripts will prefer the 2.x plugin version.

Related Issues

Fixes production deployment issue where scripts failed on docker-compose 1.27.4 due to:

1. Hardcoded docker compose (without dash) commands
2. Use of --format json flag not supported until v1.28.0