olemd/skyview
1
0
Fork 0
Code Issues 12 Pull requests Projects Releases 11 Packages Wiki Activity Actions
skyview/docs/CONFIGURATION.md
Ole-Morten Duesund 55776939ae 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>
2025-08-31 19:40:29 +02:00

708 lines
No EOL
15 KiB
Markdown
Raw Blame History

# 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
}
}
}
}
```
Reference in a new issue View git blame Copy permalink