boarding-pass/README.md

boarding-pass-pipeline

Photograph a boarding pass → decode its BCBP (IATA Resolution 792) PDF417 barcode → wait until the day after the flight → fetch the historical flight track from FlightAware's public site → stage it for manual review → notify via ntfy with Approve/Deny/Investigate actions → on approval, write the flight (with track) into AirTrail via its REST API.

Not part of any other microservice stack. Single container, SQLite for all local state, no task queue — a background thread handles the daily job.

Quick start

1. Copy .env.example to .env and fill in PUBLIC_BASE_URL, AIRTRAIL_BASE_URL, AIRTRAIL_API_KEY, and TZ.

   To get an AirTrail API key: log into your AirTrail instance → Account → API Keys → create a new key. This pipeline authenticates to AirTrail as that user and writes flights on their behalf.

2. Create the external Docker network shared with NPMplus, if it doesn't already exist:

   docker network create proxy
   

   (or edit docker-compose.yml to point at whatever network your NPMplus container is already on.)

3. Build and start:

   docker compose up -d --build
   

4. Add a proxy host in NPMplus pointing at boarding-pass:8080, behind Authelia, except for the two paths below (see "Approve/Deny callback paths").

5. Open the site, go to Settings, and configure your ntfy server/topic (defaults to the public ntfy.sh — use a private topic name, or point at a self-hosted ntfy with an auth token). Send a test notification to confirm it arrives.

6. Go to Upload and photograph a boarding pass to confirm end-to-end decoding works.

Approve/Deny callback paths — read this before exposing the service

ntfy's action buttons fire a plain HTTP request from wherever the notification is opened (phone, desktop) with no Authelia session. For those buttons to work, /flights/*/approve and /flights/*/reject must bypass the Authelia auth_request check in NPMplus. Add a location block like this in the proxy host's advanced config:

location ~ ^/flights/[0-9]+/(approve|reject) {
    # Bypasses Authelia for these two paths only.
    proxy_pass http://boarding-pass:8080;
}

This bypass applies to every request on that path, not just ntfy's — there is no way to distinguish "Authelia already checked this" from "anyone on the internet hit this URL directly" once the bypass is in place. Because of that, these two routes are protected only by a signed, expiring, per-flight HMAC token (tokens.py) baked into the URL — including the review page's own Approve/Reject buttons, which render a freshly-signed token on every page load rather than relying on the surrounding page being behind Authelia. Don't add a ?token= bypass anywhere else, and don't widen the nginx match beyond these two paths.

Re-running the reference data build

data/airports.csv and data/airlines.csv are trimmed snapshots of OurAirports/OpenFlights data, fetched once via scripts/build_reference_data.py and committed. Re-run it if IATA/ICAO mappings go stale:

python3 scripts/build_reference_data.py

Known corrections in reference_data.py's CARRIER_ICAO_OVERRIDES (e.g. Virgin Australia VA → VOZ, where OpenFlights has a stale VAU) take priority over the CSV and aren't touched by re-running the script.

Testing the daily job on demand

The daily job normally runs once at daily_run_time (Settings page, default 03:00 container time). To trigger it immediately against whatever is queued:

docker exec boarding-pass python -c "from scheduler import run_daily_job; run_daily_job()"

Notes

• Uploaded photos are stored under instance/uploads/; the SQLite database is instance/boarding_pass.db. Both are in the instance/ volume — back that directory up if you care about upload history.
• No OCR fallback: if barcode decoding fails, the flight is queued as decode_failed and every field is editable on the review page instead.
• AirTrail integration only ever calls its documented REST API (/api/flight/save, /api/flight/list) — it never touches AirTrail's Postgres database directly.