Healthchecks.io

beginner

Cron job monitoring and alerting service.

Overview

Healthchecks.io is an open-source cron job monitoring service that tracks scheduled tasks and background jobs to ensure they run on time and complete successfully. Originally created as a SaaS platform, the self-hosted version provides organizations with complete control over their monitoring infrastructure while maintaining the same robust alerting capabilities. The service works by expecting regular HTTP pings from monitored jobs - when those pings stop arriving or arrive outside expected windows, alerts are triggered. This Docker stack deploys the Healthchecks.io web application with SQLite database storage, creating a lightweight monitoring platform that can track dozens of cron jobs and automated tasks. The application provides a web dashboard for managing checks, viewing logs, and configuring alert channels, while monitored services send simple HTTP requests to unique URLs to report their status. The stack includes persistent data storage to maintain check history and configuration across container restarts. This configuration is ideal for small to medium-sized teams, homelab enthusiasts, and organizations wanting to self-host their cron monitoring without external dependencies. DevOps teams managing critical scheduled tasks, system administrators overseeing backup jobs, and developers running automated workflows will find this stack particularly valuable for maintaining visibility into job execution patterns and receiving immediate notification when tasks fail or run unexpectedly late.

Key Features

Web-based dashboard for creating and managing cron job monitoring checks with customizable grace periods
HTTP ping endpoints with unique UUIDs for each monitored task or service
Multiple notification channels including email, Slack, PagerDuty, Telegram, Discord, and webhooks
Ping log retention showing recent execution history and timing patterns for each check
Configurable check schedules supporting cron expressions and simple interval definitions
Team collaboration features with user accounts and shared project workspaces
REST API for programmatic check management and integration with existing automation tools
Timezone-aware scheduling and grace period calculations for global deployment scenarios

Common Use Cases

1Monitoring database backup scripts to ensure daily backups complete successfully
2Tracking ETL pipeline jobs and data processing workflows in analytics environments
3Supervising system maintenance tasks like log rotation, cache clearing, and cleanup scripts
4Monitoring heartbeat signals from IoT devices and remote monitoring stations
5Alerting on failed or delayed certificate renewal processes and security scans
6Tracking CI/CD pipeline health checks and automated deployment verification
7Monitoring health check endpoints for microservices and distributed applications

Prerequisites

Docker Engine 20.10+ and Docker Compose V2 for container orchestration
Minimum 512MB RAM for the healthchecks container and SQLite database operations
Port 8000 available for the web interface and ping endpoint access
Valid SECRET_KEY environment variable for Django session security
SMTP server credentials if email notifications will be configured
Understanding of cron syntax and HTTP client tools like curl for job integration

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

1services: 
2  healthchecks: 
3    image: healthchecks/healthchecks:latest
4    container_name: healthchecks
5    restart: unless-stopped
6    environment: 
7      DB: sqlite
8      SECRET_KEY: ${SECRET_KEY}
9      ALLOWED_HOSTS: "*"
10      DEBUG: "False"
11    volumes: 
12      - healthchecks_data:/data
13    ports: 
14      - "8000:8000"
15
16volumes: 
17  healthchecks_data:

.env Template

.env

1SECRET_KEY=your-secret-key-here

Usage Notes

1Docs: https://healthchecks.io/docs/
2Dashboard at http://localhost:8000 - create account to start
3Add curl to cron: curl -fsS -m 10 --retry 5 http://localhost:8000/ping/UUID
4Alerts when cron jobs fail or run late
5Integrations: Slack, PagerDuty, Email, Telegram, and more
6Create superuser: docker exec -it healthchecks ./manage.py createsuperuser

Quick Start

terminal

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  healthchecks:
5    image: healthchecks/healthchecks:latest
6    container_name: healthchecks
7    restart: unless-stopped
8    environment:
9      DB: sqlite
10      SECRET_KEY: ${SECRET_KEY}
11      ALLOWED_HOSTS: "*"
12      DEBUG: "False"
13    volumes:
14      - healthchecks_data:/data
15    ports:
16      - "8000:8000"
17
18volumes:
19  healthchecks_data:
20EOF
21
22# 2. Create the .env file
23cat > .env << 'EOF'
24SECRET_KEY=your-secret-key-here
25EOF
26
27# 3. Start the services
28docker compose up -d
29
30# 4. View logs
31docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal

1curl -fsSL https://docker.recipes/api/recipes/healthchecks/run | bash

Troubleshooting

Container exits with 'SECRET_KEY required' error: Generate and set a strong SECRET_KEY environment variable in your .env file
Web interface shows 'DisallowedHost' error: Verify ALLOWED_HOSTS environment variable includes your domain or set to '*' for testing
Ping requests return 404 errors: Ensure the check UUID is correct and the healthchecks service is accessible on port 8000
Database migrations fail on startup: Check that the healthchecks_data volume has proper write permissions and sufficient disk space
Email notifications not sending: Configure SMTP settings through the admin interface or environment variables like EMAIL_HOST and EMAIL_PORT
Check logs show incorrect timezone: Set the TZ environment variable to match your local timezone for accurate scheduling

Community Notes

Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

healthchecks

Related Recipes

Ad Space

Shortcuts: C CopyF FavoriteD Download