sdr-enthusiasts/docker-piaware

FlightAware's PiAware docker container including support for RTL-SDR, bladeRF and others. Includes dump1090 and dump978.

Builds and runs on linux/amd64, linux/386, linux/arm/v7 and linux/arm64.

For more information on what PiAware is, see here: FlightAware - PiAware.

This container can operate in "net only" mode and pull ADS-B Mode-S & UAT data from another host/container. This is the recommended way of deploying the container, and I'd humbly suggest sdr-enthusiasts/docker-readsb-protobuf and sdr-enthusiasts/docker-dump978 (if you live in an area that uses UAT).

Note: bladerf/hackrf/limesdr/radarcape - Support for these is compiled in, but I need to complete the wrapper/helper scripts. I don't have access to these devices. If you do, and would be willing to test, please get in touch with me!

Note for Users running 32-bit Debian Buster-based OSes on ARM

Please see: Buster-Docker-Fixes!

Table of Contents

• sdr-enthusiasts/docker-piaware
  • Note for Users running 32-bit Debian Buster-based OSes on ARM
  • Table of Contents
  • Supported tags and respective Dockerfiles
  • Multi Architecture Support
  • Prerequisites
  • Determining your Feeder ID
    • Already running PiAware
    • New to PiAware
  • Deployment Examples
    • Example docker run command with RTL-SDR USB for reception of 1090MHz
    • Example docker-compose.yml with RTL-SDR USB for reception of 1090MHz
    • Example docker run command with 2x RTL-SDR USB for reception of 1090MHz and 978MHz
    • Example docker-compose.yml with 2x RTL-SDR USB for reception of 1090MHz and 978MHz
    • Example docker run with external Mode-S/BEAST provider
    • Example docker-compose.yml with external Mode-S/BEAST provider
    • Example docker run with external Mode-S/BEAST provider and external UAT provider
    • Example docker-compose.yml with external Mode-S/BEAST provider and external UAT provider
  • Environment Variables
    • General
    • Multilateration
    • Receiver Configuration (1090MHz)
    • RTL-SDR Configuration (1090MHz)
      • Adaptive Gain Configuration (1090MHz)
    • Relay Configuration (1090MHz)
    • Receiver Configuration (978MHz)
    • RTL-SDR Configuration (978MHz)
    • Relay Configuration (978MHz)
  • Ports
  • Claiming Your Receiver
  • Logging
  • Other services to feed
  • Getting help

Supported tags and respective Dockerfiles

• latest should always contain the latest released version of piaware and support tools, for all supported architectures.
• Specific version and architecture tags are available if required, however these are not regularly updated. It is generally recommended to run latest.
• There are also latest and version-specific tags appended with _nohealthcheck where the container healthchecks have been excluded from the image build. See issue #43.

Multi Architecture Support

Currently, this image should pull and run on the following architectures:

• linux/i386
• linux/amd64
• linux/arm/v7
• linux/arm64

In order to ensure dump1090 is optimised for the hardware running it, the dump1090 binary is built on first-run of the container.

Prerequisites

If using an RTL-SDR, before this container will work properly, you must blacklist the kernel modules for the RTL-SDR USB device from the host's kernel.

To do this, create a file /etc/modprobe.d/blacklist-rtl2832.conf containing the following:

# Blacklist RTL2832 so docker container piaware can use the device

blacklist rtl2832
blacklist dvb_usb_rtl28xxu
blacklist rtl2832_sdr

Once this is done, you can plug in your RTL-SDR USB device and start the container.

Failure to do this will result in the error below being spammed to the container log.

2019-04-29 21:14:31.642500500  [dump1090-fa] Kernel driver is active, or device is claimed by second instance of librtlsdr.
2019-04-29 21:14:31.642635500  [dump1090-fa] In the first case, please either detach or blacklist the kernel module
2019-04-29 21:14:31.642663500  [dump1090-fa] (dvb_usb_rtl28xxu), or enable automatic detaching at compile time.
2019-04-29 21:14:31.642677500  [dump1090-fa]
2019-04-29 21:14:31.642690500  [dump1090-fa] usb_claim_interface error -6

If you get the error above even after blacklisting the kernel modules as outlined above, the modules may still be loaded. You can unload them by running the following commands:

sudo rmmod rtl2832_sdr
sudo rmmod dvb_usb_rtl28xxu
sudo rmmod rtl2832

Determining your Feeder ID

You need to specify a feeder-id for the container, as this is used by FlightAware to track your PiAware instance.

Make sure you set your feeder ID via the FEEDER_ID environment variable. Failure to do this will cause a new FlightAware site ID to be generated every time you launch the container.

Already running PiAware

You'll need your feeder-id from your existing feeder.

To get your feeder-id, log onto your feeder and issue the command:

piaware-config -show feeder-id

New to PiAware

You'll need a feeder-id. To get one, you can temporarily run the container, to allow it to communicate with the FlightAware servers and get a new feeder ID.

Run the commands:

docker pull ghcr.io/sdr-enthusiasts/docker-piaware:latest
timeout 30 docker run --rm ghcr.io/sdr-enthusiasts/docker-piaware:latest | grep "my feeder ID"

The command will run the container for 30 seconds, which should be ample time for the container to receive a feeder-id.

For example:

timeout 30 docker run --rm ghcr.io/sdr-enthusiasts/docker-piaware:latest | grep "my feeder ID"

Will output:

Set allow-mlat to yes in /etc/piaware.conf:1
Set allow-modeac to yes in /etc/piaware.conf:2
Set allow-auto-updates to no in /etc/piaware.conf:3
Set allow-manual-updates to no in /etc/piaware.conf:4
2020-03-06 06:16:11.860212500  [piaware] my feeder ID is acbf1f88-09a4-3a47-a4a0-10ae138d0c1g
write /dev/stdout: broken pipe
Terminated

As you can see from the output above, the feeder-id given to us from FlightAware is acbf1f88-09a4-3a47-a4a0-10ae138d0c1g.

You'll now want to "claim" this feeder.

To do this, go to: FlightAware PiAware Claim and follow the instructions there.

Deployment Examples

Example docker run command with RTL-SDR USB for reception of 1090MHz

docker run \
 -d \
 --rm \
 --name piaware \
 --device /dev/bus/usb \
 -e TZ="Australia/Perth" \
 -e FEEDER_ID=c478b1c99-23d3-4376-1f82-47352a28cg37 \
 -e RECEIVER_TYPE=rtlsdr \
 -p 8080:80 \
 --tmpfs=/run:exec,size=64M \
 --tmpfs=/var/log \
 ghcr.io/sdr-enthusiasts/docker-piaware:latest

Example docker-compose.yml with RTL-SDR USB for reception of 1090MHz

version: '2.0'

services:
  piaware:
    image: ghcr.io/sdr-enthusiasts/docker-piaware:latest
    tty: true
    container_name: piaware
    restart: always
    devices:
      - /dev/bus/usb:/dev/bus/usb
    ports:
      - 8080:80
      - 30003:30003
      - 30005:30005
    environment:
      - TZ="Australia/Perth"
      - FEEDER_ID=c478b1c99-23d3-4376-1f82-47352a28cg37
      - RECEIVER_TYPE=rtlsdr
    tmpfs:
      - /run:exec,size=64M
      - /var/log

Example docker run command with 2x RTL-SDR USB for reception of 1090MHz and 978MHz

This will currently only work in the United States of America, as they are the only country that uses ADS-B UAT on 978MHz.

This example assumes that:

• Your 1090MHz RTL-SDR has its serial set to 00001090
• Your 978MHz RTL-SDR has its serial set to 00000978

docker run \
 -d \
 --rm \
 --name piaware \
 --device /dev/bus/usb \
 -e TZ="Australia/Perth" \
 -e RECEIVER_TYPE=rtlsdr \
 -e DUMP1090_DEVICE=00001090 \
 -e UAT_RECEIVER_TYPE=rtlsdr \
 -e DUMP978_DEVICE=00000978 \
 -e FEEDER_ID=c478b1c99-23d3-4376-1f82-47352a28cg37 \
 -p 8080:80 \
 --tmpfs=/run:exec,size=64M \
 --tmpfs=/var/log \
 ghcr.io/sdr-enthusiasts/docker-piaware:latest

