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.

Important

This repository is not an official LinuxServer.io image release. Want to help make it an officially supported LinuxServer.io Community image? Add your support in linuxserver/discussions/108.

Overview

This project packages upstream wiedehopf/readsb into an easy-to-run, LinuxServer.io-style container image with practical defaults for ADS-B receivers, JSON/network outputs, and RTL-SDR hardware access.

Quick links:

Docker Hub listing: blackoutsecure/readsb
Balena block listing: readsb block on Balena Hub
GitHub repository: blackoutsecure/docker-readsb
Upstream application: wiedehopf/readsb

Quick Start

5-minute RTL-SDR receiver setup:

docker run -d \
  --name=readsb \
  --restart unless-stopped \
  -e TZ=Etc/UTC \
  -e READSB_ARGS="--net --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 \
  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:

Architecture	Tag
x86-64	amd64-latest
arm64	arm64v8-latest

Usage

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

---
services:
  readsb:
    image: blackoutsecure/readsb:latest
    container_name: readsb
    environment:
      - TZ=Etc/UTC
      - READSB_ARGS=--net --device-type rtlsdr
    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 protocol (TCP)
      - 30005:30005  # Beast input (TCP)
      - 30104:30104  # JSON protocol (TCP)
    devices:
      - /dev/bus/usb:/dev/bus/usb
    restart: unless-stopped
    tmpfs:
      - /tmp
      - /run

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_USER=root
      - READSB_ARGS=--net --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
    restart: unless-stopped
    read_only: false
    tmpfs:
      - /tmp
      - /run

docker-cli (click here for more info)

docker run -d \
  --name=readsb \
  -e TZ=Etc/UTC \
  -e READSB_ARGS="--net --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 \
  --restart unless-stopped \
  blackoutsecure/readsb:latest

Balena Deployment

This image can be deployed to Balena-powered IoT devices using the included balena-compose.yml file:

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

Parameter	Function
`-p 30001:30001`	Raw protocol output (TCP)
`-p 30002:30002`	Raw protocol input (TCP)
`-p 30003:30003`	SBS protocol compatible output (TCP)
`-p 30004:30004`	Beast protocol output (TCP)
`-p 30005:30005`	Beast protocol input (TCP)
`-p 30104:30104`	JSON protocol output (TCP)

Environment Variables

Parameter	Function	Required
`-e TZ=Etc/UTC`	Timezone (TZ database)	Optional
`-e READSB_ARGS=`	Additional arguments for readsb	Optional
`-e PUID=911`	User ID for non-root operation	Optional
`-e PGID=911`	Group ID for non-root operation	Optional

Storage Mounts

Parameter	Function	Required
`-v /config`	Configuration and persistent data	Recommended
`-v /run/readsb`	JSON output directory	Recommended

Devices

Parameter	Function	Required
`--device=/dev/bus/usb:/dev/bus/usb`	RTL-SDR USB device access	Required (for RTL-SDR local RX)

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 root for best USB RTL-SDR device compatibility.

Root mode (default):

No PUID or PGID needed
RTL-SDR USB access works out-of-the-box

Non-root mode (advanced):

Set READSB_USER to your username
Provide matching PUID and PGID values
Defaults to 911:911 if omitted
RTL-SDR device access requires proper permissions

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
Aircraft Database: Includes tar1090 aircraft database for accurate identification
Automatic Gain Control: Enabled by default for rtlsdr devices (configurable via READSB_ARGS)

Customizing READSB_ARGS

The READSB_ARGS environment variable allows you to customize readsb behavior. By default (for rtlsdr devices), automatic gain control is enabled.

Common examples:

# RTL-SDR with default automatic gain
-e READSB_ARGS="--net --device-type rtlsdr"

# Network-only mode (no local RTL-SDR)
-e READSB_ARGS="--net --lat 51.5 --lon -0.1"

# Fixed gain setting (overrides automatic)
-e READSB_ARGS="--net --device-type rtlsdr --gain 35 --freq-correction 10"

# Location-aware with max range
-e READSB_ARGS="--net --device-type rtlsdr --lat 51.5 --lon -0.1 --max-range 350"

For all available 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 via READSB_USER (requires device permission setup for RTL-SDR access)

Troubleshooting

Container won't start or exits immediately

Check logs:

docker logs readsb
docker logs readsb --tail 50 -f  # Follow last 50 lines

Common causes:

USB device not found: Verify RTL-SDR dongle is connected and restart container
Permission denied on /dev/bus/usb: Container may need elevated privileges or device permissions
Configuration error: Check READSB_ARGS syntax against Customizing READSB_ARGS

