• sdr-enthusiasts/docker-tar1090
  • Introduction
  • Note for Users running 32-bit Debian Buster-based OSes on ARM
  • Supported tags and respective Dockerfiles
  • Multi Architecture Support
  • Prerequisites
  • Up-and-Running with docker run
  • Up-and-Running with docker-compose
  • Ports
    • Outgoing
    • Incoming
  • Runtime Environment Variables
    • Container Configuration
    • tar1090 Configuration
      • tar1090 Core Configuration
      • Using a locally modified tar1090 version
      • tar1090 config.js Configuration - Title
      • tar1090 config.js Configuration - Output
      • tar1090 config.js Configuration - Map Settings
      • tar1090 config.js Configuration - Range Rings
      • tar1090 config.js Configuration - Expert
    • tar1090 Route Display Configuration
    • timelapse1090 Configuration
  • Paths
    • readsb Network Options
      • READSB_NET_CONNECTOR syntax
    • readsb General Options
    • AutoGain for RTLSDR Devices
  • Message decoding introspection
  • Configuring graphs1090
    • graphs1090 Environment Parameters
    • Enabling UAT data
    • Enabling AirSpy graphs
    • Enabling Disk IO and IOPS data
    • Configuring the Core Temperature graphs
    • Reducing Disk IO for Graphs1090
  • Logging
  • Getting help
  • Using tar1090 with an SDR
  • globe-history or sometimes ironically called destroy-sd-card
  • Metrics
    • Output to InfluxDBv2
    • Output to InfluxDBv1.8
    • Output to Prometheus
  • Minimalist setup

This container tar1090 runs @wiedehopf's readsb fork ADS-B decoding engine in to feed the graphic tar1090 viewing webinterface, also by wiedehopf (as is the viewadsb text-based output) to provide digital representations of the readsb output.

At the time of writing this README, it provides:

• Improved adjustable history
• Show All Tracks much faster than original with many planes
• Multiple Maps available
• Map can be dimmed/darkened
• Multiple aircraft can be selected
• Labels with the callsign can be switched on and off
• Heatmap of aircraft positions

This image:

• Receives Beast data from a provider such as dump1090 or readsb
• Optionally, receives MLAT data from a provider such as mlat-client
• Provides the tar1090 web interface
• When using the :telegraf tag, it will be able to send data to Prometheus or InfluxDB to use in Grafana

It builds and runs on linux/amd64, linux/arm/v7 and linux/arm64 (see below).

Please see: Buster-Docker-Fixes!

• latest should always contain the latest released versions of readsb, tar1090 and tar1090-db.
• latest_nohealthcheck is the same as the latest version above. However, this version has the docker healthcheck removed. This is done for people running platforms (such as Nomad) that don't support manually disabling healthchecks, where healthchecks are not wanted.
• Specific version tags are available if required, however these are not regularly updated. It is generally recommended to run latest.

• linux/amd64: Built on Linux x86-64
• linux/arm/v6: Built on Odroid HC2 running ARMv7 32-bit
• linux/arm/v7: Built on Odroid HC2 running ARMv7 32-bit
• linux/arm64: Built on a Raspberry Pi 4 Model B running ARMv8 64-bit

You will need a source of Beast data. Examples are an RPi running PiAware or sdr-enthusiasts/docker-readsb-protobuf.

Optionally, you will need a source of MLAT data. This could be:

• sdr-enthusiasts/docker-adsbexchange image
• sdr-enthusiasts/docker-piaware image
• Basically anything running mlat-client listening for beast connections (ie: --results beast,listen,30105)

docker run -d \
    --name=tar1090 \
    -p 8078:80 \
    -e TZ=<TIMEZONE> \
    -e BEASTHOST=<BEASTHOST> \
    -e MLATHOST=<MLATHOST> \
    -e LAT=xx.xxxxx \
    -e LONG=xx.xxxxx \
    -v /opt/adsb/tar1090/graphs1090:/var/lib/collectd \
    --tmpfs=/run:exec,size=64M \
    --tmpfs=/var/log \
    ghcr.io/sdr-enthusiasts/docker-tar1090:latest

