blackoutsecure/readsb repository overview

⁠blackoutsecure/readsb

Unofficial community image for readsb⁠, built with LinuxServer.io⁠ style container patterns (s6, hardened defaults, practical runtime options) for RTL-SDR ADS-B workloads. Sponsored and maintained by Blackout Secure⁠.

Links: Docker Hub⁠ · Balena block⁠ · GitHub⁠ · Upstream readsb⁠

⁠Table of Contents

• Quick Start⁠
• Image Availability⁠
• About The readsb Application⁠
• Supported Architectures⁠
• Usage⁠
  • Docker Compose⁠
  • Docker Compose (Network-only)⁠
  • Docker Compose (dump978 Sidecar)⁠
  • Docker CLI⁠
  • Balena Deployment⁠
• Parameters⁠
• Configuration⁠
• Application Setup⁠
• SDR Device Selection⁠
• Feed Profiles⁠
• Gain Control⁠
• Bias-T Power for Active Antennas⁠
• Advanced Tuning⁠
• Troubleshooting⁠
• Health Monitoring⁠
• Release & Versioning⁠
• Resources⁠
• License⁠

⁠Quick Start

5-minute RTL-SDR receiver setup:

docker run -d \
  --name=readsb \
  --restart unless-stopped \
  -e TZ=Etc/UTC \
  -e READSB_DEVICE_TYPE=rtlsdr \
  -p 30001:30001 \
  -p 30002:30002 \
  -p 30003:30003 \
  -p 30004:30004 \
  -p 30005:30005 \
  -p 30104:30104 \
  -v readsb-config:/config \
  -v readsb-json:/run/readsb \
  --device=/dev/bus/usb:/dev/bus/usb \
  --security-opt no-new-privileges:true \
  blackoutsecure/readsb:latest

Access live JSON output: docker exec readsb cat /run/readsb/aircraft.json | jq .

For compose files, balena, network-only mode, and more examples, see Usage⁠ below.

⁠Image Availability

Docker Hub (Recommended):

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

# Pull latest
docker pull blackoutsecure/readsb

# Pull specific version
docker pull blackoutsecure/readsb:1.2.3

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

⁠About The readsb Application

readsb⁠ is an ADS-B decoder often described upstream as an "ADS-B decoder swiss knife".

It is a detached fork lineage used by many ADS-B receivers and related tooling, with network outputs, JSON/API features, and broad SDR support used for local receivers and large-scale feed/aggregation workflows.

Author and maintenance credits (upstream):

• Primary upstream maintainer: wiedehopf⁠ (Matthias Wirth)
• Upstream credits/history lineage: antirez (original dump1090), Malcom Robb, mutability (dump1090-mutability / dump1090-fa), Mictronics (readsb fork), and wiedehopf (current fork)
• Upstream repository and documentation: wiedehopf/readsb⁠

⁠Supported Architectures

This image is published as a multi-arch manifest. Pulling blackoutsecure/readsb: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:
  readsb:
    image: blackoutsecure/readsb:latest
    container_name: readsb
    environment:
      - TZ=Etc/UTC
      - READSB_DEVICE_TYPE=rtlsdr
      - READSB_NET_BI_PORT=30004,30104  # Beast input ports
      - READSB_NET_BO_PORT=30005        # Beast output port
      # - READSB_BIASTEE=true          # enable for powered LNAs (e.g. SAWbird+)
      - LOG_LEVEL=info                 # debug | info | warn | error | fatal
    volumes:
      - /path/to/readsb/config:/config
      - /path/to/readsb/json:/run/readsb
    ports:
      - 30001:30001  # Raw protocol (TCP)
      - 30002:30002  # Raw protocol input (TCP)
      - 30003:30003  # SBS protocol (TCP)
      - 30004:30004  # Beast input (TCP)
      - 30005:30005  # Beast output (TCP)
      - 30104:30104  # Beast input (TCP)
    devices:
      - /dev/bus/usb:/dev/bus/usb
    security_opt:
      - no-new-privileges:true
    tmpfs:
      - /tmp
      - /run:exec
    restart: unless-stopped

⁠docker-compose with RTL-SDR over network (e.g., from a remote receiver)

