feat: add Healthchecks Cloudron package (Monitoring)
- Create Dockerfile wrapping official Healthchecks image - Add CloudronManifest.json with PostgreSQL addon - Create start.sh script with PostgreSQL wait and Django migrations - Include README.md with comprehensive monitoring documentation - Add .env.example for environment configuration - Add CHANGELOG.md for version tracking - Add logo.png (Healthchecks branding) Healthchecks is a cron job monitoring service that listens for HTTP requests and email messages (pings) from your cron jobs and sends alerts when pings are late. Package includes: - Official Healthchecks Docker image wrapper (105MB) - Cloudron PostgreSQL addon for Django database - Automatic database migrations on startup - Superuser creation via environment variables - Email configuration support for alerts - Comprehensive documentation with monitoring examples - Examples for cron, systemd, scripts, and webhook monitoring Features supported: - Cron job monitoring via HTTP pings - 25+ notification integrations (Email, SMS, Slack, Telegram, Matrix, etc.) - Live-updating web dashboard - Status badges for public monitoring - Team management (projects, team members, read-only access) - Monthly email reports - WebAuthn 2FA support - Tag-based organization - Project grouping - Detailed event logs - Grace time configuration - Cron expression support Environment variables: - SECRET_KEY: Django secret key - ALLOWED_HOSTS: Allowed hosts (default: *) - SITE_ROOT: Site root URL - EMAIL_HOST/PORT/USER/PASSWORD: SMTP configuration - SUPERUSER_EMAIL/PASSWORD: Admin account creation Ports: - 8000: Main HTTP port (web interface and API) 💘 Generated with Crush Assisted-by: GLM-4.7 via Crush <crush@charm.land>
This commit is contained in:
303
Package-Workspace/Monitoring/healthchecks/README.md
Normal file
303
Package-Workspace/Monitoring/healthchecks/README.md
Normal file
@@ -0,0 +1,303 @@
|
||||
# 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/)
|
||||
Reference in New Issue
Block a user