Add comprehensive health checks to Docker container

- Enhanced health check script with multiple check points
- Added /api/health endpoint for monitoring integration
- Configured proper Docker HEALTHCHECK parameters
- Implemented graceful degradation for non-critical failures
- Added health monitoring documentation

Health checks now monitor:
- Python process status
- Web server responsiveness
- TAR1090 connection
- Log file access
- Request failure rates

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: challgren

Dockerfile

@@ -55,5 +55,9 @@ RUN chmod +x /etc/s6-overlay/s6-rc.d/aircraft-circle/run && \
 EXPOSE 8888
 
 # Health check
-HEALTHCHECK --start-period=30s --interval=30s --timeout=5s --retries=3 \
+# Start period: 60s to allow service to fully start
+# Interval: 30s for regular checks
+# Timeout: 10s to allow for TAR1090 connection check
+# Retries: 3 failures before marking unhealthy
+HEALTHCHECK --start-period=60s --interval=30s --timeout=10s --retries=3 \
     CMD python3 /scripts/healthcheck.py || exit 1

README.md

@@ -111,6 +111,51 @@ python app.py --server http://your-tar1090:8080 --web
 | `MIN_GRID_LEGS` | Minimum parallel legs | `3` |
 | `MIN_LEG_LENGTH` | Minimum leg length (km) | `2.0` |
 
+## 🏥 Health Monitoring
+
+### Docker Health Check
+
+The container includes comprehensive health checks that monitor:
+
+- Python process status
+- Web server responsiveness (when enabled)
+- API endpoint availability
+- TAR1090 connection status
+- Log file writability
+
+Health check configuration:
+
+- **Start Period**: 60 seconds (allows service to fully initialize)
+- **Check Interval**: 30 seconds
+- **Timeout**: 10 seconds per check
+- **Retries**: 3 failures before marking unhealthy
+
+### Health API Endpoint
+
+Access health status at: `http://localhost:8888/api/health`
+
+```json
+{
+  "status": "healthy",
+  "timestamp": 1234567890.123,
+  "checks": {
+    "web_server": true,
+    "tar1090_connection": true,
+    "last_update": 1234567890.123,
+    "aircraft_count": 115,
+    "active_circles": 2,
+    "active_grids": 1,
+    "total_requests": 1000,
+    "failed_requests": 5
+  }
+}
+```
+
+Status values:
+
+- `healthy` - All systems operational
+- `degraded` - Service running but with issues (e.g., TAR1090 connection lost)
+
 ## 🖥️ Web Interface
 
 ### Live View

app.py

@@ -2537,6 +2537,40 @@ def send_static(path):
         def get_patterns():
             return jsonify(self.get_pattern_data_json())
 
+        @app.route('/api/health')
+        def health_check():
+            """Health check endpoint for monitoring."""
+            # Count active patterns
+            circling_count = len(self.get_circling_aircraft())
+            grid_count = len(self.get_grid_aircraft())
+            
+            health_status = {
+                'status': 'healthy',
+                'timestamp': time.time(),
+                'checks': {
+                    'web_server': True,
+                    'tar1090_connection': self.last_update is not None,
+                    'last_update': self.last_update.timestamp() if self.last_update else 0,
+                    'aircraft_count': len(self.aircraft),
+                    'active_circles': circling_count,
+                    'active_grids': grid_count,
+                    'total_requests': self.total_requests,
+                    'failed_requests': self.failed_requests
+                }
+            }
+            
+            # Check if we haven't received updates in a while (5 minutes)
+            if self.last_update and (time.time() - self.last_update.timestamp()) > 300:
+                health_status['status'] = 'degraded'
+                health_status['checks']['tar1090_connection'] = False
+            
+            # Check if too many requests are failing
+            if self.total_requests > 10 and (self.failed_requests / self.total_requests) > 0.5:
+                health_status['status'] = 'degraded'
+                health_status['checks']['high_failure_rate'] = True
+            
+            return jsonify(health_status)
+        
         @app.route('/history')
         def history():
             return render_template_string(HISTORY_HTML_TEMPLATE)

rootfs/scripts/healthcheck.py

@@ -3,19 +3,42 @@
 
 import sys
 import os
+import json
 import requests
 from pathlib import Path