---
services:
  readsb:
    image: blackoutsecure/readsb:latest
    container_name: readsb
    environment:
      - TZ=Etc/UTC
      - READSB_EXTRA_ARGS=--lon <longitude> --lat <latitude>
    volumes:
      - /path/to/readsb/config:/config
      - /path/to/readsb/json:/run/readsb
    ports:
      - 30001:30001
      - 30002:30002
      - 30003:30003
      - 30004:30004
      - 30005:30005
      - 30104:30104
    security_opt:
      - no-new-privileges:true
    tmpfs:
      - /tmp
      - /run:exec
    restart: unless-stopped

⁠docker-compose with dump978 sidecar (dual 1090/978 MHz, US only)

---
services:
  readsb:
    image: blackoutsecure/readsb:latest
    container_name: readsb
    environment:
      - TZ=Etc/UTC
      - READSB_DEVICE_TYPE=rtlsdr
      # - READSB_BIASTEE=true          # enable for powered LNAs (e.g. SAWbird+)
      - FEED_UAT_INPUT=dump978:30978
      # - READSB_DEVICE=00001090  # pin 1090 dongle by serial
    volumes:
      - readsb-config:/config
      - readsb-json:/run/readsb
    devices:
      - /dev/bus/usb:/dev/bus/usb
    ports:
      - 30001:30001
      - 30002:30002
      - 30003:30003
      - 30004:30004
      - 30005:30005
      - 30104:30104
    security_opt:
      - no-new-privileges:true
    tmpfs:
      - /tmp
      - /run:exec
    restart: unless-stopped
    depends_on:
      - dump978

  dump978:
    image: blackoutsecure/dump978:latest
    container_name: dump978
    environment:
      - TZ=Etc/UTC
      - DUMP978_SDR=driver=rtlsdr,serial=00000978
      - DUMP978_PROFILE=adsbexchange
    volumes:
      - dump978-config:/config
      - dump978-run:/run/dump978-fa
    ports:
      - 8978:8978
      - 30978:30978
      - 30979:30979
    devices:
      - /dev/bus/usb:/dev/bus/usb
    security_opt:
      - no-new-privileges:true
    tmpfs:
      - /tmp
      - /run:exec
    restart: unless-stopped

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

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

docker run -d \
  --name=readsb \
  -e TZ=Etc/UTC \
  -e READSB_DEVICE_TYPE=rtlsdr \
  -p 30001:30001 \
  -p 30002:30002 \
  -p 30003:30003 \
  -p 30004:30004 \
  -p 30005:30005 \
  -p 30104:30104 \
  -v /path/to/readsb/config:/config \
  -v /path/to/readsb/json:/run/readsb \
  --device=/dev/bus/usb:/dev/bus/usb \
  --security-opt no-new-privileges:true \
  --restart unless-stopped \
  blackoutsecure/readsb: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/2351129/readsb⁠

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

⁠Storage Mounts

⁠Devices

⁠Volume Details

The container uses two volumes for data persistence and output:

⁠/config — Configuration & Persistence

• Required: No (container runs without it, but state is lost on restart)
• Purpose: Stores persistent data including aircraft database cache and application state
• Contents:
  • aircraft.csv.gz (aircraft identification database)
  • Temporary caches and application state
  • Any custom configuration files
• Example: -v /path/to/readsb/config:/config or -v readsb-config:/config

⁠/run/readsb — JSON Output

• Required: No (but needed to access real-time ADS-B data)
• Purpose: Real-time JSON protocol output consumed by other applications and visualization tools
• Contents:
  • aircraft.json (current aircraft with positions and altitudes)
  • receiver.json (receiver stats and information)
  • Other protocol outputs
• Update frequency: Multiple times per second
• Example: -v /path/to/readsb/json:/run/readsb or -v readsb-json:/run/readsb

⁠Best Practices

• For persistence: Always use named volumes or host paths for /config to preserve aircraft database between container restarts
• For JSON access: Mount /run/readsb to a host path to query data from other containers or host processes
• Alternative (tmpfs): Can use tmpfs mounts for temp directories, but JSON output will be lost when container stops

⁠Volume Mount Examples

Named volumes (recommended for single-host deployments):

volumes:
  - config:/config
  - json:/run/readsb

Host paths (for direct file access):

volumes:
  - /var/lib/readsb/config:/config
  - /var/lib/readsb/json:/run/readsb

Accessing JSON data from host:

docker exec readsb cat /run/readsb/aircraft.json | jq '.aircraft | length'

⁠Configuration

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

⁠User / Group Identifiers

By default, this container runs as the LSIO abc user (non-root) for better security isolation. The abc user is created by the LinuxServer.io base image⁠ with UID/GID 911 and remapped at container start via PUID/PGID.

