ADS-B Notifier watches live aircraft data near a configured home location and sends notifications when saved rules match. I built this app to run on my home Kubernetes cluster so I can watch military traffic, figure out what loud helicopters just flew over the house, and get warnings when cool planes fly over that I might want to step outside and photograph.
The project is organized as three deployable components:
- Worker: polls ADS-B data, evaluates rules, sends notifications, and writes runtime status.
- Configuration API: validates, persists, backs up, and serves configuration and worker status.
- Web UI: manages settings, notification providers, rules, live rule tests, and recent matches.
The app can run locally during development or as containers in Kubernetes. See Development Guide for setup, testing, container builds, and deployment commands.
- ✨ Features
- 🖥️ UI
- 🔔 Notification Providers
- 🏗️ Architecture
- 🗂️ Project Layout
- ⚙️ Configuration Overview
- 🗺️ Dashboard
- 🏷️ Versioning
- 🔒 Security Model
- 🛠️ Development
- 🙏 Credits and Disclaimer
- 🚧 Status
- Rule matching for tail numbers, callsigns, ICAO hex IDs, military aircraft, aircraft types, ADS-B categories, squawk codes, and circling behavior.
- Radius, minimum altitude, maximum altitude, stale-aircraft, and cooldown filters.
- Direct
aircraft.jsonfeed support for common dump1090/readsb/tar1090-style data. - Online source adapters for Airplanes.live and ADSB.lol.
- HTTP rate-limit handling with
Retry-Aftersupport and capped exponential backoff. - Military matching that understands readsb/Airplanes.live
dbFlags. - Optional TIS-B inclusion for military rules.
- Per-rule notification provider selection from globally enabled providers.
- Rule list search/filter and selected-rule bulk enable/disable actions.
- Live rule testing against the configured ADS-B source.
- Shared configuration validation for required sections, supported fields, home coordinates, rule shape, and notification providers.
- Provider-specific notification templates.
- Optional square alert snapshots in HTML email notifications.
- Worker status and recent match history.
- Dashboard map with home location, active rule radii, grouped recent matches, filtered recent match markers, selected-match highlighting, and Airplanes.live aircraft links.
- Recent match detail view with aircraft identifiers, notification status, position, movement details, and collapsible normalized payload.
- Light/dark UI modes, accent themes, themed logo assets, and theme-aware favicon.
The UI is broken into sections by tabs. Below are example screenshots of each tab showing the variety of themes.
Current notification support includes:
- SMTP email
- Pushover push notifications
- Twilio SMS
HTML email can embed themed branding and an optional square alert snapshot. The snapshot is centered on the configured home location and scaled so the matched rule radius fills the image. Map-backed snapshots cache raw tiles and theme-neutral rendered base maps by home location, radius, zoom, and tile source before drawing the theme and aircraft-specific overlays.
I found Twilio to be overly cumbersome, and not worth the cost for my use case. I am using email and Pushover notifications. I left Twilio support in the app in case I ever want to leverage SMS, but I doubt I will use it often.
ADS-B source (ADSB.lol, Airplanes.live, or local receiver aircraft.json)
|
v
Worker service
| evaluates rules
| sends notifications
| writes status
v
Shared config/status storage
^
|
Configuration API <---- Web UI
In Kubernetes, the API owns persistence of the live configuration file and serves a redacted configuration view to the UI. The worker reads the live configuration file from shared storage and writes status so the UI can display operational state and recent matches.
adsb_notifier/ Python package for worker, API, parsing, rules, status, and notifiers
tests/ Python test suite
ui/ Static web UI and no-cache development server
charts/adsb-notifier/ Helm chart for Kubernetes deployment
k8s/ Raw Kubernetes manifests
docs/ Development and operational documentation
config.example.json Example configuration
Makefile.example Example Make targets for local, test, build, and deploy commands
Configuration is JSON. The checked-in config.example.json shows the main structure:
home: latitude and longitude used for distance calculations and map centeringpoll_seconds: worker polling intervalprimary_retry_minutes: how long to stay on the backup ADS-B source before retrying the primarystale_aircraft_seconds: ignore aircraft that have not been seen recentlyrecent_matches_window_hours: how long recent matches remain in status historysource_health_trend_retention_hours: how long source health trend events remain in PVC-backed status historyadsb_source: primary ADS-B source configuration. The current example defaults to ADSB.lol; Airplanes.live and local receiver URL/file sources are supported. Legacyadsb_urlconfigs are still read, but new directaircraft.jsonendpoints should uselocal_receiverwithquery: "url".backup_adsb_source: optional backup source used when the primary is unavailable, rate limited, or returns stale datanotifications: provider configuration and templatesrules: alert rules
Secrets can be referenced as environment variables with env:NAME, for example:
"password": "env:SMTP_PASSWORD"Rules support these event values:
tailmilitaryaircraft_typesquawkcircling
Example rule:
{
"name": "Tail number near home",
"event": "tail",
"tail_numbers": ["N12345"],
"radius_miles": 25,
"cooldown_minutes": 60,
"notification_providers": ["pushover", "email"],
"exclusions": {
"tail_numbers": ["N99999"],
"hex_ids": [],
"callsigns": [],
"aircraft_types": [],
"categories": ["A7", "UNKNOWN"]
},
"quiet_hours": {
"enabled": true,
"start": "22:00",
"end": "07:00",
"time_zone": "America/Denver",
"suppress_providers": ["pushover", "twilio"]
}
}Quiet hours are configured per rule. When enabled, matching aircraft still appear in recent matches, but phone-style notifications such as Pushover and Twilio can be suppressed during the configured time window while email remains available through normal rule notification settings. Quiet-hour windows use the configured IANA timezone, such as America/Denver, so Kubernetes containers can run in UTC without changing the alert behavior.
Exclusions can be configured globally or per rule. They support tail numbers, ICAO hex IDs, callsigns, aircraft types, and ADS-B category values. Use UNKNOWN to exclude aircraft with missing category data. Excluded aircraft do not create recent matches or notifications.
The dashboard shows worker health, recent matches, and a map view. Recent matches include observed timestamps, aircraft metadata, notification provider selections, map positions when available, and Airplanes.live links.
The map is centered around the configured home location and can show:
- Home marker
- Active rule radii
- Recent alert markers
- Track direction hints
- Selected match highlighting
Repeated dashboard alerts are grouped by aircraft and rule so noisy repeat matches are easier to scan while the underlying recent match history still preserves each individual event.
Recent matches can be filtered by event, rule, provider, notification status, and aircraft text. Each row has a detail view for troubleshooting the normalized aircraft payload behind the alert. The detail view can export the selected recent match as API-backed JSON or CSV.
The project is currently in beta and uses SemVer-style 0.x.y versions, with explicit release-candidate builds like 0.x.0-rc.n before stable cuts like 0.x.0. The worker, API, UI, Helm chart, Python package, and container images share the project version during beta.
Use make release-rc from a clean worktree to prepare, build, push, deploy, and roll out the next release candidate. The target derives the next RC from the current project version, either from the latest numeric checkpoint to the next minor rc.1, or from one RC to the next.
Stable minor releases should also get GitHub-facing release notes. Draft them with make release-notes VERSION=0.4.0 PREVIOUS_VERSION=0.3.0 ROADMAP="ADSB-Notifier Roadmap v0.4.0" and polish the resulting file under docs/releases/ before publishing the GitHub Release. See Versioning and Promotion for the branch flow, image tag strategy, RC workflow, release notes, and promotion checklist.
ADS-B Notifier is designed for trusted local networks. The web UI and configuration API do not provide app-level authentication or authorization. Put it behind your existing local network controls, VPN, ingress restrictions, or reverse proxy protections if you expose it beyond a trusted LAN.
Notification secrets can be referenced through environment variables such as env:SMTP_PASSWORD, and the API redacts known secret fields before serving configuration to the UI.
See Development Guide for:
- Installing dependencies
- Running the API, UI, and worker locally
- Running tests
- Building container images
- Deploying with Helm
- Managing runtime secrets
ADS-B Notifier is an independent personal project and is not affiliated with, endorsed by, or sponsored by Airplanes.live, ADSB.lol, OpenStreetMap, Leaflet, Pushover, Twilio, or any aircraft tracking service or notification provider.
When configured to use Airplanes.live, aircraft data and aircraft detail links may come from Airplanes.live. Please be a good neighbor: follow their API guide and terms, keep polling reasonable, and remember that public access can change. If this project is useful to you, consider becoming an Airplanes.live feeder and contributing ADS-B coverage back to the community.
Dashboard maps and map-backed email snapshots can use OpenStreetMap tiles. OpenStreetMap attribution is displayed in the map UI and rendered into email snapshots.
This project is under active development. I do not expect it to be broadly useful, but I am sharing it in case another aviation nerd with a homelab finds the shape of it helpful.