tpt-ruc-nz
A privacy-first, open-source toolkit for tracking and estimating New Zealand Road User Charges (RUC): a shared Rust core, an ESP32 reference GPS node, a static PWA, and a self-hostable backend.
Important: NZTA Section 43 disclaimer
tpt-ruc-nz is an open-source reference implementation for personal tracking, estimation and fleet telemetry. It is not an NZTA-approved distance recorder.
Under the NZ Road User Charges Act, claiming RUC deductions (such as off-road travel), or using a digital display in place of a physical licence label, requires an NZTA Approved Distance Recorder under Section 43. If you intend to use this system for official RUC licensing or tax deductions, you must apply for Section 43 approval through NZTA first.
Rates in this project are not authoritative until they have been verified against nzta.govt.nz. See DESIGN_SPEC.md.
Status
Early development. Phase 0 (foundations) and Phase 1 (core maths) are in progress. See todo.md for the full checklist.
| Component | Path | Status |
|---|
| Core: NMEA parsing, Haversine distance, coordinates | crates/tpt-ruc-core | Working, 27 tests |
| RUC rate engine | crates/tpt-ruc-core | Not started (rates need verification) |
| WASM bindings and PWA | crates/tpt-ruc-wasm, pwa/ | Planned (Phase 2) |
| ESP32 firmware | crates/tpt-ruc-firmware | Planned (Phase 3) |
| Backend | crates/tpt-ruc-backend | Working: trips, users, reports, export, rate limits, Docker (Phase 4 in progress) |
Run the server
You need Docker only. On Windows or Mac, install Docker Desktop. On Linux, install Docker Engine with the Compose plugin.
git clone <repository-url> tpt-ruc-nz
cd tpt-ruc-nz
docker compose up -d
docker compose logs tpt-ruc
The first start creates an API key and prints it in the log, under the line "No API key was set". Copy it. Every request needs it. Then check that the server answers:
curl -H "Authorization: Bearer YOUR-KEY" http://localhost:8080/v1/trips
You should see {"limit":100,"offset":0,"trips":[]}. On Windows PowerShell, use curl.exe instead of curl.
| To do this | Run |
|---|
| Stop the server, keeping your data | docker compose down |
| Start it again | docker compose up -d |
| Update after pulling new code | git pull then docker compose up -d --build |
| Change settings | Copy .env.example to .env, edit it, then docker compose up -d |
Your trips and the saved API key live in the tpt-ruc-data Docker volume. Back it up before you upgrade or delete the project.
Keep the server private. The compose file only listens on 127.0.0.1, so only this computer can reach it. Anyone who can read the Docker log can read the API key, so do not share that log. To reach the server from a phone, change the port in docker-compose.yml to 8080:8080, and put it behind an HTTPS reverse proxy such as Caddy first. The key is sent with every request, so never expose the plain HTTP port to the internet.
Without Docker: install Rust, then run cargo run -p tpt-ruc-backend from the project folder. The data and the key are kept in ./data.
Repository layout
crates/tpt-ruc-core/ Pure Rust logic, no_std compatible
pwa/ Progressive Web App (Phase 2)
hardware/ KiCad, BOM, enclosure (Phase 3 onward)
docs/ User guides and NZTA compliance notes
DESIGN_SPEC.md Design specification and locked decisions
Building
Requires the stable Rust toolchain (pinned in rust-toolchain.toml).
cargo test --workspace
# no_std check for microcontroller and WASM targets
cargo check -p tpt-ruc-core --no-default-features --target thumbv7em-none-eabihf
Licence
Dual licensed under MIT or Apache-2.0, at your option.
Copyright (c) 2026 TPT Solutions.
Every dependency must be MIT, BSD, ISC, Zlib, Unlicense/CC0 or dual MIT/Apache-2.0. This is enforced in CI by cargo-deny (see deny.toml).
Contributing
See CONTRIBUTING.md. To report a security issue, see SECURITY.md.
