blackoutsecure/tar1090 repository overview

⁠blackoutsecure/tar1090

LinuxServer.io-style containerized build of tar1090⁠, an improved, fast ADS-B web interface for readsb/dump1090-fa with maps, history, filters, and multi-instance support.

Sponsored and maintained by Blackout Secure⁠.

⁠Overview

LinuxServer.io-style containerized build of tar1090⁠, an improved, fast ADS-B web interface for readsb/dump1090-fa with maps, history, filters, and multi-instance support.

Quick links:

• Docker Hub listing: blackoutsecure/tar1090⁠
• Balena block listing: tar1090⁠
• GitHub repository: blackoutsecure/docker-tar1090⁠
• Upstream application: wiedehopf/tar1090⁠
• Upstream query parameters: tar1090 README-query.md⁠

⁠Table of Contents

• blackoutsecure/tar1090⁠
  • Overview⁠
  • Table of Contents⁠
  • Quick Start⁠
  • Image Availability⁠
  • About The tar1090 Application⁠
  • Supported Architectures⁠
  • Usage⁠
    • docker-compose (recommended, click here for more info)⁠
    • docker-compose with paired readsb container⁠
    • docker-cli (click here for more info)⁠
    • Balena Deployment⁠
  • Parameters⁠
    • Ports⁠
    • Environment Variables⁠
    • Storage Mounts⁠
  • Volume Details⁠
    • /config — Configuration & Persistence⁠
    • /data/readsb — Decoder JSON Input⁠
    • Best Practices⁠
    • Volume Mount Examples⁠
  • Configuration⁠
  • User / Group Identifiers⁠
  • Application Setup⁠
    • Key Features⁠
    • Features That Depend On The Decoder⁠
  • Troubleshooting⁠
    • Container won't start or exits immediately⁠
    • The web UI loads but no aircraft appear⁠
    • Container starts but page appears incomplete⁠
    • HTTP port conflict⁠
    • Advanced tar1090 behavior questions⁠
    • Getting help⁠
  • Release & Versioning⁠
    • Docker Hub Tags⁠
    • How It Works⁠
    • Checking Your Image Version⁠
  • Support & Getting Help⁠
  • Sponsor & Credits⁠
  • References⁠
    • Project Resources⁠
    • Upstream & Related⁠
    • Technical Resources⁠
  • License⁠

⁠Quick Start

5-minute web UI setup (with sample data):

docker compose up -d

Open http://localhost:8080.

With a running decoder (e.g., readsb outputting JSON to a host directory):

docker run -d \
  --name=tar1090 \
  --restart unless-stopped \
  -e TZ=Etc/UTC \
  -e TAR1090_SOURCE_DIR=/data/readsb \
  -p 8080:8080 \
  -v tar1090-config:/config \
  -v /path/to/readsb/json:/data/readsb:ro \
  blackoutsecure/tar1090:latest

Access the web interface at http://<host-ip>:8080.

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/tar1090:latest
• Multi-arch support: amd64, arm64
• No registry prefix needed (defaults to Docker Hub)

# Pull latest
docker pull blackoutsecure/tar1090

# Pull by upstream version (from version file)
docker pull blackoutsecure/tar1090:3.14.1801

# Pull by upstream commit (tracks exact source)
docker pull blackoutsecure/tar1090:upstream-2bf25135a665

⁠About The tar1090 Application

tar1090⁠ is an improved aircraft map and tracking web interface for ADS-B decoder outputs.

It is not an ADS-B decoder. It reads JSON data produced by an existing decoder such as readsb, dump1090-fa, or another compatible source, and renders an interactive aircraft map in the browser.

Author and maintenance credits (upstream):

• Primary upstream maintainer: wiedehopf⁠ (Matthias Wirth)
• Upstream repository and documentation: wiedehopf/tar1090⁠
• Aircraft database: wiedehopf/tar1090-db⁠

⁠Supported Architectures

