External Services
TravStats is fully functional without any external service. The core flow — log a flight, see it on the map, statistics update — works on a stock install with zero API keys configured.
External services unlock specific features. None gate the basics.
At a glance
Section titled “At a glance”| Service | Unlocks | Cost | Required for first install? |
|---|---|---|---|
| AirLabs | Live flight enrichment (route, aircraft, scheduled times) | Free tier exists, paid for non-current dates | No |
| Aviationstack | Same, but covers historical dates the AirLabs free tier doesn’t | Paid only (~$10/mo entry tier) | No |
| OpenSky Network | Real-time tracking position + free fallback | Free with login | No |
| Ollama (local LLM) | Primary email parser (recommended) + boarding-pass vision. Handles multi-flight bookings reliably, regex templates can’t | Free, runs on your hardware | No, but strongly recommended for email parsing |
| OpenAI / Anthropic | Faster / more accurate vision parsers as Ollama alternative | Pay per scan (~$0.001 per pass) | No |
| SMTP server | Invitation emails, password reset, flight reminders | Free / pay-per-volume | No (single-user instances skip it entirely) |
| WebDAV target | Off-host backup sync | Free if you self-host Nextcloud | No |
You can run TravStats forever with none of these. You can also turn them on later, one at a time, as your needs change.
Where keys go
Section titled “Where keys go”Almost all credentials are configured in Admin → Settings, encrypted
at rest with the auto-generated key under /app/data/secrets/encryption.key,
and stored in the AdminSettings or SmtpConfig tables. You never
have to edit .env again after install — env-var fallbacks exist
(see each service page) but they’re for advanced setups, not the
default path.
The only ENV-set variable that matters per-service is OLLAMA_URL,
which is seeded from the env var on first boot but can then be
overridden in the admin UI.
Pages in this section
Section titled “Pages in this section”- Flight data APIs — AirLabs, Aviationstack, OpenSky compared side-by-side. Which one to pick, how to get a key, what each gives you.
- Ollama (local LLM) — Why TravStats ships an Ollama container, how to pick a model, what changes on Pi vs Mac vs PC, how to point at an Ollama running elsewhere on your LAN.
- Vision parsers — OpenAI and Anthropic Claude as alternatives to Ollama for boarding-pass scanning. The cascade order, costs per scan, when each is worth it.
- SMTP — Sending invitation emails, password resets, and reminders. Concrete examples for Gmail, Mailgun, Sendgrid, and a self-hosted Postfix.
The WebDAV / off-host backup sync is covered on the Backups page rather than here, because it’s tightly coupled to the backup scheduler.
What gets logged when you talk to an external service
Section titled “What gets logged when you talk to an external service”Every outbound request gets logged to /app/data/logs/parser*.log
or /app/data/logs/app.log. The log line records the service, the
endpoint hit, the latency, and the response code. Request bodies
are not logged by default — your AirLabs API key won’t show up in
plaintext in your log files.
Set the log level to debug in Admin → Settings → Logging if you
want to see request payloads while troubleshooting; revert to info
afterwards or your app.log will grow fast.
What happens if a service is unreachable
Section titled “What happens if a service is unreachable”TravStats is designed to degrade gracefully when an external service is offline:
- Flight-data API down — flight saves still work; the enrichment fields stay blank, you can manually edit them in or retry later.
- Ollama down — email parsing falls back to the regex templates for the eight built-in airlines (single-leg bookings parse fine; multi-flight emails are the regex layer’s weak spot). Other carriers fall back to “no match” and manual entry. Manual entry always works.
- Vision parser down — the next parser in the cascade tries; if all fail, manual entry pre-fills with whatever OCR could read.
- SMTP down — invitations / password resets show an error; flights still log, dashboard still loads.
- WebDAV target down — local backups still happen; the off-host sync is queued and retries on the next scheduler tick.
No external service is in the critical path for “log a flight, see it on the map”.