feat: Enhanced database status monitoring and configuration management #34
2 changed files with 1416 additions and 0 deletions
docs: Add comprehensive configuration documentation
- Create detailed CONFIGURATION.md covering all SkyView settings - Document external aviation data sources (OpenFlights, OurAirports) - Explain origin vs sources distinction for map center vs receivers - Include privacy controls, database optimization, and validation - Provide environment-specific configuration examples - Cover database management commands and troubleshooting 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
commit
55776939ae
708
debian/usr/share/doc/skyview-adsb/CONFIGURATION.md
vendored
Normal file
708
debian/usr/share/doc/skyview-adsb/CONFIGURATION.md
vendored
Normal file
|
|
@ -0,0 +1,708 @@
|
|||
# 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
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
708
docs/CONFIGURATION.md
Normal file
708
docs/CONFIGURATION.md
Normal file
|
|
@ -0,0 +1,708 @@
|
|||
# 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
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
Loading…
Add table
Add a link
Reference in a new issue