This image is published as a multi-arch manifest. Pulling blackoutsecure/tar1090: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:
  tar1090:
    image: blackoutsecure/tar1090:latest
    container_name: tar1090
    environment:
      - TZ=Etc/UTC
      - TAR1090_SOURCE_DIR=/data/readsb
    volumes:
      - /path/to/tar1090/config:/config
      - /path/to/readsb/json:/data/readsb:ro
    ports:
      - 8080:8080
    restart: unless-stopped
    tmpfs:
      - /tmp
      - /run:exec

⁠docker-compose with paired readsb container

---
services:
  readsb:
    image: blackoutsecure/readsb:latest
    container_name: readsb
    environment:
      - TZ=Etc/UTC
      - READSB_ARGS=--net --device-type rtlsdr
    volumes:
      - readsb-config:/config
      - readsb-json:/run/readsb
    devices:
      - /dev/bus/usb:/dev/bus/usb
    restart: unless-stopped
    tmpfs:
      - /tmp
      - /run

  tar1090:
    image: blackoutsecure/tar1090:latest
    container_name: tar1090
    environment:
      - TZ=Etc/UTC
      - TAR1090_SOURCE_DIR=/data/readsb
    volumes:
      - tar1090-config:/config
      - readsb-json:/data/readsb:ro
    ports:
      - 8080:8080
    depends_on:
      - readsb
    restart: unless-stopped
    tmpfs:
      - /tmp
      - /run:exec

volumes:
  readsb-config:
  readsb-json:
  tar1090-config:

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

docker run -d \
  --name=tar1090 \
  -e TZ=Etc/UTC \
  -e TAR1090_SOURCE_DIR=/data/readsb \
  -p 8080:8080 \
  -v /path/to/tar1090/config:/config \
  -v /path/to/readsb/json:/data/readsb:ro \
  --restart unless-stopped \
  blackoutsecure/tar1090: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 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

⁠Volume Details

The container uses two volumes for data persistence and input:

⁠/config — Configuration & Persistence

• Required: No (container runs without it, but state is lost on restart)
• Purpose: Stores persistent data and application state
• Example: -v /path/to/tar1090/config:/config or -v tar1090-config:/config

⁠/data/readsb — Decoder JSON Input

• Required: Effectively yes (without it, the web UI loads but shows no aircraft)
• Purpose: Input directory containing decoder-generated JSON files
• Contents:
  • aircraft.json (current aircraft positions and data)
  • receiver.json (receiver stats and information)
  • Other tar1090-compatible outputs
• Example: -v /path/to/readsb/json:/data/readsb:ro or shared volume with readsb container

⁠Best Practices

• Read-only mount: Always mount /data/readsb as read-only (:ro) when another container owns the decoder output
• For persistence: Use named volumes or host paths for /config to preserve state between container restarts
• Shared volume with readsb: Use a named volume shared between readsb and tar1090 containers

⁠Volume Mount Examples

Named volumes (recommended for single-host deployments):

volumes:
  - config:/config
  - readsb-json:/data/readsb:ro

Host paths (for direct file access):

volumes:
  - /var/lib/tar1090/config:/config
  - /var/lib/readsb/json:/data/readsb:ro

⁠Configuration

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

tar1090 web interface customization is generally performed through upstream configuration such as config.js in the served HTML assets. This container ships the upstream defaults.

Useful upstream documentation:

• Main tar1090 readme: wiedehopf/tar1090⁠
• Query parameters: tar1090 README-query.md⁠

Examples of upstream URL-driven behavior include:

• /?pTracks for history display
• /?icao=abc123 to select a specific aircraft
• /?zoom=9&enableLabels&extendedLabels=2 for display tuning
• /?heatmap=200000 when compatible heatmap data is available

⁠User / Group Identifiers

By default, this container runs with the abc user (uid 911) via LinuxServer.io s6-overlay patterns.

Default mode:

• Uses TAR1090_USER=abc with PUID=911 / PGID=911
• No special permissions needed

Custom user mode (advanced):

• Set TAR1090_USER to your username
• Provide matching PUID and PGID values

⁠Application Setup

The container runs tar1090 through nginx and expects decoder JSON input from a mounted directory.

⁠Key Features

