Add deploy script, CI integration and docs

Replace direct docker pull/run steps in CI with a robust deploy script (downloaded to /opt/espacogeek/deploy.sh) that handles backup, rename, image pull, container start, health checks, rollback, cleanup and logging. Update .github/workflows/cicd.yml to use script_stop: all, create .env.espacogeek, login to GHCR and execute the deploy script. Add docker/deploy.sh and docker/diagnose.sh and comprehensive documentation files (DEPLOYMENT_SUMMARY.md, INDEX.md, VALIDATION.md and multiple docker/*.md) describing architecture, setup, testing and quick references.

Author: vitorhugo-java

.github/workflows/cicd.yml

@@ -208,10 +208,229 @@ jobs:
           key: ${{ secrets.HOSTINGER }}
           port: ${{ secrets.HOSTINGER_PORT }}
           envs: GHCR_OWNER_LC,APP_NAME
+          script_stop: all
           script: |
-            set -e
-            echo "Starting deployment with image: ghcr.io/${GHCR_OWNER_LC}/${APP_NAME}:latest"
+            # Download and setup deploy script if not present
+            DEPLOY_SCRIPT="/opt/espacogeek/deploy.sh"
+
+            if [ ! -f "$DEPLOY_SCRIPT" ]; then
+              echo "Downloading deploy script..."
+              mkdir -p "$(dirname "$DEPLOY_SCRIPT")"
+              # You can download from a specific release or use inline
+              cat > "$DEPLOY_SCRIPT" << 'DEPLOY_SCRIPT_EOF'
+            #!/bin/bash
+
+            set -euo pipefail
+
+            RED='\033[0;31m'
+            GREEN='\033[0;32m'
+            YELLOW='\033[1;33m'
+            BLUE='\033[0;34m'
+            NC='\033[0m'
+
+            log_info() { echo -e "${BLUE}[INFO]${NC} $*"; }
+            log_success() { echo -e "${GREEN}[✓]${NC} $*"; }
+            log_warn() { echo -e "${YELLOW}[WARN]${NC} $*"; }
+            log_error() { echo -e "${RED}[✗]${NC} $*"; }
+
+            trap 'on_error' ERR
+            on_error() {
+              local exit_code=$?
+              if [ $exit_code -ne 0 ]; then
+                log_error "Deployment failed with exit code $exit_code"
+                log_warn "Attempting rollback..."
+                rollback_deployment
+              fi
+            }
+
+            GHCR_OWNER_LC="${1:-}"
+            APP_NAME="${2:-}"
+            IMAGE_TAG="${3:-latest}"
+            ENV_FILE="${4:-.env.espacogeek}"
+            CONTAINER_NAME="espacogeek"
+            BACKUP_DIR="${HOME}/espacogeek-backups"
+            OLD_CONTAINER_BACKUP="${CONTAINER_NAME}-old"
+            TIMESTAMP=$(date +%Y%m%d_%H%M%S)
+
+            if [ -z "$GHCR_OWNER_LC" ] || [ -z "$APP_NAME" ]; then
+              log_error "Usage: $0 <GHCR_OWNER_LC> <APP_NAME> [IMAGE_TAG] [ENV_FILE]"
+              exit 1
+            fi
+
+            IMAGE="ghcr.io/${GHCR_OWNER_LC}/${APP_NAME}:${IMAGE_TAG}"
+
+            container_exists() { docker ps -a --format '{{.Names}}' | grep -q "^${1}$"; }
+            container_running() { docker ps --format '{{.Names}}' | grep -q "^${1}$"; }
+
+            backup_old_container() {
+              if ! container_exists "$CONTAINER_NAME"; then
+                log_info "No existing container to backup"
+                return 0
+              fi
+              log_info "Creating backup of old container..."
+              mkdir -p "$BACKUP_DIR"
+              BACKUP_FILE="${BACKUP_DIR}/${CONTAINER_NAME}_backup_${TIMESTAMP}.tar"
+              log_info "Exporting container to ${BACKUP_FILE}..."
+              if docker export "$CONTAINER_NAME" > "$BACKUP_FILE"; then
+                log_success "Container backup created: ${BACKUP_FILE}"
+              else
+                log_error "Failed to backup container"
+                return 1
+              fi
+              ls -t "${BACKUP_DIR}/${CONTAINER_NAME}_backup_"*.tar 2>/dev/null | tail -n +6 | xargs rm -f 2>/dev/null || true
+            }
+
+            rename_old_container() {
+              if ! container_exists "$CONTAINER_NAME"; then
+                log_info "No old container to rename"
+                return 0
+              fi
+              log_info "Renaming old container..."
+              if container_running "$CONTAINER_NAME"; then
+                log_info "Stopping old container..."
+                docker stop "$CONTAINER_NAME" || log_warn "Failed to stop container"
+              fi
+              if docker rename "$CONTAINER_NAME" "${OLD_CONTAINER_BACKUP}" 2>/dev/null; then
+                log_success "Old container renamed to ${OLD_CONTAINER_BACKUP}"
+              else
+                log_warn "Could not rename old container"
+              fi
+            }
+
+            pull_new_image() {
+              log_info "Pulling new image: ${IMAGE}..."
+              if docker pull "$IMAGE"; then
+                log_success "Image pulled successfully"
+                return 0
+              else
+                log_error "Failed to pull image"
+                return 1
+              fi
+            }
+
+            start_new_container() {
+              log_info "Starting new container..."
+              if ! docker run -d --name "$CONTAINER_NAME" -p 8080:8080 --restart unless-stopped --env-file "$ENV_FILE" "$IMAGE"; then
+                log_error "Failed to start container"
+                return 1
+              fi
+              log_success "Container started with ID: $(docker ps --filter name=$CONTAINER_NAME -q)"
+            }
+
+            validate_container_health() {
+              local max_attempts=30
+              local attempt=1
+              log_info "Validating container health (max ${max_attempts} attempts)..."
+              while [ $attempt -le $max_attempts ]; do
+                if container_running "$CONTAINER_NAME"; then
+                  local status=$(docker inspect "$CONTAINER_NAME" --format='{{.State.Status}}')
+                  if [ "$status" = "running" ]; then
+                    if docker exec "$CONTAINER_NAME" wget -q -O- http://localhost:8080/actuator/health &>/dev/null 2>&1 || docker exec "$CONTAINER_NAME" curl -s http://localhost:8080/actuator/health &>/dev/null 2>&1; then
+                      log_success "Container is healthy"
+                      return 0
+                    fi
+                  else
+                    log_warn "Container status is: $status"
+                  fi
+                fi
+                log_info "Waiting... (attempt ${attempt}/${max_attempts})"
+                sleep 2
+                attempt=$((attempt + 1))
+              done
+              log_error "Container failed health check"
+              return 1
+            }
+
+            cleanup_old_container() {
+              log_info "Cleaning up old container..."
+              if container_exists "${OLD_CONTAINER_BACKUP}"; then
+                log_info "Removing backed-up container: ${OLD_CONTAINER_BACKUP}"
+                if docker rm -f "${OLD_CONTAINER_BACKUP}"; then
+                  log_success "Old container removed"
+                else
+                  log_warn "Could not remove old container"
+                fi
+              fi
+            }
+
+            rollback_deployment() {
+              log_warn "Starting rollback procedure..."
+              if container_exists "$CONTAINER_NAME"; then
+                log_info "Stopping new container..."
+                docker stop "$CONTAINER_NAME" 2>/dev/null || true
+                docker rm "$CONTAINER_NAME" 2>/dev/null || true
+              fi
+              if container_exists "${OLD_CONTAINER_BACKUP}"; then
+                log_info "Restoring old container from backup: ${OLD_CONTAINER_BACKUP}"
+                if docker rename "${OLD_CONTAINER_BACKUP}" "$CONTAINER_NAME" 2>/dev/null; then
+                  if docker start "$CONTAINER_NAME"; then
+                    log_success "Rollback successful: Old container restored"
+                    return 0
+                  else
+                    log_error "Failed to start rolled-back container"
+                    return 1
+                  fi
+                else
+                  log_error "Failed to rename backed-up container"
+                  return 1
+                fi
+              else
+                log_error "No backed-up container available for rollback"
+                return 1
+              fi
+            }
+
+            show_container_status() {
+              log_info "=== Container Status ==="
+              docker ps -a --filter name="$CONTAINER_NAME" --filter name="${OLD_CONTAINER_BACKUP}" || log_info "No containers found"
+              log_info "======================="
+            }
+
+            show_container_logs() {
+              log_info "=== Container Logs (last 20 lines) ==="
+              if container_exists "$CONTAINER_NAME"; then
+                docker logs --tail 20 "$CONTAINER_NAME" || log_info "No logs available"
+              fi
+              log_info "======================================="
+            }
+
+            log_info "Starting deployment of ${APP_NAME}:${IMAGE_TAG}"
+            log_info "Container name: ${CONTAINER_NAME}"
+            log_info "Image: ${IMAGE}"
+            log_info "Environment file: ${ENV_FILE}"
+            log_info ""
+
+            if [ ! -f "$ENV_FILE" ]; then
+              log_error "Environment file not found: ${ENV_FILE}"
+              exit 1
+            fi
+            log_success "Environment file found"
+
+            backup_old_container || exit 1
+            rename_old_container || exit 1
+            pull_new_image || exit 1
+            start_new_container || exit 1
 
+            if ! validate_container_health; then
+              log_error "Health check failed, initiating rollback..."
+              rollback_deployment || exit 1
+              exit 1
+            fi
+
+            cleanup_old_container
+
+            log_success ""
+            log_success "=== DEPLOYMENT SUCCESSFUL ==="
+            show_container_status
+            show_container_logs
+            log_success "============================="
+
+            rm -f "$ENV_FILE"
+            DEPLOY_SCRIPT_EOF
+              chmod +x "$DEPLOY_SCRIPT"
+            fi
+
+            # Create environment file
             cat > .env.espacogeek << 'ENVEOF'
             SPRING_DATASOURCE_URL=${{ secrets.SPRING_DATASOURCE_URL }}
             SPRING_DATASOURCE_USERNAME=${{ secrets.SPRING_DATASOURCE_USERNAME }}
@@ -229,31 +448,12 @@ jobs:
             FRONTEND_URL=${{ secrets.FRONTEND_URL }}
             ENVEOF
 
+            # Login to GHCR
             echo "${{ secrets.GHCR_TOKEN }}" | docker login ghcr.io -u "${{ secrets.GHCR_USER }}" --password-stdin
 
-            echo "Pulling image from GHCR..."
-            docker pull ghcr.io/${GHCR_OWNER_LC}/${APP_NAME}:latest || { echo "Failed to pull image"; exit 1; }
-
-            echo "Stopping and removing old container..."
-            docker stop espacogeek || true
-            docker rm espacogeek || true
-
-            echo "Starting new container..."
-            if ! docker run -d --name espacogeek \
-              -p 8080:8080 \
-              --restart unless-stopped \
-              --env-file .env.espacogeek \
-              ghcr.io/${GHCR_OWNER_LC}/${APP_NAME}:latest; then
-              echo "Failed to start container"
-              docker ps -a
-              docker logs espacogeek || true
-              rm -f .env.espacogeek
-              exit 1
-            fi
+            # Execute deployment script
+            "$DEPLOY_SCRIPT" "${GHCR_OWNER_LC}" "${APP_NAME}" "latest" ".env.espacogeek"
 
-            echo "Container started successfully"
-            docker ps -a
-            rm -f .env.espacogeek
 
       # Final summary with generated tags
       - name: Summary