Initial commit: Nginx Proxy Manager utility scripts and documentation

- CLAUDE.md: Project guidance for Claude Code
- PROJECT_DOCUMENTATION.md: Complete project documentation
- upload_log_file_fixed.sh: Fixed rclone upload functions with proper error handling
- error_handling_comparison.sh: Documentation of rclone error handling patterns

This repository contains utility scripts for managing nginx-proxy-manager
log streaming to Cloudflare R2 storage, designed for CrowdSec integration.

error_handling_comparison.sh

@@ -0,0 +1,78 @@
+#!/bin/bash
+
+echo "=== RCLONE ERROR HANDLING COMPARISON ==="
+echo
+
+# ❌ PROBLEMATIC APPROACH (what you might have been doing)
+echo "❌ PROBLEMATIC APPROACH:"
+echo "---"
+cat << 'EOF'
+upload_log_file_problematic() {
+    local source_file="$1"
+    local dest_path="$2"
+    
+    # WRONG: Parsing output instead of checking exit code
+    local output=$(rclone copyto "$source_file" "$dest_path" 2>&1)
+    
+    if [[ "$output" =~ "Transferred: 0 / 1, 0%" ]]; then
+        echo "Upload failed!"  # This is WRONG - 0% can mean success!
+        return 1
+    elif [[ "$output" =~ "error" ]] || [[ "$output" =~ "failed" ]]; then
+        echo "Upload failed!"
+        return 1
+    else
+        echo "Upload successful"
+        return 0
+    fi
+}
+EOF
+
+echo
+echo "Problems with this approach:"
+echo "• Relies on parsing text output which can be misleading"
+echo "• 'Transferred: 0 / 1, 0%' appears even for successful uploads"
+echo "• Ignores rclone's actual exit code"
+echo "• Fragile - breaks if rclone changes output format"
+echo
+
+# ✅ CORRECT APPROACH
+echo "✅ CORRECT APPROACH:"
+echo "---"
+cat << 'EOF'
+upload_log_file_correct() {
+    local source_file="$1" 
+    local dest_path="$2"
+    
+    echo "Uploading $(basename "$source_file")..."
+    
+    # CORRECT: Check rclone's exit code directly
+    if rclone copyto "$source_file" "$dest_path" \
+        --retries=2 \
+        --timeout=300s \
+        --progress; then
+        # Exit code 0 = success
+        echo "✅ Upload successful"
+        return 0
+    else
+        # Non-zero exit code = failure
+        local exit_code=$?
+        echo "❌ Upload failed (exit code: $exit_code)"
+        return $exit_code
+    fi
+}
+EOF
+
+echo
+echo "Why this approach works:"
+echo "• Uses rclone's exit code (0=success, non-zero=failure)"
+echo "• Reliable regardless of output text format"
+echo "• Follows Unix convention for command success/failure"
+echo "• Built-in retry mechanism"
+echo
+
+echo "=== KEY TAKEAWAYS ==="
+echo "1. Always check EXIT CODES, not output text"
+echo "2. rclone exit code 0 = success, anything else = failure"
+echo "3. Progress output like 'Transferred: 0 / 1, 0%' can appear for successful uploads"
+echo "4. Use proper error handling with retries and timeouts"
+echo "5. Don't exit monitoring loops on upload failures - retry in next cycle"