TSYSDevStack-SupportStack-Cloudron/Package-Workspace/Monitoring/healthchecks/README.md

# 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:
```bash
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:
```bash
# 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:
```bash
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
```bash
# Backup script with ping
0 2 * * * /usr/local/bin/backup.sh && curl -fsS https://your-app.cloudron.app/ping/uuid-1
```

### Systemd Service Monitoring
```ini
[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
```python
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:
```bash
# 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**:
```bash
# 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:
```bash
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:
```bash
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:
```bash
# 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](https://healthchecks.io/)
- [GitHub Repository](https://github.com/healthchecks/healthchecks)
- [API Reference](https://healthchecks.io/docs/api/)
- [Integrations Guide](https://healthchecks.io/docs/integrations/)
- [Docker Hub](https://hub.docker.com/r/healthchecks/healthchecks)
- [Docker Compose Example](https://github.com/healthchecks/healthchecks/tree/master/docker)

## Support

For issues and questions:
- [GitHub Issues](https://github.com/healthchecks/healthchecks/issues)
- [Community Forum](https://healthchecks.io/)
- [Discord Server](https://discord.gg/bn9VcsY)

## Upstream

[GitHub Repository](https://github.com/healthchecks/healthchecks)
[Official Website](https://healthchecks.io/)