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.

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

• 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

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.

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

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

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:

---
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

---
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 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

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.

The container uses two volumes for data persistence and input:

• 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

• 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

• 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

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

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

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

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

• 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

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.

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

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.

Check logs:

docker logs tar1090 --tail 100

Change the host-side port mapping:

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

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

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

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.

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

Release plumbing is handled by a thin caller for the Blackout Secure Launchpad reusable workflow, defined in .github/workflows/bos-universal-launchpad.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).

# 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

• 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

Sponsored and maintained by Blackout Secure

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

• ADS-B Overview
• Docker Documentation

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

The tar1090 application itself is also licensed under GPL-2.0-or-later. For more information, see the tar1090 repository.

Made with care by Blackout Secure