Requirements

SoftwareCopy Anchor Link

For the recommended Docker Compose installation:

• Docker Engine or Docker Desktop
• Docker Compose v2 (the docker compose command, not docker-compose)

For a manual installation without Docker you need Node.js 22, Bun, Git and PostgreSQL 16 instead.

Using an existing PostgreSQL serverCopy Anchor Link

The Docker Compose file runs its own PostgreSQL container, which is the easiest option. You can point DB_URL at a PostgreSQL server you already run instead. AirTrail is tested with PostgreSQL 16, and its migrations also apply on versions down to 11, though 11 and 12 no longer receive security updates.

Create a role and a database it owns:

CREATE ROLE airtrail LOGIN PASSWORD 'change-me';
CREATE DATABASE airtrail OWNER airtrail;

Then set DB_URL=postgres://airtrail:change-me@<server>:5432/airtrail. Migrations run when AirTrail starts and create the unaccent extension. On PostgreSQL 12 and earlier, or when the role does not own the database, that needs a superuser. Run this once, connected to the AirTrail database as a superuser, and restart AirTrail:

CREATE EXTENSION IF NOT EXISTS "unaccent";

AirTrail also prints this command when the migration fails for that reason.

PlatformsCopy Anchor Link

AirTrail images are published for linux/amd64 and linux/arm64, so they run on:

• Linux servers and virtual machines (most tested; Ubuntu and Debian are common choices)
• ARM single-board computers such as the Raspberry Pi 4 and 5 with a 64-bit OS
• NAS devices and home servers that run containers, such as Synology and Unraid
• macOS and Windows through Docker Desktop, which is fine for trying AirTrail out

32-bit ARM (armv7) is not supported.

HardwareCopy Anchor Link

These figures come from running the published image with its PostgreSQL container:

• Memory: the first start loads about 86,000 airports, and the app briefly peaks around 600 MB before settling at about 75 MB when idle. It also starts successfully when capped at 512 MB, with the database capped at 256 MB. With 10,000 flights, listing all flights, computing statistics or exporting them peaks at about 375 MB for the app and 190 MB for the database.
• CPU: the same requests take under a second each on one core.
• Disk: the AirTrail image is about 570 MB, including a 200 MB map data file, and PostgreSQL about 290 MB. A database with 10,000 flights and all reference data is about 25 MB. Detailed flight tracks and uploaded icons add to this.

A Raspberry Pi 4 or 5 with 2 GB or more is plenty for a household.

NetworkCopy Anchor Link

• Clients reach AirTrail on port 3000 by default. For access over the internet, use a reverse proxy with HTTPS.
• The server makes outbound HTTPS requests to download airport and airline data and to reach optional integrations such as AeroDataBox. Behind a corporate proxy, see Outbound proxy.
• Browsers load map tiles from the configured basemap provider.