Example docker-compose.yml with 2x RTL-SDR USB for reception of 1090MHz and 978MHz

This will currently only work in the United States of America, as they are the only country that uses ADS-B UAT on 978MHz.

version: '2.0'

services:
  piaware:
    image: ghcr.io/sdr-enthusiasts/docker-piaware:latest
    tty: true
    container_name: piaware
    restart: always
    devices:
      - /dev/bus/usb:/dev/bus/usb
    ports:
      - 8080:80
      - 30003:30003
      - 30005:30005
    environment:
      - TZ="Australia/Perth"
      - FEEDER_ID=c478b1c99-23d3-4376-1f82-47352a28cg37
      - RECEIVER_TYPE=rtlsdr
      - DUMP1090_DEVICE=00001090
      - UAT_RECEIVER_TYPE=rtlsdr
      - DUMP978_DEVICE=00000978
    tmpfs:
      - /run:exec,size=64M
      - /var/log

Example docker run with external Mode-S/BEAST provider

An example of an external Mode-S/BEAST provider would be:

• sdr-enthusiasts/docker-readsb-protobuf container
• Another hardware feeder that provides BEAST output data on port 30005

In the example below, it is assumed that the external BEAST provider resolves to beasthost and is listening for connections on TCP port 30005.

docker run \
 -d \
 --rm \
 --name piaware \
 -e TZ="Australia/Perth" \
 -e RECEIVER_TYPE=relay \
 -e BEASTHOST=beasthost \
 -e BEASTPORT=30005 \
 -e FEEDER_ID=c478b1c99-23d3-4376-1f82-47352a28cg37 \
 --tmpfs=/run:exec,size=64M \
 --tmpfs=/var/log \
 ghcr.io/sdr-enthusiasts/docker-piaware:latest

Example docker-compose.yml with external Mode-S/BEAST provider

An example of an external Mode-S/BEAST provider would be:

• sdr-enthusiasts/docker-readsb-protobuf container
• Another hardware feeder that provides BEAST output data on port 30005

In the example below, it is assumed that the external BEAST provider resolves to beasthost and is listening for connections on TCP port 30005.

version: '2.0'

services:
  piaware:
    image: ghcr.io/sdr-enthusiasts/docker-piaware:latest
    tty: true
    container_name: piaware
    restart: always
    environment:
      - TZ="Australia/Perth"
      - RECEIVER_TYPE=relay
      - BEASTHOST=beasthost
      - BEASTPORT=30005
      - FEEDER_ID=c478b1c99-23d3-4376-1f82-47352a28cg37
    tmpfs:
      - /run:exec,size=64M
      - /var/log

Example docker run with external Mode-S/BEAST provider and external UAT provider

This will currently only work in the United States of America, as they are the only country that uses ADS-B UAT on 978MHz.

An example of an external Mode-S/BEAST provider would be:

• sdr-enthusiasts/docker-readsb-protobuf container
• Another hardware feeder that provides BEAST output data on port 30005

In the example below, it is assumed that the external BEAST provider resolves to beasthost and is listening for connections on TCP port 30005.

An example of an external UAT provider would be:

• sdr-enthusiasts/docker-dump978 container

In the example below, it is assumed that the external UAT provider resolves to uathost and is listening for connections on TCP port 30978.

docker run \
 -d \
 --rm \
 --name piaware \
 -e TZ="Australia/Perth" \
 -e RECEIVER_TYPE=relay \
 -e BEASTHOST=beasthost \
 -e BEASTPORT=30005
 -e UAT_RECEIVER_TYPE=relay \
 -e UAT_RECEIVER_HOST=uathost \
 -e UAT_RECEIVER_PORT=30978 \
 -e FEEDER_ID=c478b1c99-23d3-4376-1f82-47352a28cg37 \
 --tmpfs=/run:exec,size=64M \
 --tmpfs=/var/log \
 ghcr.io/sdr-enthusiasts/docker-piaware:latest

Example docker-compose.yml with external Mode-S/BEAST provider and external UAT provider

This will currently only work in the United States of America, as they are the only country that uses ADS-B UAT on 978MHz.

An example of an external Mode-S/BEAST provider would be:

• sdr-enthusiasts/docker-readsb-protobuf container
• Another hardware feeder that provides BEAST output data on port 30005

In the example below, it is assumed that the external BEAST provider resolves to beasthost and is listening for connections on TCP port 30005.

An example of an external UAT provider would be:

• sdr-enthusiasts/docker-dump978 container

In the example below, it is assumed that the external UAT provider resolves to uathost and is listening for connections on TCP port 30978.

version: '2.0'

services:
  piaware:
    image: ghcr.io/sdr-enthusiasts/docker-piaware:latest
    tty: true
    container_name: piaware
    restart: always
    environment:
      - TZ="Australia/Perth"
      - RECEIVER_TYPE=relay
      - BEASTHOST=beasthost
      - BEASTPORT=30005
      - UAT_RECEIVER_TYPE=relay
      - UAT_RECEIVER_HOST=uathost
      - UAT_RECEIVER_PORT=30978
      - FEEDER_ID=c478b1c99-23d3-4376-1f82-47352a28cg37
    tmpfs:
      - /run:exec,size=64M
      - /var/log

Environment Variables

For an explanation of piaware-config variables, see FlightAware PiAware Advanced Configuration.

General

Multilateration

Receiver Configuration (1090MHz)

Receiver types:

• rtlsdr - For FlightAware dongles and any other RTL-SDR
• relay - For use with an external BEAST protocol provider running on another host (dump1090/readsb/etc)
• bladerf/hackrf/limesdr/radarcape - Support for these is compiled in, but I need to complete the wrapperr scripts. I don't have access to these devices. If you do, and would be willing to test, please get in touch with me!

RTL-SDR Configuration (1090MHz)

Use only with RECEIVER_TYPE=rtlsdr.

Adaptive Gain Configuration (1090MHz)

The following settings control the adaptive gain configuration of dump1090 when using RECEIVER_TYPE=rtlsdr.

Relay Configuration (1090MHz)

Use only with RECEIVER_TYPE=relay.

Receiver Configuration (978MHz)

Receiver types:

• rtlsdr - For FlightAware dongles and any other RTL-SDR
• relay - For use with an external BEAST protocol provider running on another host (dump1090/readsb/etc)
• bladerf/hackrf/limesdr/radarcape - Support for these is compiled in, but I need to complete the wrapperr scripts. I don't have access to these devices. If you do, and would be willing to test, please get in touch with me!

RTL-SDR Configuration (978MHz)

Use only with UAT_RECEIVER_TYPE=rtlsdr.

Relay Configuration (978MHz)

Use only with UAT_RECEIVER_TYPE=relay.

Ports

The following ports are used by this container:

• 80 - PiAware Status page and dump1090 web interface (Skyaware) - optional but recommended so you can check status and and watch the planes fly around.
• 30003 - dump1090 TCP BaseStation output listen port - optional, recommended to leave unmapped unless explicitly needed
• 30005 - dump1090 TCP Beast output listen port - optional, recommended to leave unmapped unless explicitly needed
• 30105 - If MLAT is enabled, mlat-client results published on this port in Beast format - optional, recommended to leave unmapped unless explicitly needed
• 30978 - If UAT decoding is enabled, UAT raw data published on this port - optional, recommended to leave unmapped unless explicitly needed
• 30979 - If UAT decoding is enabled, UAT decoded JSON published on this port - optional, recommended to leave unmapped unless explicitly needed

Claiming Your Receiver

Since version 3.8.0 the flightaware-user and flightaware-password configuration options are no longer used; please use the normal site-claiming mechanisms to associate sites with a FlightAware account.

FlightAware PiAware Claim

Logging

• All processes are logged to the container's stdout, and can be viewed with docker logs [-f] container.
• lighttpd (which provides SkyAware & SkyAware978) is configured to not log (except for a startup message on container start)

Other services to feed

Check out these other images here.

Getting help

Please feel free to open an issue on the project's GitHub.

We also have a Discord channel, feel free to join and converse.