No aircraft data appearing

Verify connectivity:

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

If count is 0:

Check RTL-SDR device: docker exec readsb rtl_test -t
Verify antenna is connected and positioned properly
Try manual gain: Set --gain 35 (or other value 0-49) if auto-gain isn't performing well
Look for RF interference: Try a different location or antenna orientation

JSON output not updating

Check if readsb is running:

docker exec readsb ps aux | grep readsb

Verify write permissions:

docker exec readsb ls -la /run/readsb/

JSON directory should be writable by the container user.

High CPU usage or memory growth

Profile the container:

docker stats readsb --no-stream

Troubleshooting steps:

Reduce JSON output frequency: Add --write-json-every 5 (updates every 5 seconds instead of 1)
Check for decode storms: Monitor aircraft count with watch 'docker exec readsb jq .aircraft.length /run/readsb/aircraft.json'
Restart container: docker restart readsb

Device permission errors (non-root mode)

If running with READSB_USER set to a non-root user:

# Find the numeric user/group ID
docker exec readsb id

# Grant USB access to the group (host-side)
sudo usermod -a -G plugdev <username>

Then restart container with proper PUID and PGID environment variables.

Port conflicts

If ports are already in use, map to different host ports:

docker run ... \
  -p 30011:30001 \
  -p 30012:30002 \
  -p 30013:30003 \
  ...

Then update client connections to use the new ports.

Getting help

Check upstream readsb documentation
Review container logs: docker logs -f readsb
Open an issue on GitHub

Release & Versioning

This project uses semantic versioning:

Releases published on GitHub Releases
Multi-arch images (amd64, arm64v8) built automatically
Docker Hub tags: version-specific, latest, and architecture-specific

Update to latest:

docker pull blackoutsecure/readsb:latest
docker-compose up -d  # if using compose

Check image version:

docker inspect -f '{{ index .Config.Labels "build_version" }}' blackoutsecure/readsb:latest

Support & Getting Help

❓ Questions: GitHub Issues
🐛 Bug Reports: Include Docker version, container logs, and reproduction steps
📖 Upstream Documentation: readsb on GitHub
💬 Community: LinuxServer.io Discord

Get help:

docker logs readsb                          # View container logs
docker exec -it readsb /bin/bash           # Access container shell
docker inspect blackoutsecure/readsb       # Check image details

Sponsor & Credits

Sponsored and maintained by Blackout Secure

Upstream project: wiedehopf/readsb
Container patterns: LinuxServer.io

References

Project Resources

Resource	Link
Docker Hub	blackoutsecure/readsb
GitHub Issues	Report bugs or request features
GitHub Releases	Download releases

Upstream & Related

Project	Link
readsb	wiedehopf/readsb
LinuxServer.io	linuxserver.io

Technical Resources

License

This project is licensed under the GNU General Public License v3.0 or later - see the LICENSE file for details.

The readsb application itself is also licensed under GPL-3.0. For more information, see the readsb repository.

Made with ❤️ by Blackout Secure

Name		Name	Last commit message	Last commit date
Latest commit History 52 Commits
.github/workflows		.github/workflows
root/etc/s6-overlay/s6-rc.d		root/etc/s6-overlay/s6-rc.d
.dockerignore		.dockerignore
.editorconfig		.editorconfig
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
balena-compose.yml		balena-compose.yml
balena.yml		balena.yml
docker-compose.yml		docker-compose.yml
logo.png		logo.png
readme-vars.yml		readme-vars.yml

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

blackoutsecure/readsb

Overview

Table of Contents

Quick Start

Image Availability

About The readsb Application

Supported Architectures

Usage

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

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

docker-cli (click here for more info)

Balena Deployment

Parameters

Ports

Environment Variables

Storage Mounts

Devices

Volume Details

/config — Configuration & Persistence

/run/readsb — JSON Output

Best Practices

Volume Mount Examples

Configuration

User / Group Identifiers

Application Setup

Key Features

Customizing READSB_ARGS

JSON Output Files

Supported Modes

Troubleshooting

Container won't start or exits immediately

No aircraft data appearing

JSON output not updating

High CPU usage or memory growth

Device permission errors (non-root mode)

Port conflicts

Getting help

Release & Versioning

Support & Getting Help

Sponsor & Credits

References

Project Resources

Upstream & Related

Technical Resources

License

About

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 1

Sponsor this project

Uh oh!

Uh oh!

Contributors 2

Languages

`/config` — Configuration & Persistence

`/run/readsb` — JSON Output