Skip to main content

Health Checks

Cleanuparr provides comprehensive health check endpoints that are compatible with Docker health checks and Kubernetes probes. This allows for better monitoring, automated failover, and container orchestration.

🏥 Health Check Endpoints

💓/health - Liveness Probe

Purpose: Basic liveness check to verify the application is running
Use Case: Docker HEALTHCHECK and Kubernetes liveness probes
Response: HTTP 200 (healthy) or 503 (unhealthy)
Checks: Application startup and basic functionality

curl http://localhost:11011/health

✅/health/ready - Readiness Probe

Purpose: Verify the application is ready to serve traffic
Use Case: Kubernetes readiness probes and load balancer health checks
Response: HTTP 200 (ready) or 503 (not ready)
Checks: Database connectivity, file system access, download client health

curl http://localhost:11011/health/ready

📊/health/detailed - Detailed Status

Purpose: Comprehensive health status for monitoring and debugging
Use Case: Monitoring systems and troubleshooting
Response: Detailed JSON with status of all components
Checks: All health checks with timing and detailed status

curl http://localhost:11011/health/detailed

🔍 Health Check Components

🚀Application Health

  • Verifies the application is running and responsive
  • Basic functionality test
  • Used for liveness probes

🗄️Database Health

  • Tests database connectivity
  • Checks for pending migrations
  • Validates schema integrity
  • Used for readiness probes

📁File System Health

  • Verifies access to configuration directories
  • Validates working directory access
  • Used for readiness probes
⚠️Important

File write tests are not performed during health checks to avoid creating temporary files on every check.

⬇️Download Client Health

  • Integrates with existing download client monitoring
  • Reports status of all configured download clients
  • Considers overall health based on client availability
  • Used for readiness probes

🐳 Environment Variables

🌍Environment Variables

Health check endpoints are affected by these environment variables:

  • PORT: Application port (default: 11011)
  • BASE_PATH: Base path for the application (affects health check URLs)

If you set BASE_PATH=/cleanuparr, health checks will be available at:

  • localhost:[PORT]/cleanuparr/health
  • localhost:[PORT]/cleanuparr/health/ready
  • localhost:[PORT]/cleanuparr/health/detailed

🔧 Troubleshooting

⚠️Common Issues

Health check timeout
Increase timeout values if the application is slow to respond

File system permission errors
Check container user permissions and mount points

Download client unavailability
Review download client configurations and network connectivity