blackoutsecure/dump978 repository overview

⁠docker-dump978

Containerized dump978⁠ for decoding 978 MHz UAT ADS-B with RTL-SDR or SoapySDR on Linux.

Sponsored and maintained by Blackout Secure⁠.

⁠Overview

This project packages upstream flightaware/dump978⁠ into a containerized build for decoding 978 MHz UAT ADS-B with RTL-SDR or SoapySDR on Linux.

Quick links:

• Docker Hub listing: blackoutsecure/dump978⁠
• Balena block listing: dump978 block on Balena Hub⁠
• GitHub repository: blackoutsecure/docker-dump978⁠
• Upstream application: flightaware/dump978⁠

⁠Table of Contents

• docker-dump978⁠
  • Overview⁠
  • Table of Contents⁠
  • Quick Start⁠
  • Image Availability⁠
  • About The dump978 Application⁠
  • Supported Architectures⁠
  • Usage⁠
    • docker-compose (recommended, click here for more info)⁠
    • docker-compose paired with readsb⁠
    • docker-cli (click here for more info)⁠
    • Balena Deployment⁠
  • Parameters⁠
    • Ports⁠
    • Environment Variables⁠
      • Feed Profile⁠
      • Core Settings⁠
      • SDR Advanced Tuning⁠
      • Location & Statistics⁠
      • faup978 FlightAware Reporter⁠
      • skyaware978 Tuning⁠
      • SkyAware Web UI Customization⁠
    • Storage Mounts⁠
  • Volume Details⁠
    • /config — Configuration & Persistence⁠
    • /run/dump978-fa — Decoder Output⁠
  • Configuration⁠
    • Feed Profiles⁠
    • dump978-fa Options⁠
    • skyaware978 Options⁠
    • faup978 Options (FlightAware Reporter)⁠
    • Custom Configuration via Volume Mount⁠
  • Application Setup⁠
    • SDR Device Access⁠
  • Troubleshooting⁠
    • No SDR device found⁠
    • No data / empty web UI⁠
    • Port conflict⁠
    • View logs⁠
    • Check service status⁠
    • Getting help⁠
  • Release & Versioning⁠
  • Support & Getting Help⁠
  • Sponsor & Credits⁠
  • References⁠
    • Project Resources⁠
    • Upstream & Related⁠
    • Technical Resources⁠
  • License⁠

⁠Quick Start

docker run -d \
  --name=dump978 \
  --restart unless-stopped \
  -e TZ=Etc/UTC \
  -e DUMP978_SDR=driver=rtlsdr \
  -e DUMP978_LAT=47.6062 \
  -e DUMP978_LON=-122.3321 \
  -p 8978:8978 \
  -p 30978:30978 \
  -p 30979:30979 \
  -v dump978-config:/config \
  -v /run/dump978-fa:/run/dump978-fa \
  --device /dev/bus/usb:/dev/bus/usb \
  blackoutsecure/dump978:latest

Access the SkyAware978 web UI at http://<host-ip>:8978/.

For compose files, balena, and more examples, see Usage⁠ below.

⁠Image Availability

Docker Hub (Recommended):

• All images published to Docker Hub⁠
• Simple pull command: docker pull blackoutsecure/dump978:latest
• Multi-arch support: amd64, arm64
• No registry prefix needed (defaults to Docker Hub)

# Pull latest
docker pull blackoutsecure/dump978

# Pull specific version
docker pull blackoutsecure/dump978:10.2

# Pull architecture-specific (rarely needed)
docker pull blackoutsecure/dump978:latest@amd64

⁠About The dump978 Application

dump978-fa⁠ is FlightAware's 978 MHz UAT (Universal Access Transceiver) decoder. It demodulates UAT signals from an RTL-SDR or other SoapySDR-compatible receiver and provides decoded ADS-B data as raw messages or JSON-formatted output on network ports. The companion skyaware978 writes JSON files suitable for the SkyAware web map.

Author and maintenance credits (upstream):

• Primary upstream maintainer: FlightAware⁠
• Original implementation: mutability/dump978⁠
• Upstream repository and documentation: flightaware/dump978⁠

⁠Supported Architectures

This image is published as a multi-arch manifest. Pulling blackoutsecure/dump978:latest retrieves the correct image for your host architecture.

The architectures supported by this image are:

⁠Usage

⁠docker-compose (recommended, click here for more info⁠)

---
services:
  dump978:
    image: blackoutsecure/dump978:latest
    container_name: dump978
    environment:
      - TZ=Etc/UTC
      - DUMP978_SDR=driver=rtlsdr
    volumes:
      - config:/config
      - dump978-run:/run/dump978-fa
    ports:
      - 8978:8978    # SkyAware978 Web UI (HTTP)
      - 30978:30978  # Raw UAT messages
      - 30979:30979  # Decoded JSON messages
    devices:
      - /dev/bus/usb:/dev/bus/usb
    cap_drop:
      - ALL
    cap_add:
      - CHOWN
      - DAC_OVERRIDE
      - FOWNER
      - SETUID
      - SETGID
    security_opt:
      - no-new-privileges:true
    tmpfs:
      - /tmp
      - /run:exec
    restart: unless-stopped

volumes:
  config:
  dump978-run:

⁠docker-compose paired with readsb

