skyview/docs/CONFIGURATION.md

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

{
  "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.

{
  "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.

{
  "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

{
  "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.

{
  "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

{
  "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:

{
  "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.

{
  "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.

{
  "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

{
  "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

"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

"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

"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:

{
  "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:

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

Database Management Commands

Updating External Data Sources

# 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

# 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

# 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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

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