Skip to content

About

Self-hosted flight archive for organizing flight history, boarding passes, airlines, airports, aircraft, and related documents.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

8 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

FlightArchive

FlightArchive v1.0.1

English | 简体中文

FlightArchive on GitHub GHCR DockerHub

1 Description

FlightArchive is a containerized flight-history application written with Python, FastAPI, React 19, TypeScript, and Material UI. It uses RemappableFileGateway (RFG) for read-only source discovery, virtual-path mappings, resource delivery, and hashes.

It follows these rules:

  • flight, catalog, and boarding-pass-layout data is atomically persisted by the backend
  • resources are selected from an RFG resource root and business records retain only classified virtual paths
  • resource mappings can be inspected and manually re-matched without editing virtual paths
  • thumbnails are disposable derived cache data; they never enter business data
  • fingerprint storage is limited to classified resources directly bound to saved flight boarding passes or attachments, or to a saved airline logo

1.1 Resource Model

RFG owns the read-only resource root and <data>/rfg/mapping.json. FlightArchive owns <data>/flightarchive/v1/business-data.json. A separate cache root stores rebuildable thumbnail objects and is never part of business data.

1.2 Preview Configuration

On first start, FlightArchive atomically seeds the restart-only, user-editable configuration file <RFG_DATA_DIR>/flightarchive/v1/preview-config.json. It is separate from both BusinessData and the disposable thumbnail cache. At startup, the path must be a regular file, must not be a symbolic link, and must be no larger than 64 KiB. The file must also be valid version 1 configuration; any violation blocks startup until it is corrected. Changes take effect only after restarting the backend.

{
  "schemaVersion": 1,
  "thumbnails": {
    "maxSourceBytes": 268435456,
    "maxSourcePixels": 100000000,
    "maxDimension": 512,
    "quality": 82,
    "jobConcurrency": 2
  },
  "rfg": {
    "pillowImageMaxPixels": 100000000
  }
}

thumbnails.maxSourceBytes defaults to 256 MiB. The inclusive ranges are: maxSourceBytes 1 MiB–1 GiB, maxSourcePixels 1,000,000–500,000,000, maxDimension 1–2048, quality 0–100, jobConcurrency 1–2, and pillowImageMaxPixels 1,000,000–500,000,000. Every scalar must be a strict JSON integer, and the document must contain exactly the documented keys. Unknown keys, missing keys, non-integers, and out-of-range values block startup. Raising the byte or pixel limits, or job concurrency, can increase memory use; concurrent image work has a corresponding memory cost. Changing thumbnail settings invalidates and reprofiles the thumbnail cache. All configuration changes are restart-only.

rfg.pillowImageMaxPixels is the only supported host-configurable RFG image safety setting. It is applied before RFG initializes and affects perceptual hashes. RFG ZIP guards, hash capacity, and internal thresholds are not configurable through this file.

1.3 Current Features

FlightArchive provides a responsive flight dashboard, flight and flight-reference (airline / airport / aircraft type) catalog editing, resource selection and classification, mapping review with ignore and re-match operations, business-bound resource fingerprints, and a boarding-pass crop & layout tool.

2 Usage

Run the following container commands from the repository root.

Build Docker Image:

docker build -f app/Dockerfile -t flightarchive:local app

Run Docker Image:

docker run -d \
  --name=flightarchive \
  --restart=unless-stopped \
  -p 127.0.0.1:8080:8080/tcp \
  -v /path/for/resources:/resource:ro \
  -v /path/for/data:/data \
   flightarchive:local

Published images: Each published GitHub Release tag is used directly as the image tag (without version normalization) and also updates latest:

docker pull ghcr.io/mehver/flightarchive:<release-tag>
docker pull docker.io/mehver/flightarchive:<release-tag>

Release assets also include separately loadable linux/amd64 and linux/arm64 Docker image tarballs.