---
services:
  readsb:
    image: blackoutsecure/readsb:latest
    container_name: readsb
    environment:
      - TZ=Etc/UTC
    volumes:
      - readsb-config:/config
      - readsb-run:/run/readsb
    devices:
      - /dev/bus/usb:/dev/bus/usb
    tmpfs:
      - /tmp
      - /run:exec
    restart: unless-stopped

  dump978:
    image: blackoutsecure/dump978:latest
    container_name: dump978
    environment:
      - TZ=Etc/UTC
      - DUMP978_SDR=driver=rtlsdr
    volumes:
      - dump978-config:/config
      - dump978-run:/run/dump978-fa
    ports:
      - 8978:8978
      - 30978:30978
      - 30979:30979
    devices:
      - /dev/bus/usb:/dev/bus/usb
    cap_drop:
      - ALL
    cap_add:
      - CHOWN
      - DAC_OVERRIDE
      - FOWNER
      - SETUID
      - SETGID
    security_opt:
      - no-new-privileges:true
    tmpfs:
      - /tmp
      - /run:exec
    restart: unless-stopped

volumes:
  readsb-config:
  readsb-run:
  dump978-config:
  dump978-run:

⁠docker-cli (click here for more info⁠)

docker run -d \
  --name=dump978 \
  -e TZ=Etc/UTC \
  -e DUMP978_SDR=driver=rtlsdr \
  -p 8978:8978 \
  -p 30978:30978 \
  -p 30979:30979 \
  -v /path/to/dump978/config:/config \
  -v /run/dump978-fa:/run/dump978-fa \
  --device /dev/bus/usb:/dev/bus/usb \
  --restart unless-stopped \
  blackoutsecure/dump978:latest

⁠Balena Deployment

This image can be deployed to Balena-powered IoT devices using the included docker-compose.yml file (which contains the required Balena labels):

• Balena block listing: https://hub.balena.io/blocks/dump978⁠

balena push <your-app-slug>

For deployment via the web interface, use the deploy button in this repository. See Balena documentation⁠ for details.

⁠Parameters

⁠Ports

⁠Environment Variables

⁠Feed Profile

⁠Core Settings

⁠SDR Advanced Tuning

⁠Location & Statistics

⁠faup978 FlightAware Reporter

⁠skyaware978 Tuning

⁠SkyAware Web UI Customization

Settings can be configured via environment variables, or by placing a complete custom config.js file at /config/skyaware978-config.js (takes priority over env vars). The active feed profile⁠ sets default values for SKYAWARE_PAGE_NAME and SKYAWARE_SITE_NAME; explicit env vars override them.

⁠Storage Mounts

⁠Volume Details

The container uses two volumes:

⁠/config — Configuration & Persistence

• Purpose: Stores persistent configuration files (dump978-fa, skyaware978)
• Example: -v /path/to/dump978/config:/config or -v dump978-config:/config

⁠/run/dump978-fa — Decoder Output

• Purpose: Runtime output directory for dump978-fa data accessible by other containers
• Example: -v /run/dump978-fa:/run/dump978-fa or -v dump978-run:/run/dump978-fa

⁠Configuration

Environment variables are set using -e flags in docker run or the environment: section in docker-compose.

Configuration files are stored in /config inside the container. On first run, default configuration files are created at /config/dump978-fa and /config/skyaware978.

⁠Feed Profiles

Set DUMP978_PROFILE to switch between preconfigured defaults for different ADS-B networks. The profile controls branding, feeder behavior, and filtering — every default can still be overridden with explicit env vars.

Example — switch to FlightAware profile:

environment:
  DUMP978_PROFILE: "flightaware"
  DUMP978_FA_STATS_URL: "https://flightaware.com/adsb/stats/user/yourname"

Example — ADS-B Exchange profile (default):

environment:
  DUMP978_PROFILE: "adsbexchange"
  DUMP978_ADSBX_STATS_URL: "https://www.adsbexchange.com/myip/"

You can set both stats URLs and switch profiles at will — only the active profile's URL is used.

⁠dump978-fa Options

To select a specific RTL-SDR dongle by serial number: DUMP978_SDR=driver=rtlsdr,serial=01234567

⁠skyaware978 Options

⁠faup978 Options (FlightAware Reporter)

The faup978 binary re-encodes UAT messages into FlightAware's format for stats collection. It is enabled by default with the flightaware profile and disabled by default with the adsbexchange profile. Override with DUMP978_ENABLE_FAUP978.

⁠Custom Configuration via Volume Mount

You can supply custom config files via volume mounts:

volumes:
  - ./my-dump978-config:/config/dump978-fa:ro
  - ./my-skyaware978-config:/config/skyaware978:ro
  - ./my-skyaware-config.js:/config/skyaware978-config.js:ro

⁠Application Setup

The container runs four services under s6-overlay:

1. dump978-fa — the main 978 MHz UAT decoder that talks to the SDR hardware via SoapySDR, demodulates UAT data, and provides raw and JSON-decoded messages on TCP ports
2. skyaware978 — connects to dump978-fa and writes JSON files suitable for the SkyAware web map interface
3. nginx — serves the SkyAware978 HTML interface and live aircraft JSON data
4. faup978 (optional, profile-dependent) — re-encodes UAT messages and reports to FlightAware for stats collection. Enabled by default with the flightaware profile; override with DUMP978_ENABLE_FAUP978=true

⁠SDR Device Access

The container requires access to the USB SDR device. Pass --device /dev/bus/usb:/dev/bus/usb to grant USB access, or p