# SkyView Configuration Guide

This document provides comprehensive configuration options for SkyView, including server settings, data sources, database management, and external aviation data integration.

## Configuration File Format

SkyView uses JSON configuration files. The default locations are:
- **System service**: `/etc/skyview-adsb/config.json`
- **User mode**: `~/.config/skyview/config.json`
- **Current directory**: `./config.json`
- **Custom path**: Specify with `-config path/to/config.json`

## Complete Configuration Example

```json
{
  "server": {
    "host": "",
    "port": 8080
  },
  "sources": [
    {
      "id": "primary",
      "name": "Primary Site",
      "host": "localhost",
      "port": 30005,
      "format": "beast",
      "latitude": 51.4700,
      "longitude": -0.4600,
      "altitude": 50.0,
      "enabled": true
    }
  ],
  "origin": {
    "latitude": 51.4700,
    "longitude": -0.4600,
    "name": "Control Tower"
  },
  "settings": {
    "history_limit": 1000,
    "stale_timeout": 60,
    "update_rate": 1
  },
  "database": {
    "path": "",
    "max_history_days": 7,
    "backup_on_upgrade": true,
    "max_open_conns": 10,
    "max_idle_conns": 5
  },
  "callsign": {
    "enabled": true,
    "cache_hours": 24,
    "privacy_mode": false,
    "sources": {
      "openflights_airlines": {
        "enabled": true,
        "priority": 1
      },
      "openflights_airports": {
        "enabled": true,
        "priority": 2
      },
      "ourairports": {
        "enabled": true,
        "priority": 3
      }
    }
  }
}
```

## Configuration Sections

### Server Configuration

Controls the web server and API endpoints.

```json
{
  "server": {
    "host": "",
    "port": 8080
  }
}
```

#### Options

- **`host`** (string): Interface to bind to
  - `""` or `"0.0.0.0"` = All interfaces (default)
  - `"127.0.0.1"` = Localhost only (IPv4)
  - `"::1"` = Localhost only (IPv6)
  - `"192.168.1.100"` = Specific interface

- **`port`** (integer): TCP port for web interface
  - Default: `8080`
  - Valid range: `1-65535`
  - Ports below 1024 require root privileges

### ADS-B Data Sources

Configures connections to dump1090/readsb receivers.

```json
{
  "sources": [
    {
      "id": "primary",
      "name": "Primary Site",
      "host": "localhost",
      "port": 30005,
      "format": "beast",
      "latitude": 51.4700,
      "longitude": -0.4600,
      "altitude": 50.0,
      "enabled": true
    }
  ]
}
```

#### Source Options

- **`id`** (string, required): Unique identifier for this source
- **`name`** (string, required): Human-readable name displayed in UI
- **`host`** (string, required): Hostname or IP address of receiver
- **`port`** (integer, required): TCP port of receiver
- **`format`** (string, optional): Data format
  - `"beast"` = Beast binary format (port 30005, default)
  - `"vrs"` = VRS JSON format (port 33005)
- **`latitude`** (number, required): Receiver latitude in decimal degrees
- **`longitude`** (number, required): Receiver longitude in decimal degrees  
- **`altitude`** (number, optional): Receiver altitude in meters above sea level
- **`enabled`** (boolean): Enable/disable this source (default: `true`)

#### Multiple Sources Example

```json
{
  "sources": [
    {
      "id": "site1",
      "name": "North Site",
      "host": "192.168.1.100",
      "port": 30005,
      "latitude": 51.50,
      "longitude": -0.46,
      "enabled": true
    },
    {
      "id": "site2",
      "name": "South Site (VRS)",
      "host": "192.168.1.101",
      "port": 33005,
      "format": "vrs",
      "latitude": 51.44,
      "longitude": -0.46,
      "enabled": true
    }
  ]
}
```

### Map Origin Configuration

Sets the default map center and reference point for the web interface. This is **different** from the ADS-B receiver locations defined in `sources`.

