69 lines
2.0 KiB
Markdown
69 lines
2.0 KiB
Markdown
# OpenJSP Bus Tracker
|
|
|
|
Real-time Skopje public transport tracking with Bun, GTFS/GTFS-RT ingestion, parquet persistence, and optional S3-compatible segment upload.
|
|
|
|
## What Is In This Repo
|
|
|
|
- `bus-tracker-json.ts`: terminal tracker for one stop + one route.
|
|
- `index.ts`: continuous collector for multiple routes/stops.
|
|
- `lib/storage.ts`: parquet write layer with rolling segments and optional S3 upload.
|
|
- `lib/gtfs.ts`: GTFS CSV loading helpers.
|
|
- `config.ts`: API base URL, defaults, and tracker timing.
|
|
|
|
## Requirements
|
|
|
|
- Bun 1.x+
|
|
- Network access to the configured GTFS/JSON upstream APIs
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
bun install
|
|
bun run typecheck
|
|
```
|
|
|
|
Run single stop/route terminal tracker:
|
|
|
|
```bash
|
|
bun run bus-tracker-json.ts
|
|
```
|
|
|
|
Run with custom stop and route IDs:
|
|
|
|
```bash
|
|
bun run bus-tracker-json.ts --stop 1571 --route 125
|
|
```
|
|
|
|
Run background collection pipeline:
|
|
|
|
```bash
|
|
bun run start
|
|
```
|
|
|
|
## Environment
|
|
|
|
Copy `.env.example` to `.env` and adjust values as needed.
|
|
|
|
Key variables:
|
|
|
|
- `PARQUET_DIR`: local output directory for parquet files.
|
|
- `PARQUET_ROLL_MINUTES`: segment rotation interval.
|
|
- `SAVE_ALL_VEHICLE_SNAPSHOTS`: save full raw vehicle feed snapshots.
|
|
- `SAVE_ALL_VEHICLE_POSITIONS`: persist all vehicle positions (not only route-matched).
|
|
- `S3_ENABLED`: enable object storage upload.
|
|
- `S3_BUCKET`, `S3_REGION`, `S3_ENDPOINT`, `S3_PREFIX`: object storage target.
|
|
- `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`: object storage credentials.
|
|
- `S3_DELETE_LOCAL_AFTER_UPLOAD`: delete local parquet after successful upload.
|
|
- `S3_UPLOAD_RETRIES`, `S3_UPLOAD_RETRY_BASE_MS`: upload retry behavior.
|
|
|
|
## Scripts
|
|
|
|
- `bun run start`: collector entrypoint (`index.ts`).
|
|
- `bun run typecheck`: TypeScript no-emit check.
|
|
|
|
## Notes
|
|
|
|
- Generated parquet files are intentionally ignored by git (`data/**/*.parquet`).
|
|
- The collector rotates segments and uploads each closed segment when S3 is enabled.
|
|
- On process shutdown (`SIGINT`/`SIGTERM`), writers are flushed so the current segment is finalized.
|