Health Check

Overview

The health check endpoint provides a simple way to verify that the API server is running and responsive. Use this for monitoring, load balancer health checks, and readiness probes.

Endpoint

GET /health

Authentication

No authentication required - This endpoint is publicly accessible.

Request

Simple GET request with no parameters:

$
curl http://localhost:7100/health

Response

Healthy Response

HTTP Status: 200 OK

1
{
2
  "status": "healthy"
3
}

Unhealthy Response

HTTP Status: 503 Service Unavailable

1
{
2
  "status": "unhealthy",
3
  "reason": "No ASR workers available"
4
}

Use Cases

Load Balancer Health Checks

Configure your load balancer to use the health endpoint:

1
apiServer:
2
  service:
3
    type: LoadBalancer
4
    healthCheckPath: /health
5
    healthCheckInterval: 30
6
    healthCheckTimeout: 5
7
    healthyThreshold: 2
8
    unhealthyThreshold: 3

Kubernetes Liveness Probe

Monitor pod health in Kubernetes:

1
livenessProbe:
2
  httpGet:
3
    path: /health
4
    port: 7100
5
  initialDelaySeconds: 30
6
  periodSeconds: 10
7
  timeoutSeconds: 5
8
  failureThreshold: 3

Kubernetes Readiness Probe

Determine when pod is ready to receive traffic:

1
readinessProbe:
2
  httpGet:
3
    path: /health
4
    port: 7100
5
  initialDelaySeconds: 10
6
  periodSeconds: 5
7
  timeoutSeconds: 3
8
  failureThreshold: 3

Monitoring and Alerting

Monitor service availability:

1
- job_name: 'api-server-health'
2
  metrics_path: '/health'
3
  scrape_interval: 30s
4
  static_configs:
5
    - targets: ['api-server:7100']

Uptime Monitoring

Integration with uptime monitoring services:

Advanced Health Checks

Detailed Health Status

For more detailed health information, add query parameter:

$
curl http://localhost:7100/health?detailed=true

Response:

1
{
2
  "status": "healthy",
3
  "components": {
4
    "api_server": "healthy",
5
    "lightning_asr": "healthy",
6
    "license_proxy": "healthy",
7
    "redis": "healthy"
8
  },
9
  "uptime_seconds": 86400,
10
  "version": "1.0.0"
11
}

Component-Specific Checks

Check individual components:

$
curl http://localhost:7100/health/asr
$
curl http://localhost:7100/health/license
$
curl http://localhost:7100/health/redis

Integration Examples

Docker Compose Healthcheck

1
services:
2
  api-server:
3
    image: quay.io/smallestinc/self-hosted-api-server:latest
4
    healthcheck:
5
      test: ["CMD", "curl", "-f", "http://localhost:7100/health"]
6
      interval: 30s
7
      timeout: 10s
8
      retries: 3
9
      start_period: 40s

Kubernetes Deployment

1
apiVersion: apps/v1
2
kind: Deployment
3
metadata:
4
  name: api-server
5
spec:
6
  template:
7
    spec:
8
      containers:
9
      - name: api-server
10
        image: quay.io/smallestinc/self-hosted-api-server:latest
11
        livenessProbe:
12
          httpGet:
13
            path: /health
14
            port: 7100
15
          initialDelaySeconds: 30
16
          periodSeconds: 10
17
        readinessProbe:
18
          httpGet:
19
            path: /health
20
            port: 7100
21
          initialDelaySeconds: 10
22
          periodSeconds: 5

Automated Testing

Include health checks in CI/CD:

1
- name: Wait for deployment
2
  run: |
3
    for i in {1..30}; do
4
      if curl -f http://api.example.com/health; then
5
        echo "Service is healthy"
6
        exit 0
7
      fi
8
      sleep 10
9
    done
10
    echo "Service failed to become healthy"
11
    exit 1

Best Practices

1
healthcheck:
2
  timeout: 5s
3
  interval: 30s
4
  retries: 3

$
kubectl delete pod api-server-xxx

Troubleshooting

Health Check Failing

Check API server logs:

$
kubectl logs -l app=api-server -n smallest

Common causes:

• Lightning ASR not available
• License proxy down
• Redis connection failed

Solutions:

• Verify all components running
• Check service connectivity
• Review component logs

False Positives

Symptoms: Health returns 200 but requests fail

Solutions:

• Use detailed health checks
• Test actual transcription endpoint
• Monitor error rates

Timeout Issues

Symptoms: Health checks timing out

Solutions:

• Increase timeout values
• Check network latency
• Verify no network policies blocking

What’s Next?