```json
{
  "origin": {
    "latitude": 51.4700,
    "longitude": -0.4600,
    "name": "Control Tower"
  }
}
```

#### Purpose and Usage

The **`origin`** defines where the map centers when users first load the web interface:

- **Map Center**: Initial view focus when loading the web interface
- **Reference Point**: Visual "home" location for navigation
- **User Experience**: Where operators expect to see coverage area
- **Reset Target**: Where "Reset to Origin" button returns the map view

This is **separate from** the `sources` coordinates, which define:
- Physical ADS-B receiver locations for signal processing
- Multi-source data fusion calculations
- Coverage area computation
- Signal strength weighting

#### Options

- **`latitude`** (number, required): Center latitude in decimal degrees
- **`longitude`** (number, required): Center longitude in decimal degrees
- **`name`** (string, optional): Display name for the origin point (shown in UI)

#### Example: Multi-Site Configuration

```json
{
  "origin": {
    "latitude": 51.4700,
    "longitude": -0.4600,
    "name": "London Control Center"
  },
  "sources": [
    {
      "id": "north",
      "name": "North Site",
      "latitude": 51.5200,
      "longitude": -0.4600
    },
    {
      "id": "south",
      "name": "South Site", 
      "latitude": 51.4200,
      "longitude": -0.4600
    }
  ]
}
```

In this configuration:
- **Map centers** on the Control Center for optimal viewing
- **Two receivers** located north and south provide coverage
- **Users see** the control area as the focal point
- **System uses** both receiver locations for signal processing

#### Single-Site Simplification

For single receiver deployments, origin and source coordinates are typically the same:

```json
{
  "origin": {
    "latitude": 51.4700,
    "longitude": -0.4600,
    "name": "Primary Site"
  },
  "sources": [
    {
      "id": "primary",
      "name": "Primary Receiver",
      "latitude": 51.4700,
      "longitude": -0.4600
    }
  ]
}
```

### General Settings

Global application behavior settings.

```json
{
  "settings": {
    "history_limit": 1000,
    "stale_timeout": 60,
    "update_rate": 1
  }
}
```

#### Options

- **`history_limit`** (integer): Maximum aircraft position history points per aircraft
  - Default: `1000`
  - Higher values = longer trails, more memory usage
  - `0` = No history limit

- **`stale_timeout`** (integer): Seconds before aircraft is considered stale/inactive
  - Default: `60` seconds
  - Range: `10-600` seconds

- **`update_rate`** (integer): WebSocket update rate in seconds
  - Default: `1` second
  - Range: `1-10` seconds
  - Lower values = more responsive, higher bandwidth

### Database Configuration

Controls SQLite database storage and performance.

```json
{
  "database": {
    "path": "",
    "max_history_days": 7,
    "backup_on_upgrade": true,
    "max_open_conns": 10,
    "max_idle_conns": 5
  }
}
```

#### Options

- **`path`** (string): Database file path
  - `""` = Auto-resolve to system appropriate location
  - Custom path: `"/var/lib/skyview-adsb/skyview.db"`
  - Relative path: `"./data/skyview.db"`

- **`max_history_days`** (integer): Aircraft history retention in days
  - Default: `7` days
  - `0` = Keep all history (unlimited)
  - Range: `1-365` days

- **`backup_on_upgrade`** (boolean): Create backup before schema upgrades
  - Default: `true`
  - Recommended to keep enabled for safety

- **`max_open_conns`** (integer): Maximum concurrent database connections
  - Default: `10`
  - Range: `1-100`

- **`max_idle_conns`** (integer): Maximum idle database connections in pool
  - Default: `5`
  - Range: `1-50`
  - Should be ≤ max_open_conns

## External Aviation Data Sources

SkyView can enhance aircraft data using external aviation databases. This section configures callsign enhancement and airline/airport lookup functionality.

