skyview/docs/CRON_SETUP.md

# SkyView Database Auto-Update with Cron

This guide explains how to set up automatic database updates for SkyView using cron jobs.

## Overview

SkyView can automatically update its aviation database from public domain sources using cron jobs. This ensures your aircraft callsign data stays current without manual intervention.

## Features

- ✅ **Auto-initialization**: Creates empty database if it doesn't exist
- ✅ **Safe sources only**: Updates only public domain data (no license issues)
- ✅ **Cron-friendly**: Proper logging and exit codes for automated execution
- ✅ **Lock file protection**: Prevents concurrent updates
- ✅ **Error handling**: Graceful failure handling with logging

## Quick Setup

### 1. Command Line Tool

The `skyview-data` command is designed to work perfectly with cron:

```bash
# Auto-initialize database and update safe sources
skyview-data update

# Check what's loaded
skyview-data status

# List available sources
skyview-data list
```

### 2. Cron Job Examples

#### Daily Update (Recommended)
```bash
# Add to crontab: crontab -e
# Update database daily at 3 AM
0 3 * * * /usr/bin/skyview-data update >/var/log/skyview-update.log 2>&1
```

#### Weekly Update
```bash
# Update database weekly on Sunday at 2 AM
0 2 * * 0 /usr/bin/skyview-data update >/var/log/skyview-update.log 2>&1
```

#### With Helper Script (Debian Package)
```bash
# Use the provided update script
0 3 * * * /usr/share/skyview/scripts/update-database.sh
```

### 3. System Service User

For Debian package installations, use the skyview service user:

```bash
# Edit skyview user's crontab
sudo crontab -u skyview -e

# Add daily update
0 3 * * * /usr/bin/skyview-data update
```

## Configuration

### Database Location

The tool automatically detects the database location:
- **System service**: `/var/lib/skyview/skyview.db`
- **User install**: `~/.local/share/skyview/skyview.db`  
- **Current directory**: `./skyview.db`

### Custom Database Path

```bash
# Specify custom database location
skyview-data -db /custom/path/skyview.db update
```

### Logging

For cron jobs, redirect output to log files:

```bash
# Basic logging
skyview-data update >> /var/log/skyview-update.log 2>&1

# With timestamps (using helper script)
/usr/share/skyview/scripts/update-database.sh
```

## Data Sources

### Safe Sources (Auto-Updated)

These sources are automatically included in `skyview-data update`:

- **OurAirports**: Public domain airport data
- **FAA Registry**: US aircraft registration (public domain)
- *(Additional safe sources as they become available)*

### License-Required Sources  

These require explicit acceptance and are NOT included in automatic updates:

- **OpenFlights**: AGPL-3.0 licensed airline/airport data

To include license-required sources:
```bash
# Interactive acceptance
skyview-data import openflights

# Force acceptance (for automation)
skyview-data update openflights --force
```

## Monitoring

### Check Update Status

```bash
# View database status
skyview-data status

# Example output:
# SkyView Database Status
# ======================  
# Database: /var/lib/skyview/skyview.db
# Size: 15.4 MB
# Modified: 2025-01-15T03:00:12Z
#
# 📦 Loaded Data Sources (2):
#    • OurAirports (Public Domain)  
#    • FAA Registry (Public Domain)
#
# 📊 Statistics:
#    Aircraft History: 1,234 records
#    Unique Aircraft: 567
#    Last 24h: 89 records
```

### Log Monitoring

```bash
# View recent updates
tail -f /var/log/skyview-update.log

# Check for errors
grep ERROR /var/log/skyview-update.log
```

## Troubleshooting

### Common Issues

#### Database Not Found
```
ERROR: failed to create database: no write permission
```
**Solution**: Ensure the skyview user has write access to `/var/lib/skyview/`

#### Network Errors
```
ERROR: failed to download data: connection timeout
```
**Solution**: Check internet connectivity and firewall settings

#### Lock File Issues  
```
ERROR: Another instance is already running
```
**Solution**: Wait for current update to finish, or remove stale lock file

### Manual Debugging

```bash
# Verbose output
skyview-data -v update

# Force update (skips locks)
skyview-data update --force

# Reset database
skyview-data reset --force
```

## Advanced Configuration

### Custom Update Script

Create your own update script with custom logic:

```bash
#!/bin/bash
# custom-update.sh

# Only update if database is older than 7 days
if [ "$(find /var/lib/skyview/skyview.db -mtime +7)" ]; then
    skyview-data update
    systemctl reload skyview  # Reload SkyView after update
fi
```

### Integration with SkyView Service

```bash
# Reload SkyView after database updates
skyview-data update && systemctl reload skyview
```

### Backup Before Updates

```bash
#!/bin/bash
# backup-and-update.sh

DB_PATH="/var/lib/skyview/skyview.db"
BACKUP_DIR="/var/backups/skyview"

# Create backup
mkdir -p "$BACKUP_DIR"
cp "$DB_PATH" "$BACKUP_DIR/skyview-$(date +%Y%m%d).db"

# Keep only last 7 backups
find "$BACKUP_DIR" -name "skyview-*.db" -type f -mtime +7 -delete

# Update database
skyview-data update
```

## Security Considerations

### File Permissions

```bash
# Secure database directory
sudo chown skyview:skyview /var/lib/skyview
sudo chmod 755 /var/lib/skyview
sudo chmod 644 /var/lib/skyview/skyview.db
```

### Network Security

- Updates only download from trusted sources (GitHub, government sites)
- All downloads use HTTPS
- No sensitive data is transmitted
- Local processing only

### Resource Limits

```bash
# Limit resources in cron (optional)
0 3 * * * timeout 30m nice -n 10 skyview-data update
```

This setup ensures your SkyView installation maintains up-to-date aviation data automatically while respecting all license requirements and security best practices.