• Interactive Map: Aircraft visualization with multiple basemap options
• Aircraft Database: Includes tar1090-db⁠ for accurate aircraft identification
• Advanced Filtering: Filter by ICAO, callsign, type, altitude, and more
• Track History: ?pTracks support when decoder provides history snapshots
• Read-Only Filesystem: Supported when temp directories are mounted to tmpfs

⁠Features That Depend On The Decoder

Some tar1090 features depend on the decoder providing additional data:

• ?pTracks requires history snapshots from the decoder
• Heatmap and replay require decoder-side support and retained history
• Richer aircraft identification benefits from the included tar1090-db aircraft database

This container fetches aircraft.csv.gz from wiedehopf/tar1090-db⁠ during build so the web UI has the upstream database artifact available.

⁠Troubleshooting

⁠Container won't start or exits immediately

Check logs:

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

Common causes:

• Port conflict: another service is already using port 8080
• Volume mount issue: verify paths exist and are accessible

⁠The web UI loads but no aircraft appear

Check that decoder JSON is available:

docker exec tar1090 ls -la /data/readsb
docker exec tar1090 cat /data/readsb/aircraft.json | head -c 200

If aircraft.json is missing or stale, the problem is upstream of tar1090 — fix it in the decoder container or host service.

⁠Container starts but page appears incomplete

Check logs:

docker logs tar1090 --tail 100

⁠HTTP port conflict

Change the host-side port mapping:

docker run ... -p 8081:8080 ...

⁠Advanced tar1090 behavior questions

For filter syntax, query parameters, ?pTracks, heatmaps, and multi-instance behavior, use the upstream tar1090 documentation⁠ as those are application-level features.

⁠Getting help

• Check upstream tar1090 documentation⁠
• Review container logs: docker logs -f tar1090
• Open an issue on GitHub⁠

⁠Release & Versioning

This project tracks two independent values from the upstream wiedehopf/tar1090⁠ master branch:

These are two different things: the commit changes frequently with every push, while the version only changes when the upstream maintainer explicitly increments it. Both are tracked and published.

⁠Docker Hub Tags

Every build produces multiple tags so you can pin at the granularity you need:

⁠How It Works

Release plumbing is handled by a thin caller for the Blackout Secure Launchpad⁠ reusable workflow, defined in .github/workflows/bos-launchpad-release.yml⁠. On a 6-hour cron (and on manual dispatch) it runs three stages end-to-end:

1. Monitor — Polls the version file at the head of wiedehopf/tar1090@master, compares against .github/upstream/tar1090-master.json, and commits the tracking file when upstream moves.
2. Docker — Builds multi-arch images (amd64, arm64), tags latest, <version>, <major>.<minor>, <major>, upstream-<commit>, and sha-<run-sha> on Docker Hub, then refreshes the Docker Hub description from this README and runs a Docker Scout scan.
3. Balena — Renders balena.yml dynamically from the launchpad inputs and publishes the tar1090 block release. This repo opts out of automated GitHub Releases (github_release: false).

⁠Checking Your Image Version

# Check the upstream version baked into the image
docker inspect -f '{{ index .Config.Labels "org.opencontainers.image.version" }}' blackoutsecure/tar1090:latest

# Check the upstream commit baked into the image
docker inspect -f '{{ index .Config.Labels "io.tar1090.upstream.commit" }}' blackoutsecure/tar1090:latest

# Check the full build version string
docker inspect -f '{{ index .Config.Labels "build_version" }}' blackoutsecure/tar1090:latest

Update to latest:

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

⁠Support & Getting Help

• Questions: GitHub Issues⁠
• Bug Reports: Include Docker version, container logs, and reproduction steps
• Upstream Documentation: tar1090 on GitHub⁠
• Community: LinuxServer.io Discord⁠

Get help:

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

⁠Sponsor & Credits

Sponsored and maintained by Blackout Secure⁠

Upstream project: wiedehopf/tar1090⁠ Container patterns: LinuxServer.io⁠

⁠References

⁠Project Resources

⁠Upstream & Related

⁠Technical Resources

• ADS-B Overview⁠
• Docker Documentation⁠

⁠License

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

The tar1090 application itself i