+import time
 
 def check_web_server():
     """Check if web server is responding."""
-    if os.environ.get('ENABLE_WEB', 'true').lower() == 'true':
-        port = os.environ.get('WEB_PORT', '8888')
-        try:
-            response = requests.get(f'http://localhost:{port}/data.json', timeout=3)
-            return response.status_code == 200
-        except:
+    if os.environ.get('ENABLE_WEB', 'true').lower() != 'true':
+        return True  # Web server disabled, skip check
+    
+    port = os.environ.get('WEB_PORT', '8888')
+    try:
+        # Check health endpoint
+        response = requests.get(f'http://localhost:{port}/api/health', timeout=3)
+        if response.status_code != 200:
+            return False
+        
+        # Verify response is valid JSON and check status
+        data = response.json()
+        if not isinstance(data, dict):
             return False
-    return True
+        
+        # Check the reported status
+        status = data.get('status', 'unknown')
+        if status == 'healthy':
+            return True
+        elif status == 'degraded':
+            print(f"Warning: Service is degraded - {data.get('checks', {})}")
+            return True  # Still return True for degraded state
+        else:
+            print(f"Error: Service status is {status}")
+            return False
+            
+    except Exception as e:
+        print(f"Web server check error: {e}")
+        return False
 
 def check_process():
     """Check if main process is running."""
@@ -25,23 +48,72 @@ def check_process():
         result = subprocess.run(['pgrep', '-f', 'python3.*app.py'], 
                               capture_output=True, text=True)
         return result.returncode == 0
-    except:
+    except Exception as e:
+        print(f"Process check error: {e}")
+        return False
+
+def check_tar1090_connection():
+    """Check if we can connect to TAR1090."""
+    tar1090_url = os.environ.get('TAR1090_URL', 'http://tar1090:80')
+    try:
+        # Allow this check to fail gracefully as TAR1090 might be temporarily unavailable
+        response = requests.get(f'{tar1090_url}/data/aircraft.json', timeout=5)
+        if response.status_code == 200:
+            data = response.json()
+            # Check if we got valid aircraft data
+            if 'aircraft' in data or 'ac' in data:
+                return True
+        # Don't fail health check if TAR1090 is temporarily unavailable
+        # Just log a warning
+        print(f"Warning: TAR1090 at {tar1090_url} not responding (status: {response.status_code})")
+        return True  # Return True to not fail the container
+    except requests.exceptions.RequestException as e:
+        print(f"Warning: Cannot connect to TAR1090 at {tar1090_url}: {e}")
+        return True  # Return True to not fail the container
+    except Exception as e:
+        print(f"Warning: TAR1090 check error: {e}")
+        return True  # Return True to not fail the container
+
+def check_log_files():
+    """Check if log files are writable."""
+    try:
+        # Check if we can write to log directory
+        log_dir = Path('/app')
+        if not log_dir.exists():
+            return False
+        
+        # Test write access
+        test_file = log_dir / '.healthcheck_test'
+        test_file.write_text(str(time.time()))
+        test_file.unlink()
+        return True
+    except Exception as e:
+        print(f"Log file check error: {e}")
         return False
 
 def main():
     """Run health checks."""
+    # Define checks with their names and criticality
     checks = [
-        ("Process", check_process()),
-        ("Web Server", check_web_server()),
+        ("Process", check_process(), True),  # Critical
+        ("Web Server", check_web_server(), True),  # Critical
+        ("Log Files", check_log_files(), True),  # Critical
+        ("TAR1090 Connection", check_tar1090_connection(), False),  # Non-critical
     ]
 
-    failed = [name for name, status in checks if not status]
+    # Separate critical and non-critical failures
+    critical_failures = [name for name, status, critical in checks if not status and critical]
+    warnings = [name for name, status, critical in checks if not status and not critical]
+    
+    # Print status
+    if warnings:
+        print(f"Health check warnings: {', '.join(warnings)}")
 
-    if failed:
-        print(f"Health check failed: {', '.join(failed)}")
+    if critical_failures:
+        print(f"Health check FAILED: {', '.join(critical_failures)}")
         sys.exit(1)
 
-    print("Health check passed")
+    print("Health check PASSED")
     sys.exit(0)
 
 if __name__ == "__main__":