### Callsign Enhancement Configuration

```json
{
  "callsign": {
    "enabled": true,
    "cache_hours": 24,
    "privacy_mode": false,
    "sources": {
      "openflights_airlines": {
        "enabled": true,
        "priority": 1
      },
      "openflights_airports": {
        "enabled": true,
        "priority": 2
      },
      "ourairports": {
        "enabled": true,
        "priority": 3
      }
    }
  }
}
```

#### Main Callsign Options

- **`enabled`** (boolean): Enable callsign enhancement features
  - Default: `true`
  - Set to `false` to disable all callsign lookups

- **`cache_hours`** (integer): Hours to cache lookup results
  - Default: `24` hours
  - Range: `1-168` hours (1 hour to 1 week)

- **`privacy_mode`** (boolean): Disable all external data requests
  - Default: `false`
  - `true` = Local-only operation (no network requests)
  - `false` = Allow external data loading

### Available External Data Sources

SkyView supports three external aviation data sources:

#### 1. OpenFlights Airlines Database

- **Content**: Global airline information with ICAO/IATA codes, callsigns, and country data
- **Records**: ~6,162 airlines worldwide
- **License**: AGPL-3.0 (runtime consumption allowed)
- **Source**: https://openflights.org/data.html
- **Updates**: Downloads latest data automatically

```json
"openflights_airlines": {
  "enabled": true,
  "priority": 1
}
```

#### 2. OpenFlights Airports Database

- **Content**: Global airport data with coordinates, codes, and basic metadata
- **Records**: ~7,698 airports worldwide
- **License**: AGPL-3.0 (runtime consumption allowed)
- **Source**: https://openflights.org/data.html
- **Updates**: Downloads latest data automatically

```json
"openflights_airports": {
  "enabled": true,
  "priority": 2
}
```

#### 3. OurAirports Database

- **Content**: Comprehensive airport database with detailed geographic and operational metadata
- **Records**: ~83,557 airports worldwide (includes small airfields)
- **License**: Public Domain (CC0)
- **Source**: https://ourairports.com/data/
- **Updates**: Downloads latest data automatically

```json
"ourairports": {
  "enabled": true,
  "priority": 3
}
```

#### Source Configuration Options

- **`enabled`** (boolean): Enable/disable this specific data source
- **`priority`** (integer): Processing priority (lower number = higher priority)

**Note**: License information and consent requirements are handled automatically by the system. All currently available data sources are safe for automatic loading without explicit consent.

### Data Loading Performance

When all sources are enabled, expect the following performance:

- **OpenFlights Airlines**: 6,162 records in ~350ms
- **OpenFlights Airports**: 7,698 records in ~640ms  
- **OurAirports**: 83,557 records in ~2.2s
- **Total**: 97,417 records in ~3.2s

## Privacy and Security Settings

### Privacy Mode

Enable privacy mode to disable all external data requests:

```json
{
  "callsign": {
    "privacy_mode": true,
    "sources": {
      "openflights_airlines": {
        "enabled": false
      },
      "openflights_airports": {
        "enabled": false
      },
      "ourairports": {
        "enabled": false
      }
    }
  }
}
```

#### Privacy Mode Features

- **No External Requests**: Completely disables all external data loading
- **Local-Only Operation**: Uses only embedded data and local cache
- **Air-Gapped Compatible**: Suitable for isolated networks
- **Compliance**: Meets strict privacy requirements

### Selective Source Control

Enable only specific data sources:

```json
{
  "callsign": {
    "sources": {
      "openflights_airlines": {
        "enabled": true
      },
      "openflights_airports": {
        "enabled": false
      },
      "ourairports": {
        "enabled": false
      }
    }
  }
}
```

## Database Management Commands

### Updating External Data Sources

```bash
# Update all enabled external data sources
skyview-data -config /path/to/config.json update

# List available data sources
skyview-data -config /path/to/config.json list

# Check database status and loaded sources
skyview-data -config /path/to/config.json status
```

