---
sidebar_position: 8
---

import {
  ConfigSection,
  Important,
  Warning,
  ElementNavigator,
  SectionTitle,
  styles
} from '@site/src/components/documentation';

# Health Checks

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

<ElementNavigator />

<div className={styles.documentationPage}>

<div className={styles.section}>

<SectionTitle icon="🏥">Health Check Endpoints</SectionTitle>

<ConfigSection
  title="/health - Liveness Probe"
  icon="💓"
>

**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

```bash
curl http://localhost:11011/health
```

</ConfigSection>

<ConfigSection
  title="/health/ready - Readiness Probe"
  icon="✅"
>

**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

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

</ConfigSection>

<ConfigSection
  title="/health/detailed - Detailed Status"
  icon="📊"
>

**Purpose**: 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

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

</ConfigSection>

</div>

<div className={styles.section}>

<SectionTitle icon="🔍">Health Check Components</SectionTitle>

<ConfigSection
  title="Application Health"
  icon="🚀"
>

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

</ConfigSection>

<ConfigSection
  title="Database Health"
  icon="🗄️"
>

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

</ConfigSection>

<ConfigSection
  title="File System Health"
  icon="📁"
>

- 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.
</Important>

</ConfigSection>

<ConfigSection
  title="Download Client Health"
  icon="⬇️"
>

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

</ConfigSection>

</div>

<div className={styles.section}>

<SectionTitle icon="🐳">Environment Variables</SectionTitle>

<ConfigSection
  title="Environment Variables"
  icon="🌍"
>

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`

</ConfigSection>

</div>

<div className={styles.section}>

<SectionTitle icon="🔧">Troubleshooting</SectionTitle>

<ConfigSection
  title="Common Issues"
  icon="⚠️"
>

**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

</ConfigSection>

</div>

</div> 