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>
2026-02-04 13:55:57 -05:00
parent 9877a53291
commit 3aaf98267d
7 changed files with 462 additions and 0 deletions
--- a/Package-Workspace/Monitoring/healthchecks/.env.example
+++ 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
--- a/Package-Workspace/Monitoring/healthchecks/CHANGELOG.md
+++ 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
--- a/Package-Workspace/Monitoring/healthchecks/CloudronManifest.json
+++ 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"
+}
--- a/Package-Workspace/Monitoring/healthchecks/Dockerfile
+++ 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"]
--- a/Package-Workspace/Monitoring/healthchecks/README.md
+++ 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 <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/)
--- a/Package-Workspace/Monitoring/healthchecks/logo.png
+++ b/Package-Workspace/Monitoring/healthchecks/logo.png
--- a/Package-Workspace/Monitoring/healthchecks/start.sh
+++ 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