# HubSpot Sync Cron Installation - Instructions for Server Admin

**Last Updated:** 2026-03-06

**Purpose:** Instructions to provide to your server administrator or hosting support for installing the hourly HubSpot affiliate sync cron job.

## Quick Install (Recommended)

**On production server:**

```bash
cd /var/www/lexikon
crontab v2/cron/crontab-production.txt
```

This installs:
- **Hourly HubSpot sync** (runs at minute 0 of every hour)
- **Daily health check** (runs at 9:00 UTC)
- **Daily performance analysis** (runs at 2:00 AM)

## Manual Install (Alternative)

If you prefer to add manually or edit existing crontab:

```bash
# Edit crontab
crontab -e

# Add this line for hourly sync:
0 * * * * cd /var/www/lexikon && /usr/bin/php v2/cron/sync-affiliate-hubspot.php >> /var/log/affiliate-sync.log 2>&1

# Optional: Add daily health check (recommended):
0 9 * * * cd /var/www/lexikon && /usr/bin/php v2/scripts/affiliate/monitor-sync-health.php >> /var/log/affiliate-sync-health.log 2>&1
```

## Path Configuration

**Important:** Update paths if your production directory is different:

1. Replace `/var/www/lexikon` with your actual production path
2. Replace `/usr/bin/php` with your PHP CLI path (find with: `which php`)

## Verification

After installation, verify it's working:

```bash
# Check if cron is installed
php v2/scripts/affiliate/verify-cron-installed.php

# Or manually check crontab
crontab -l | grep sync-affiliate-hubspot
```

Expected output:
```
OK: Affiliate sync cron is installed
  Sync: 0 * * * * cd /var/www/lexikon && /usr/bin/php v2/cron/sync-affiliate-hubspot.php >> /var/log/affiliate-sync.log 2>&1
```

## Testing

Before relying on cron, test the sync manually:

```bash
cd /var/www/lexikon
php v2/cron/sync-affiliate-hubspot.php
```

Expected output:
```
[2026-03-06 12:00:00] [INFO] Starting HubSpot affiliate partner sync...
[2026-03-06 12:00:01] [INFO] Processing partner: AP-20260129-AD2F73
...
[2026-03-06 12:00:45] [INFO] Sync completed successfully
```

## What Gets Scheduled

- **Hourly sync:** `0 * * * *` - Runs at :00 of every hour (00:00, 01:00, 02:00, etc.)
- **Health check:** `0 9 * * *` - Runs daily at 9:00 UTC (optional but recommended)
- **Performance:** `0 2 * * *` - Runs daily at 2:00 AM (optional)

## Log Files

- **Sync logs:** `/var/log/affiliate-sync.log` (stdout/stderr from hourly sync)
- **Health check logs:** `/var/log/affiliate-sync-health.log` (daily health check output)

## Troubleshooting

### Cron Not Running

1. **Check cron service is running:**
   ```bash
   systemctl status cron  # Debian/Ubuntu
   # or
   systemctl status crond  # CentOS/RHEL
   ```

2. **Check cron logs:**
   ```bash
   grep CRON /var/log/syslog  # Debian/Ubuntu
   # or
   grep CRON /var/log/cron    # CentOS/RHEL
   ```

3. **Verify PHP CLI path:**
   ```bash
   which php
   /usr/bin/php --version
   ```

### Sync Not Updating Cache

1. **Check file permissions:**
   ```bash
   ls -la /var/www/lexikon/v2/data/
   # Cache directory should be writable
   ```

2. **Run sync manually and check for errors:**
   ```bash
   php v2/cron/sync-affiliate-hubspot.php
   ```

## Related Files

- **Crontab file:** `v2/cron/crontab-production.txt`
- **Sync script:** `v2/cron/sync-affiliate-hubspot.php`
- **Verification script:** `v2/scripts/affiliate/verify-cron-installed.php`
- **Documentation:** `docs/systems/affiliate/CRON_SYNC_RUNBOOK.md`