TSYSDevStack-SupportStack-Cloudron/Package-Workspace/Monitoring/healthchecks

Healthchecks Cloudron Package

Description

Healthchecks is a cron job monitoring service. It listens for HTTP requests and email messages ("pings") from your cron jobs and scheduled tasks ("checks"). When a ping does not arrive on time, Healthchecks sends out alerts.

Features

Core Capabilities

• Cron Job Monitoring: Monitor scheduled tasks via HTTP pings
• Multiple Alert Methods: Email, SMS, Slack, Discord, Telegram, Matrix, PagerDuty, and 20+ integrations
• Web Dashboard: View status of all cron jobs in a live-updating dashboard
• Status Badges: Generate public but hard-to-guess status badge URLs
• Team Management: Projects, team members, read-only access
• Monthly Reports: Automated monthly summary emails
• WebAuthn 2FA: Modern two-factor authentication support

Check Configuration

• Periodic Pings: Define expected time between pings
• Grace Time: Specify how long to wait before sending alerts when a job is late
• Cron Expressions: Define expected schedules using cron syntax
• Event Logs: View detailed history of each check
• Integrations: Native support for 25+ notification services
• Tags: Organize and filter checks using tags
• Projects: Group related checks together

Configuration

Environment Variables

Database (Automatically configured by Cloudron)

• CLOUDRON_POSTGRESQL_HOST: PostgreSQL host
• CLOUDRON_POSTGRESQL_PORT: PostgreSQL port
• CLOUDRON_POSTGRESQL_DATABASE: Database name
• CLOUDRON_POSTGRESQL_USERNAME: Database username
• CLOUDRON_POSTGRESQL_PASSWORD: Database password

Django Configuration

• SECRET_KEY: Django secret key (auto-generated, change in production)
• ALLOWED_HOSTS: Allowed hosts (default: *)
• SITE_ROOT: Site root URL (auto-configured)

Email Configuration

• EMAIL_HOST: SMTP server host
• EMAIL_PORT: SMTP server port (default: 587)
• EMAIL_HOST_USER: SMTP username
• EMAIL_HOST_PASSWORD: SMTP password
• EMAIL_USE_TLS: Use TLS (default: True)
• DEFAULT_FROM_EMAIL: Default sender email

Admin User

• SUPERUSER_EMAIL: Email address for admin account
• SUPERUSER_PASSWORD: Password for admin account

Ports

• 8000: Main HTTP port (web interface and API)

Usage

1. Create a Check

Via Web Interface:

1. Open Healthchecks dashboard
2. Click "Add Check"
3. Configure:
   • Name: "Daily Backup"
   • Period: "1 day"
   • Grace: "1 hour"
4. Click "Save"
5. Copy the ping URL provided

Via API:

curl -X POST http://localhost:8000/api/v1/checks/ \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily Backup",
    "timeout": 3600,
    "grace": 3600
  }'

2. Configure Cron Job

Add ping to your cron job:

# Backup script
0 2 * * * /path/to/backup.sh

# Send ping to Healthchecks
curl -fsS --retry 3 https://your-app.cloudron.app/ping/your-check-uuid > /dev/null

Combined in one line:

0 2 * * * /path/to/backup.sh && curl -fsS --retry 3 https://your-app.cloudron.app/ping/your-check-uuid > /dev/null

3. Configure Alert Notifications

Email Alerts:

1. Go to "Integrations" in Healthchecks
2. Add email address for notifications
3. Configure which checks send alerts

Slack Integration:

1. Go to "Integrations" → "Slack"
2. Create Slack webhook URL
3. Paste webhook URL into Healthchecks
4. Select which checks send Slack notifications

Telegram Integration:

1. Go to "Integrations" → "Telegram"
2. Message @HealthchecksBot
3. Paste token from bot into Healthchecks
4. Configure alert settings

4. Use Status Badges

Generate badge for your README or dashboard:

https://your-app.cloudron.app/badge/your-check-uuid.svg