Non-root mode (default, recommended):

• readsb runs as the abc user by default
• RTL-SDR USB device permissions are automatically fixed during container init — no manual configuration needed
• Set PUID and PGID only if you need file ownership to match a specific host user

Root mode (fallback):

• Set READSB_USER=root if needed for other reasons
• USB permissions are handled automatically regardless of user

⁠Application Setup

The container runs readsb with network support and automatic RTL-SDR device detection by default.

⁠Key Features

• JSON Output: ADS-B data is output as JSON to /run/readsb/ and updated frequently
• RTL-SDR Support: USB devices are auto-detected when passed to the container; permissions are fixed automatically
• Aircraft Database: Includes tar1090 aircraft database⁠ for accurate identification
• Automatic Gain: readsb's built-in autogain (--gain auto) is enabled by default (READSB_AUTOGAIN=true) — adjusts gain at the IQ sample level every ~0.5s, in-process without restarts. Set READSB_AUTOGAIN=false to disable.
• Bias-T Power: Optional DC voltage on coax for active antennas with built-in LNAs (see Bias-T Power for Active Antennas⁠)
• Docker HEALTHCHECK: Built-in health monitoring — marks container unhealthy if aircraft.json stops updating
• Periodic Stats: Logs aircraft count, positions, and message totals every 2 minutes (configurable via STATS_LOG_INTERVAL). When adsbexchange is in FEED_PROFILES, also uploads RSSI/stats data to ADSBx every 5 seconds using the same UUID as the beast feed. Per-upload confirmations are debug-level.
• Log Verbosity: Set LOG_LEVEL to control log output: debug, info (default), warn, error, fatal
• Feed Status URLs: Init logs include verification URLs for each active feed profile
• RTL-SDR Tools: rtl_test, rtl_eeprom, and rtl_biast available inside the container for diagnostics, dongle tagging, and bias-T control

⁠Extra Arguments (READSB_EXTRA_ARGS)

Most readsb settings have dedicated READSB_* env vars (READSB_NET, READSB_DEVICE_TYPE, READSB_GAIN, READSB_AUTOGAIN, READSB_BIASTEE, READSB_NET_BI_PORT, etc.). Use READSB_EXTRA_ARGS for anything not covered by a dedicated variable — these are appended to the end of the command line after all env-var-driven options.

Examples:

# Frequency correction
-e READSB_EXTRA_ARGS="--freq-correction 10"

# Location and range
-e READSB_EXTRA_ARGS="--lat 51.5 --lon -0.1 --max-range 350"

# See autogain decisions in the log
-e READSB_EXTRA_ARGS="--gain auto-verbose"

# Multiple extra options
-e READSB_EXTRA_ARGS="--freq-correction 3 --max-range 300 --ppm 2"

For all available readsb options, see the readsb documentation⁠.

⁠JSON Output Files

• aircraft.json - Current aircraft data with positions, callsigns, and altitudes
• receiver.json - Statistics and receiver information

⁠Supported Modes

• Read-only filesystem: Supported when JSON and temp directories are mounted to volumes or tmpfs
• Non-root user: Supported by default — RTL-SDR USB permissions are fixed automatically during init

⁠SDR Device Selection

The container auto-detects RTL-SDR dongles at startup and assigns the 1090 MHz device automatically using the community serial-number convention.

Auto-detection (default):

• Single dongle: assumed to be 1090 MHz
• Multiple dongles: serial containing 978 or uat is identified as UAT (informational); first non-UAT dongle is assigned as 1090

Manual override:

Set READSB_DEVICE to a device index or serial number:

environment:
  - READSB_DEVICE=0          # by device index
  - READSB_DEVICE=00001090   # by serial number

UAT 978 MHz (US only):

readsb only decodes 1090 MHz. For 978 MHz UAT, run blackoutsecure/docker-dump978⁠ as a sidecar container and set FEED_UAT_INPUT=dump978:30978 to merge UAT aircraft into readsb's unified output. See the dump978 sidecar compose example⁠ above.

Tagging dongle serials:

rtl_eeprom -d 0 -s 00001090   # tag first dongle as 1090
rtl_eeprom -d 1 -s 00000978   # tag second dongle as UAT

The description above is a condensed version. View the full README on GitHub: https://github.com/blackoutsecure/docker-readsb/blob/3f3f30902a8daf30ba80d4f36a51877888128657/./README.md⁠