Replacing TIMEZONE with your timezone, BEASTHOST with the IP address of a host that can provide Beast data, and MLATHOST with the IP address of a host that can provide MLAT data.

For example:

docker run -d \
    --name=tar1090 \
    -p 8078:80 \
    -e TZ=Australia/Perth \
    -e BEASTHOST=readsb \
    -e MLATHOST=adsbx \
    -e LAT=-33.33333 \
    -e LONG=111.11111 \
    -v /opt/adsb/tar1090/graphs1090:/var/lib/collectd \
    --tmpfs=/run:exec,size=64M \
    --tmpfs=/var/log \
    ghcr.io/sdr-enthusiasts/docker-tar1090:latest

You should now be able to browse to:

• http://dockerhost:8078/ to access the tar1090 web interface
• http://dockerhost:8078/?replay to see a replay of past data
• http://dockerhost:8078/?heatmap to see the heatmap for the past 24 hours.
• http://dockerhost:8078/?heatmap&realHeat to see a different heatmap for the past 24 hours.
• http://dockerhost:8078/graphs1090/ to see performance graphs

An example docker-compose.xml file is below:

version: "3.8"

services:
  tar1090:
    image: ghcr.io/sdr-enthusiasts/docker-tar1090:latest
    tty: true
    container_name: tar1090
    restart: always
    environment:
      - TZ=Australia/Perth
      - BEASTHOST=readsb
      - MLATHOST=adsbx
      - LAT=-33.33333
      - LONG=111.11111
    volumes:
      - /opt/adsb/tar1090/globe_history:/var/globe_history
      - /opt/adsb/tar1090/timelapse1090:/var/timelapse1090
      - /opt/adsb/tar1090/graphs1090:/var/lib/collectd
      - /proc/diskstats:/proc/diskstats:ro
    # - /run/airspy_adsb:/run/airspy_adsb
    ports:
      - 8078:80
    tmpfs:
      - /run:exec,size=64M
      - /var/log

You should now be able to browse to:

• http://dockerhost:8078/ to access the tar1090 web interface.
• http://dockerhost:8078/?replay to see a replay of past data
• http://dockerhost:8078/?heatmap to see the heatmap for the past 24 hours.
• http://dockerhost:8078/?heatmap&realHeat to see a different heatmap for the past 24 hours.
• http://dockerhost:8078/graphs1090/ to see performance graphs

Note: the example above excludes MLATHOST as readsb alone cannot provide MLAT data. You'll need a feeder container for this.

Some common ports are as follows (which may or may not be in use depending on your configuration):

Json position output:

• outputs an aircraft object for every new position received for an aircraft. The following parameters (which can be added with READSB_EXTRA_ARGS) control this output:
• --net-json-port-interval Set minimum interval between outputs per aircraft for TCP json output, default: 0.0 (every position)
• --net-json-port-include-noposition TCP json position output: include aircraft without position (state is sent for aircraft for every DF11 with CRC if the aircraft hasn't sent a position in the last 10 seconds and interval allowing)
• each json object will be on a new line
• https://github.com/wiedehopf/readsb/blob/dev/README-json.md

Aircraft.json:

• https://github.com/wiedehopf/readsb/blob/dev/README-json.md
• available on the same port as the web interface, example: http://192.168.x.yy:8087/data/aircraft.json

This container will try to connect to the BEASTHOST on TCP port 30005 by default. This can be changed by setting the BEASTPORT environment variable.

If MLATHOST is set, this container will try to connect the MLATHOST on TCP port 30105 by default. This can be changed to setting the MLATPORT environment variable.

This container accepts HTTP connections on TCP port 80 by default. You can change this with the container's port mapping. In the examples above, this has been changed to 8078.

READSB_EXTRA_ARGS just passes arguments to the commandline, you can check this file for more options for wiedehofps readsb fork: https://github.com/wiedehopf/readsb/blob/dev/help.h

If you want to save historic data with tar1090, see a modified mode of operation at the end of the readme

All of the variables below are optional.

• For documentation on the aircraft.json format see this page: https://github.com/wiedehopf/readsb/blob/dev/README-json.md
• TAR1090_ENABLE_AC_DB causes readsb to load the tar1090 database as a csv file from this repository: https://github.com/wiedehopf/tar1090-db/tree/csv

• git clone https://github.com/wiedehopf/tar1090 /local/my_special_version
• Apply your modifications
• Make that directory available as /var/tar1090_git_source in the container (volumes: - /local/my_special_version:/var/tar1090_git_source)
• UPDATE_TAR1090=true

• In case a setting is available in tar1090 but not exposed via environment variable for this container
• For a list of possible settings, see https://github.com/wiedehopf/tar1090/blob/master/html/config.js
• Incorrect syntax or any capitalization errors will cause the map to not load, you have been warned!
• Example: TAR1090_CONFIGJS_APPEND= MapDim=false; nexradOpacity=0.2;
• In the environment section of a compose file you can generally use multiple lines like this:

    environment:
    ...
      - TAR1090_CONFIGJS_APPEND=
        MapDim=false;
        nexradOpacity=0.2;
    ...

Legacy: we do NOT recommend you enable this feature as it will cause substantial additional writes to disk. On a Pi, this may reduce the lifespan of your SD card. Instead, use http://dockerhost:port/?replay which provides the same functionality, but without additional load to the disk. The feature is included for legacy purposes only, and is disabled by default.

No paths need to be mapped through to persistent storage. However, if you don't want to lose your range outline and aircraft tracks/history and heatmap / replay data on container restart, you can optionally map these paths:

This container uses the readsb fork by wiedehopf as a backend to tar1090: https://github.com/wiedehopf/readsb

Where the default value is "Unset", readsb's default will be used.

Instead of (or in addition to) using BEASTHOST, you can also define ADSB data ingests using the READSB_NET_CONNECTOR parameter. This is the preferred way if you have multiple sources or destinations for your ADSB data. This variable allows you to configure incoming and outgoing connections. The variable takes a semicolon (;) separated list of host,port,protocol[,uuid=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX], where:

• host is an IP address. Specify an IP/hostname/containername for incoming or outgoing connections.
• port is a TCP port number
• protocol can be one of the following:
  • beast_reduce_out: Beast-format output with lower data throughput (saves bandwidth and CPU)
  • beast_reduce_plus_out: Beast-format output with extra data (UUID). This is the preferred format when feeding the "new" aggregator services
  • beast_out: Beast-format output
  • beast_in: Beast-format input
  • raw_out: Raw output
  • raw_in: Raw input
  • sbs_out: SBS-format output
  • vrs_out: SBS-format output
• uuid=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX is an optional parameter that sets the UUID for this specific instance. It will override the global UUID parameter. This is only needed when you want to send different UUIDs to different aggregators.

NOTE: If you have a UAT dongle and use dump978 to decode this, you should use READSB_NET_CONNECTOR to ingest UAT data from dump978. See example below

    environment:
    ...
      - READSB_NET_CONNECTOR=dump978,37981,raw_in;another-data-aggregator.com,30005,beast_reduce_plus_out
    ...

Where the default value is "Unset", readsb's default will be used.

If you have set READSB_GAIN=autogain, then the system will take signal strength measurements to determine the optimal gain. The AutoGain functionality is based on a (slightly) modified version of Wiedehopf's AutoGain. AutoGain will only work with rtlsdr style receivers.

There are 2 distinct periods in which the container will attempt to figure out the gain:

• The initial period of 2 hours, in which an adjustment is done every 5 minutes
• The subsequent period, in which an adjustment is done once every day

Please note that in order for the initial period to complete, the container must run for 90 minutes without restarting.

When taking measurements, if the percentage of "strong signals" (i.e., ADSB messages with RSSI > 3 dB) is larger than 6%, AutoGain will reduce the receiver's gain by 1 setting. Similarly, if the percentage of strong signals is smaller than 2.5%, AutoGain will increment the receiver's gain by 1 setting. When AutoGain changes the gain value, the readsb component of the container will restart. This may show as a disconnect / reconnected in container logs.

We recommend running the initial period during times when there are a lot of planes overhead, so the system will get a good initial view of what signals look like when traffic is at its peak for your location. If you forgot to do this for any reason, feel free to give the AutoGain reset command (see below) during flights busy hour.

Although not recommended, you can change the measurement intervals and low/high cutoffs with these parameters:

If you need to reset AutoGain and start over determining the gain, you can do so with this command:

docker exec -it tar1090 /usr/local/bin/autogain1090 reset

You can look at individual messages and what information they contain, either for all or for an individual aircraft by hex:

# only for hex 3D3ED0
docker exec -it tar1090 /usr/local/bin/viewadsb --show-only 3D3ED0

# for all aircraft
docker exec -it tar1090 /usr/local/bin/viewadsb --no-interactive

# show position / CPR debugging for hex 3D3ED0
docker exec -it tar1090 /usr/local/bin/viewadsb --cpr-focus 3D3ED0

ADS-B over UAT data is transmitted in the 978 MHz band, and this is used in the USA only. To display the corresponding graphs, you should:

1. Set the following environment parameters:

- ENABLE_978=yes
- URL_978=http://dump978/skyaware978

2. Install the docker-dump978 container. Note - only containers downloaded/deployed on/after Feb 8, 2023 will work.

Note that you *must- configure URL_978 to point at a working skyaware978 website with aircraft.json data feed. This means that the URL http://dump978/skyaware978/data/aircraft.json must return valid JSON data to this tar1090 container.

Users of AirSpy devices can enable extra graphs1090 graphs by configuring the following:

• Set the following environment parameter:

- ENABLE_AIRSPY=yes

• To provide the container access to the AirSpy statistics, map a volume in your docker-compose.yml file as follows:

    volumes:
      - /run/airspy_adsb:/run/airspy_adsb
      ...

To allow the container access to the Disk IO data, you should map the following volume:

    volumes:
      - /proc/diskstats:/proc/diskstats:ro
      ...

By default, the system will use the temperature available at Thermal Zone 0. This generally works well on Raspberry Pi devices, and no additional changes are needed.

On different devices, the Core Temperature is mapped to a different Thermal Zone. To ensure the Core Temperature graph works, follow these steps

First check out which Thermal Zone contains the temperature you want to monitor. On your host system, do this:

for i in /sys/class/thermal/thermal_zone* ; do echo "$i - $(cat ${i}/type) - $(cat ${i}/temp 2>/dev/null)"; done

Something similar to this will be show:

/sys/class/thermal/thermal_zone0 - acpitz - 25000
/sys/class/thermal/thermal_zone1 - INT3400 Thermal - 20000
/sys/class/thermal/thermal_zone2 - TSKN - 43050
/sys/class/thermal/thermal_zone3 - NGFF - 32050
/sys/class/thermal/thermal_zone4 - TMEM - 39050
/sys/class/thermal/thermal_zone5 - pch_skylake - 40500
/sys/class/thermal/thermal_zone6 - B0D4 - 54050
/sys/class/thermal/thermal_zone7 - iwlwifi_1 -
/sys/class/thermal/thermal_zone8 - x86_pkg_temp - 57000

Repeat this a few times to ensure that the temperature varies and isn't hardcoded to a value. In our case, either Thermal Zone 5 (pch_skylake is the Intel Core name) or Thermal Zone 8 (the temp of the entire SOC package) can be used. Once you have determined which Thermal Zone number you want to use, map it to a volume like this. Make sure that the part to the left of the first : reflects your Thermal Zone directory; the part to the right of the first : should always be /sys/class/thermal/thermal_zone0:ro.

Note that you will have to add - privileged: true capabilities to the container. This is less than ideal as it will give the container access to all of your system devices and processes. Make sure you feel comfortable with this before you do this.

    privileged: true
    volumes:
      - /sys/class/thermal/thermal_zone8:/sys/class/thermal/thermal_zone0:ro
      ...

Note - on some systems (DietPi comes to mind), /sys/class/thermal/ may not be available.

Note - this feature is still somewhat experimental. If you are really attached to your statistics/graphs1090 data, please make sure to back up your mapped drives regularly

If you are using a Raspberry Pi or another type of computer with an SD card, you may already be aware that these SD cards have a limited number of write-cycles that will determine their lifespan. In other words - a common reason for SD card failure is excessive writes to it.

By the nature of having to log lots of data the graphs1090 functionality writes a lot to the SD card. To reduce the number of write cycles, there are a few parameters you can set.

Enabling this functionality will cause graphs1090 to temporarily write all data to volatile memory (/run) instead of persistent disk space (/var/lib/collectd). This data is backed up to persistent disk space in regular intervals and upon (graceful) shutdown of the container.

Note -- there is a chance that the data isn't written back in time (due to power failures, non-graceful container shutdowns, etc), in which case you may lose statistics data that has been generated since the last write-back.

The feature assumes that you have mapped /var/lib/collectd to a volume (to ensure data is persistent across container recreations), and /run as a tmpfs RAM disk, as shown below and also as per the docker-compose.yml example:

volumes:
  - /opt/adsb/tar1090/globe_history:/var/globe_history
---
tmpfs:
  - /run:exec,size=256M

All logs are to the container's stdout and can be viewed with docker logs -t [-f] container.

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

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

Example (devices: section is mandatory)

version: "3.8"

services:
  tar1090:
    image: ghcr.io/sdr-enthusiasts/docker-tar1090:latest
    tty: true
    container_name: tar1090
    hostname: tar1090
    restart: always
    environment:
      - TZ=Australia/Perth
      - LAT=-33.33333
      - LONG=111.11111
      - READSB_DEVICE_TYPE=rtlsdr
      - READSB_GAIN=43.9
      - READSB_RTLSDR_DEVICE=0
    ports:
      - 8078:80
    tmpfs:
      - /run:exec,size=64M
      - /var/log

    devices:
      - /dev/bus/usb:/dev/bus/usb

See also: https://github.com/wiedehopf/tar1090#0800-destroy-sd-card

    environment:
    ...
      - READSB_EXTRA_ARGS=--write-json-globe-index --write-globe-history /var/globe_history
    ...
    volumes:
      - /hostpath/to/your/globe_history:/var/globe_history

The first part of the mount before the : is the path on the docker host, don't change the 2nd part. Using this volume gives you persistence for the history / heatmap / range outline

Note that this mode will make T not work as before for displaying all tracks as tracks are only loaded when you click them.

When using the :telegraf tag, the image contains Telegraf, which can be used to capture metrics from readsb if an output is enabled.

NOTE - READ CAREFULLY: As of 27 April 2023, the latest image no longer contains Telegraf. If you want to send metrics to InfluxDB or Prometheus, please use this image:

services:
  tar1090:
    image: ghcr.io/sdr-enthusiasts/docker-tar1090:telegraf
  ...

In order for Telegraf to output metrics to an InfluxDBv2 time-series database, the following environment variables can be used:

In order for Telegraf to output metrics to a legacyInfluxDBv1 time-series database, the following environment variables can be used:

In order for Telegraf to serve a Prometheus endpoint, the following environment variables can be used:

If you want to configure to run with a minimal CPU and RAM profile, and use it only as a SDR decoder but without any mapping or stats/graph websites, then do the following:

• Set the parameter TAR1090_DISABLE=true. This will prevent the nginx webserver and any websites or associated data collection (collectd, graphs1090, rrd, etc.) to be launched
• Make sure not to use the dhcr.io/sdr-enthusiasts/docker-adsb-ultrafeeder:telegraf label as Telegraf adds a LOT of resource use to the container