Badge will show:

• ✓ Green: Check is up
• ⚠️ Yellow: Check is late
• ✗ Red: Check is down

5. Create Team Members

1. Go to "Team" in Healthchecks
2. Click "Add Team Member"
3. Enter email address
4. Assign role (Admin, Read-only)
5. Team member receives invitation email

6. Set Up Projects

1. Go to "Projects"
2. Click "Create Project"
3. Enter project name and description
4. Add checks to project
5. Share project with team members

Monitoring Examples

Cron Job Monitoring

# Backup script with ping
0 2 * * * /usr/local/bin/backup.sh && curl -fsS https://your-app.cloudron.app/ping/uuid-1

Systemd Service Monitoring

[Unit]
Description=My Service

[Service]
Type=simple
ExecStart=/usr/local/bin/my-service
ExecStartPost=/usr/bin/curl -fsS https://your-app.cloudron.app/ping/uuid-2

[Install]
WantedBy=multi-user.target

Script Monitoring

import subprocess
import requests

# Run backup
subprocess.run(["/usr/local/bin/backup.sh"], check=True)

# Send success ping
requests.get("https://your-app.cloudron.app/ping/uuid-3")

Webhook Monitoring

Healthchecks can send webhooks when check status changes:

# Configure webhook in Healthchecks
URL: https://your-server.com/api/webhook
Method: POST
Body: JSON payload with check details

Security

Change Default Secret Key

The default secret key is auto-generated. Change SECRET_KEY in production:

# Generate new secret key
python -c 'from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())'

# Set SECRET_KEY environment variable

Use Email Authentication

Configure SMTP with authentication to prevent spam:

EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_HOST_USER=your-email@gmail.com
EMAIL_HOST_PASSWORD=your-app-password
EMAIL_USE_TLS=True

API Key Management

1. Create API keys in Healthchecks dashboard
2. Assign keys to team members
3. Use keys in API requests:

curl -H "X-Api-Key: your-api-key" http://localhost:8000/api/v1/checks/

Tag-Based Access Control

Use tags to organize and restrict access:

# Create check with tags
curl -X POST http://localhost:8000/api/v1/checks/ \
  -H "X-Api-Key: your-api-key" \
  -d '{"tags": "production, database"}'

Troubleshooting

Checks Not Receiving Pings

1. Verify cron job is running
2. Check ping URL is correct
3. Test ping manually: curl https://your-app.cloudron.app/ping/uuid
4. Check firewall rules allow outbound HTTP

Alerts Not Sending

1. Verify email configuration is correct
2. Check spam folder for test emails
3. Verify SMTP server allows sending
4. Test email integration in Healthchecks dashboard

Database Connection Errors

1. Verify PostgreSQL addon is active
2. Check database credentials in Cloudron environment
3. Review Healthchecks logs: docker logs <container>
4. Verify PostgreSQL is running: pg_isready

Performance Issues

1. Increase memory limit in Cloudron settings
2. Enable Gzip middleware (default: enabled)
3. Consider using CDN for static files
4. Optimize database queries

Architecture

                    ┌─────────────┐
                    │   Client    │
                    │  (Cron)    │
                    └──────┬──────┘
                           │
                    HTTP Ping (POST)
                           ▼
                   ┌──────────────┐
                   │ Healthchecks  │
                   │  (Django)    │
                   │  Dashboard    │
                   └──────┬──────┘
                           │
                           ▼
                   ┌──────────────┐
                   │ PostgreSQL   │
                   │  (Database)  │
                   └──────────────┘

                   ┌──────────────┐
                   │ Notifications│
                   │ (Email, Slack│
                   │  Telegram...) │
                   └──────────────┘

Documentation

For more information on using Healthchecks:

• Official Documentation
• GitHub Repository
• API Reference
• Integrations Guide
• Docker Hub
• Docker Compose Example

Support

For issues and questions:

• GitHub Issues
• Community Forum
• Discord Server

Upstream

GitHub Repository Official Website