# Cron Jobs Configuration Guide


**Last Updated:** 2025-11-20

This document explains how to set up automated scheduled tasks for documentation monitoring and maintenance.

## GitHub Actions Scheduled Workflows (Recommended)

The recommended approach is to use GitHub Actions scheduled workflows, which run automatically without requiring server access.

### Configuration

The scheduled workflow is configured in `.github/workflows/scheduled-documentation-checks.yml`.

### Schedule

- **Daily Health Check:** 9 AM UTC (runs every day)
- **Weekly Debt Scan:** 10 AM UTC (Mondays only)
- **Weekly Report:** 11 AM UTC (Mondays only)
- **Monthly Review:** 9 AM UTC (1st of month)

### Manual Triggering

All scheduled jobs can be manually triggered via GitHub Actions UI:

1. Go to Actions tab
2. Select "Scheduled Documentation Checks"
3. Click "Run workflow"

### Viewing Results

- Check GitHub Actions runs for execution logs
- Download artifacts for reports:
  - Daily health reports
  - Weekly debt reports
  - Weekly status reports
  - Monthly review reports

## Local Cron Jobs (Alternative)

If you prefer to run jobs locally or on a server, you can set up cron jobs.

### Setup Instructions

1. **Edit crontab:**

   ```bash
   crontab -e
   ```

2. **Add scheduled jobs:**

   ```bash
   # Daily health check at 9 AM (local time)
   0 9 * * * cd /path/to/landingpage && python3 scripts/monitor-documentation-health.py --all > /dev/null 2>&1

   # Weekly debt scan on Mondays at 10 AM
   0 10 * * 1 cd /path/to/landingpage && python3 scripts/track-documentation-debt.py --scan > /dev/null 2>&1

   # Weekly report on Mondays at 11 AM
   0 11 * * 1 cd /path/to/landingpage && python3 scripts/generate-weekly-report.py > /dev/null 2>&1

   # Monthly review on 1st of month at 9 AM
   0 9 1 * * cd /path/to/landingpage && python3 scripts/monthly-documentation-review.py > /dev/null 2>&1
   ```

3. **Save and exit**

### Email Alerts

To receive email alerts from cron jobs:

1. **Set up SMTP configuration** (see `docs/SETUP_GUIDE.md`)
2. **Enable email alerts:**

   ```bash
   export ENABLE_EMAIL_ALERTS=true
   export SMTP_HOST='smtp.gmail.com'
   export SMTP_PORT='587'
   export SMTP_USER='alerts@ordio.com'
   export SMTP_PASSWORD='your-app-password'
   export SMTP_FROM='noreply@ordio.com'
   ```

3. **Add to crontab:**
   ```bash
   # Include environment variables in cron job
   0 9 * * * cd /path/to/landingpage && export ENABLE_EMAIL_ALERTS=true && export SMTP_HOST='smtp.gmail.com' && ... && python3 scripts/monitor-documentation-health.py --all
   ```

### Logging

To log cron job output:

```bash
# Log to file
0 9 * * * cd /path/to/landingpage && python3 scripts/monitor-documentation-health.py --all >> /var/log/docs-health.log 2>&1

# Email output on errors
0 9 * * * cd /path/to/landingpage && python3 scripts/monitor-documentation-health.py --all || echo "Health check failed" | mail -s "Docs Health Check Failed" hady@ordio.com
```

## Verification

### Test Scheduled Workflows

1. **Manual trigger:** Use GitHub Actions UI to trigger workflow manually
2. **Check logs:** Review execution logs for errors
3. **Verify artifacts:** Download and review generated reports

### Test Cron Jobs

```bash
# Test command directly
cd /path/to/landingpage
python3 scripts/monitor-documentation-health.py --all

# Test cron syntax
crontab -l

# Check cron logs (Linux)
grep CRON /var/log/syslog

# Check cron logs (Mac)
grep cron /var/log/system.log
```

## Troubleshooting

### GitHub Actions Not Running

- Check repository settings: Actions must be enabled
- Verify workflow file syntax: Use YAML validator
- Check schedule syntax: Use [crontab.guru](https://crontab.guru) to validate

### Cron Jobs Not Running

- Verify cron service is running: `systemctl status cron` (Linux)
- Check cron logs for errors
- Verify file paths are absolute
- Check Python path: Use full path to python3
- Verify file permissions: Scripts must be executable

### Email Alerts Not Sending

- Check SMTP configuration: Verify environment variables
- Test SMTP connection: Use `telnet smtp.gmail.com 587`
- Review alert script logs: Check for SMTP errors
- Verify email address: Check `alert_email` in scripts

## Best Practices

1. **Use GitHub Actions** for automated workflows (no server required)
2. **Use local cron** only if you need server-specific features
3. **Monitor regularly:** Check logs weekly
4. **Set up alerts:** Configure email alerts for critical issues
5. **Review reports:** Weekly review of generated reports
6. **Update schedules:** Adjust timing based on team needs

## Schedule Recommendations

- **Daily:** Health checks (catch issues early)
- **Weekly:** Debt scans and reports (manage backlog)
- **Monthly:** Comprehensive reviews (strategic planning)
- **Quarterly:** Deep analysis (optimization)

## References

- GitHub Actions: [Scheduled Events](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#schedule)
- Cron Syntax: [crontab.guru](https://crontab.guru)
- SMTP Configuration: `docs/SETUP_GUIDE.md`