### Database Optimization

```bash
# Optimize database storage efficiency
skyview-data -config /path/to/config.json optimize

# Check optimization statistics only
skyview-data -config /path/to/config.json optimize --stats-only

# Force optimization without prompts
skyview-data -config /path/to/config.json optimize --force
```

## Configuration Validation

### Validating Configuration

```bash
# Test configuration file syntax
skyview -config config.json -test

# Verify data source connectivity
skyview-data -config config.json list
```

### Common Configuration Errors

#### JSON Syntax Errors
```
Error: invalid character '}' looking for beginning of object key string
```
**Solution**: Check for trailing commas, missing quotes, or bracket mismatches.

#### Invalid Data Types
```
Error: json: cannot unmarshal string into Go struct field
```
**Solution**: Ensure numbers are not quoted, booleans use true/false, etc.

#### Missing Required Fields
```
Error: source 'primary' missing required field: latitude
```
**Solution**: Add all required fields for each configured source.

### Minimal Configuration

For basic operation without external data sources:

```json
{
  "server": {
    "host": "",
    "port": 8080
  },
  "sources": [
    {
      "id": "primary",
      "name": "Local Receiver",
      "host": "localhost",
      "port": 30005,
      "latitude": 51.4700,
      "longitude": -0.4600,
      "enabled": true
    }
  ],
  "settings": {
    "history_limit": 1000,
    "stale_timeout": 60,
    "update_rate": 1
  }
}
```

### Full-Featured Configuration

For complete functionality with all external data sources:

```json
{
  "server": {
    "host": "",
    "port": 8080
  },
  "sources": [
    {
      "id": "primary",
      "name": "Primary Site",
      "host": "localhost",
      "port": 30005,
      "latitude": 51.4700,
      "longitude": -0.4600,
      "altitude": 50.0,
      "enabled": true
    }
  ],
  "origin": {
    "latitude": 51.4700,
    "longitude": -0.4600,
    "name": "Control Tower"
  },
  "settings": {
    "history_limit": 4000,
    "stale_timeout": 60,
    "update_rate": 1
  },
  "database": {
    "path": "",
    "max_history_days": 7,
    "backup_on_upgrade": true,
    "max_open_conns": 10,
    "max_idle_conns": 5
  },
  "callsign": {
    "enabled": true,
    "cache_hours": 24,
    "privacy_mode": false,
    "sources": {
      "openflights_airlines": {
        "enabled": true,
        "priority": 1
      },
      "openflights_airports": {
        "enabled": true,
        "priority": 2
      },
      "ourairports": {
        "enabled": true,
        "priority": 3
      }
    }
  }
}
```

This configuration enables all SkyView features including multi-source ADS-B data fusion, comprehensive aviation database integration, and database optimization.

## Environment-Specific Examples

### Production System Service

Configuration for systemd service deployment:

```json
{
  "server": {
    "host": "0.0.0.0",
    "port": 8080
  },
  "database": {
    "path": "/var/lib/skyview-adsb/skyview.db",
    "max_history_days": 30,
    "backup_on_upgrade": true
  },
  "callsign": {
    "enabled": true,
    "privacy_mode": false
  }
}
```

### Development/Testing

Configuration for development use:

```json
{
  "server": {
    "host": "127.0.0.1",
    "port": 3000
  },
  "database": {
    "path": "./dev-skyview.db",
    "max_history_days": 1
  },
  "settings": {
    "history_limit": 100,
    "update_rate": 1
  }
}
```

### Air-Gapped/Secure Environment

Configuration for isolated networks:

```json
{
  "callsign": {
    "enabled": true,
    "privacy_mode": true,
    "sources": {
      "openflights_airlines": {
        "enabled": false
      },
      "openflights_airports": {
        "enabled": false
      },
      "ourairports": {
        "enabled": false
      }
    }
  }
}
```