Parameter Function
-p 127.0.0.1:8080:8080/tcp HTTP web interface
-v /path/for/resources:/resource:ro Existing RFG resource root, read-only
-v /path/for/data:/data RFG mapping and FlightArchive business data
-v /path/for/cache:/cache Optional rebuildable thumbnail cache

Open http://localhost:8080 after the container starts. Without the optional cache mount, /cache remains an ordinary disposable container directory.

The Notifications & Tasks drawer combines session-only notifications with backend-persisted task history. The application loads the newest three existing UTC log days into its global task store, shares that history with the drawer, and loads older days while scrolling. While any task is queued or running, it polls even when the drawer is closed and stops after tasks reach terminal states. Active tasks appear in a dedicated first group. Other entries retain their valid UTC instants, including future instants, and are grouped for display by the user's local activity date with newest dates first; only invalid times fall back to the current time. Session notifications exist only for the current session and clear on reload; task history persists in backend JSONL logs.

Polling also tracks the creation dates of known active tasks outside the newest three days, without moving the older-history cursor. Current-session task phases notify once regardless of whether POST or GET arrives first; historical loading and progress-only updates do not replay notifications. Task-history loading errors do not block session notifications. Closing a resource picker does not cancel an already submitted ignore operation: success is reported globally, while failure is global if the original dialog is closed; an old operation cannot change a newly opened dialog.

Task feedback is stored in the fixed <RFG_DATA_DIR>/flightarchive/log/tasks/ directory and retained across restarts. The old flightarchive/log/task/ directory is not read, migrated, or deleted. The backend worker executes its real in-memory FIFO queue; logs are feedback, not commands or a replay source. Reading interrupted history conservatively records failure, preserving successful items; without a reliable terminal record, success is not inferred. A failed task can have zero failed items and is then shown as Result Unconfirmed. Task timestamps use UTC with six fractional digits and +00:00; the frontend also accepts Z and compares instants without losing microsecond identity.


Docker Compose:

cp app/.env.example app/.env
docker compose --env-file app/.env -f app/compose.yaml up --build

For a persistent or high-speed thumbnail cache, set FLIGHTARCHIVE_CACHE_HOST_PATH and run:

docker compose --env-file app/.env -f app/compose.yaml -f app/compose.cache-host.yaml up --build

The override mounts only /cache; the resource mount remains read-only and the data mount retains RFG mapping and business state.

3 Development

Requirements

  • Docker
  • Node.js v22 or later for frontend development
  • Python 3.10 or later for backend development and tests

Install Dependency

cd app/frontend
pnpm install

cd ../backend
python -m venv .venv
. .venv/bin/activate
python -m pip install -r requirements-dev.txt

Frontend Development

cd app/frontend
pnpm dev

Frontend Compile

cd app/frontend
pnpm build

Backend Server

cd app/backend
RFG_RESOURCE_PATH=/path/for/resources \
RFG_DATA_DIR=/path/for/data \
python -m flightarchive

Tests / Typecheck

cd app/backend
python -m pytest tests -q

cd ../frontend
pnpm exec vitest run --maxWorkers=4
pnpm typecheck

Build Docker Image

docker build -f app/Dockerfile -t flightarchive:local app

On Windows, tools/BuildAll.bat builds the same local image. tools/BuildAndRunContainer.bat is a Windows helper that cleans local build artifacts, prompts for host mappings, and starts a detached container. On other platforms, use the docker run command in Usage.

4 Built With

All dependencies are open-source and licensed under permissive licenses. No copyleft (for example GPL or AGPL) components are included.

5 License

This project is released under the BSD 3-Clause License. Code may be reused with proper attribution.

Copyright (c) 2026 Mehver (https://github.com/Mehver). All rights reserved.

All dependencies are open-source and licensed under permissive licenses. No copyleft (for example GPL or AGPL) components are included.

About

Self-hosted flight archive for organizing flight history, boarding passes, airlines, airports, aircraft, and related documents.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages