diff --git a/Package-Workspace/Monitoring/healthchecks/.env.example b/Package-Workspace/Monitoring/healthchecks/.env.example new file mode 100644 index 0000000..82dc1b9 --- /dev/null +++ b/Package-Workspace/Monitoring/healthchecks/.env.example @@ -0,0 +1,26 @@ +# Healthchecks Cloudron Environment Configuration Example +# Copy this to .env and configure as needed + +# Django Configuration +SECRET_KEY=change-this-to-a-random-secret-key-in-production +ALLOWED_HOSTS=* +SITE_ROOT=https://your-app.cloudron.app + +# Database (Automatically configured by Cloudron PostgreSQL addon) +# CLOUDRON_POSTGRESQL_HOST=127.0.0.1 +# CLOUDRON_POSTGRESQL_PORT=5432 +# CLOUDRON_POSTGRESQL_DATABASE=healthchecks +# CLOUDRON_POSTGRESQL_USERNAME=hc +# CLOUDRON_POSTGRESQL_PASSWORD=database-password + +# Email Configuration (for sending alerts) +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 +DEFAULT_FROM_EMAIL=healthchecks@your-app.cloudron.app + +# Superuser Configuration (create admin account on first start) +SUPERUSER_EMAIL=admin@example.com +SUPERUSER_PASSWORD=admin-password-change-me diff --git a/Package-Workspace/Monitoring/healthchecks/CHANGELOG.md b/Package-Workspace/Monitoring/healthchecks/CHANGELOG.md new file mode 100644 index 0000000..2817d4e --- /dev/null +++ b/Package-Workspace/Monitoring/healthchecks/CHANGELOG.md @@ -0,0 +1,28 @@ +# Changelog + +## [3.12.0] - 2025-01-24 + +### Added +- Initial Cloudron package for Healthchecks +- Official Healthchecks Docker image wrapper +- Automatic PostgreSQL configuration via Cloudron addon +- Django migrations on startup +- Superuser creation support via environment variables +- Email configuration support +- Health check endpoint +- Documentation with usage examples +- Monitoring examples (cron, systemd, scripts, webhooks) + +### Features +- 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 diff --git a/Package-Workspace/Monitoring/healthchecks/CloudronManifest.json b/Package-Workspace/Monitoring/healthchecks/CloudronManifest.json new file mode 100644 index 0000000..f5b6f49 --- /dev/null +++ b/Package-Workspace/Monitoring/healthchecks/CloudronManifest.json @@ -0,0 +1,33 @@ +{ + "version": 1, + "manifestVersion": 2, + "type": "app", + "id": "io.cloudron.healthchecks", + "title": "Healthchecks", + "description": "Cron job monitoring service. Listens for HTTP requests and email messages (pings) from your cron jobs and sends alerts when pings are late.", + "author": "Healthchecks.io", + "website": "https://github.com/healthchecks/healthchecks", + "contactEmail": "cloudron@tsys.dev", + "tagline": "Cron job monitoring with alerting", + "version": "3.12.0", + "healthCheckPath": "/", + "httpPort": 8000, + "memoryLimit": 512, + "addons": { + "localstorage": true, + "postgresql": { + "version": "14" + } + }, + "tcpPorts": { + "HTTP_PORT": { + "description": "Healthchecks HTTP port", + "defaultValue": 8000 + } + }, + "mediaLinks": [ + "https://raw.githubusercontent.com/healthchecks/healthchecks/master/static/img/logo.png" + ], + "changelog": "Initial Cloudron package for Healthchecks", + "icon": "file://logo.png" +} diff --git a/Package-Workspace/Monitoring/healthchecks/Dockerfile b/Package-Workspace/Monitoring/healthchecks/Dockerfile new file mode 100644 index 0000000..98c31e0 --- /dev/null +++ b/Package-Workspace/Monitoring/healthchecks/Dockerfile @@ -0,0 +1,7 @@ +FROM healthchecks/healthchecks:latest + +# Cloudron: Copy start script (already executable from host) +COPY start.sh /app/start.sh + +# Start Healthchecks +CMD ["/app/start.sh"] diff --git a/Package-Workspace/Monitoring/healthchecks/README.md b/Package-Workspace/Monitoring/healthchecks/README.md new file mode 100644 index 0000000..1e633aa --- /dev/null +++ b/Package-Workspace/Monitoring/healthchecks/README.md @@ -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 ` +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/) diff --git a/Package-Workspace/Monitoring/healthchecks/logo.png b/Package-Workspace/Monitoring/healthchecks/logo.png new file mode 100644 index 0000000..b4ca910 Binary files /dev/null and b/Package-Workspace/Monitoring/healthchecks/logo.png differ diff --git a/Package-Workspace/Monitoring/healthchecks/start.sh b/Package-Workspace/Monitoring/healthchecks/start.sh new file mode 100755 index 0000000..d5522dc --- /dev/null +++ b/Package-Workspace/Monitoring/healthchecks/start.sh @@ -0,0 +1,65 @@ +#!/bin/bash + +set -e + +echo "Starting Healthchecks Cloudron package..." + +# Database connection from Cloudron +DB_NAME=${CLOUDRON_POSTGRESQL_DATABASE:-healthchecks} +DB_USER=${CLOUDRON_POSTGRESQL_USERNAME:-hc} +DB_PASSWORD=${CLOUDRON_POSTGRESQL_PASSWORD} +DB_HOST=${CLOUDRON_POSTGRESQL_HOST:-127.0.0.1} +DB_PORT=${CLOUDRON_POSTGRESQL_PORT:-5432} + +echo "Database host: $DB_HOST" +echo "Database port: $DB_PORT" +echo "Database name: $DB_NAME" + +# Wait for PostgreSQL to be ready +echo "Waiting for PostgreSQL to be ready..." +until PGPASSWORD=$DB_PASSWORD psql -h "$DB_HOST" -p "$DB_PORT" -U "$DB_USER" -d "$DB_NAME" -c '\q' 2>/dev/null; do + echo "PostgreSQL is unavailable - sleeping" + sleep 2 +done + +echo "PostgreSQL is ready!" + +# Django configuration +export DEBUG=False +export SECRET_KEY=${SECRET_KEY:-cloudron-secret-key-change-in-production} +export ALLOWED_HOSTS=${ALLOWED_HOSTS:-'*'} +export SITE_ROOT=${SITE_ROOT:-https://$CLOUDRON_APP_DOMAIN} +export EMAIL_HOST=${EMAIL_HOST:-} +export EMAIL_PORT=${EMAIL_PORT:-587} +export EMAIL_HOST_USER=${EMAIL_HOST_USER:-} +export EMAIL_HOST_PASSWORD=${EMAIL_HOST_PASSWORD:-} +export EMAIL_USE_TLS=${EMAIL_USE_TLS:-True} +export DEFAULT_FROM_EMAIL=${DEFAULT_FROM_EMAIL:-healthchecks@$CLOUDRON_APP_DOMAIN} + +# Database configuration +export DB=postgresql +export DB_HOST=$DB_HOST +export DB_NAME=$DB_NAME +export DB_USER=$DB_USER +export DB_PASSWORD=$DB_PASSWORD +export DB_PORT=$DB_PORT +export DB_CONN_MAX_AGE=60 + +# Run Django migrations +echo "Running Django migrations..." +python /opt/healthchecks/manage.py migrate --noinput + +# Collect static files +echo "Collecting static files..." +python /opt/healthchecks/manage.py collectstatic --noinput + +# Create superuser if specified +if [ -n "$SUPERUSER_EMAIL" ] && [ -n "$SUPERUSER_PASSWORD" ]; then + echo "Creating superuser..." + echo "from django.contrib.auth import get_user_model; User = get_user_model(); User.objects.create_superuser('$SUPERUSER_EMAIL', '', '$SUPERUSER_PASSWORD')" | \ + python /opt/healthchecks/manage.py shell || echo "Superuser may already exist" +fi + +# Start Healthchecks +echo "Starting Healthchecks..." +exec uwsgi /opt/healthchecks/docker/uwsgi.ini