OwnTracks Recorder

OwnTracks Recorder is a lightweight, self‑hosted service designed to ingest, persist, and expose GPS location data from the OwnTracks mobile apps. It consumes messages via MQTT or HTTP POST, serializes them into flat‑file storage (LMDB), and serves a RESTful API for retrieval. The entire stack is written in Go, enabling a single statically‑linked binary that runs on minimal hardware such as Raspberry Pi or edge gateways. Because it eschews external databases, deployment is trivial—no database server, migration scripts, or complex schema management are required.

Key Features

• Dual Ingestion Channels: Subscribes to an MQTT broker (using the standard paho.mqtt.golang client) or accepts raw HTTP POSTs, making it compatible with both native OwnTracks clients and custom gateways.
• LMDB Persistence: Uses Lightning Memory‑Mapped Database (LMDB) for on‑disk key/value storage. The design documents (STORE.md) detail how each MQTT topic maps to a unique LMDB transaction ID, ensuring high throughput and low latency writes even on flash storage.
• REST API & Webhooks: Exposes endpoints for last position, track segments, and live updates. A Lua hook system (HOOKS.md) allows developers to inject custom logic on message receipt, enabling transformations or side‑effects (e.g., pushing data to a time‑series database).
• Built‑in Reverse Geocoding: Caches geocode results locally, configurable precision, and supports external services via the reverse-geo module.

Technical Stack

The architecture is intentionally monolithic to reduce operational overhead. The binary contains the HTTP server, MQTT client, and storage engine—all compiled into one artifact—so developers can focus on integration rather than orchestration.

Deployment & Infrastructure

OwnTracks Recorder is designed for edge‑first scenarios. A single Docker image (ghcr.io/owntracks/recorder) can be run on a Raspberry Pi with 512 MiB RAM, yet it scales to dozens of users on a small VM. The LMDB backend is file‑system friendly, making it suitable for SSDs or even eMMC storage. The service exposes a health endpoint and Prometheus metrics (/metrics), allowing integration with Grafana dashboards or alerting systems. For high‑availability, multiple Recorder instances can share the same MQTT broker; the system uses per‑topic message IDs to deduplicate writes.

Integration & Extensibility

Developers can extend Recorder via:

• Lua Hooks: Custom scripts executed on every incoming message, enabling real‑time transformations or side‑effects (e.g., pushing to InfluxDB).
• Webhooks: Configure outbound HTTP callbacks for events like user arrival or departure.
• API Clients: The REST API supports JSON and CSV responses; authentication can be token‑based or Basic Auth.
• Reverse Proxy: The documentation details nginx and Apache setups, allowing SSL termination and path rewriting.

Because Recorder exposes a clean HTTP interface, it can be integrated into larger fleet‑management stacks or used as a data source for visualization tools like Grafana or custom dashboards.

Developer Experience

The project prioritizes clarity and minimalism. The source code is well‑structured, with a single main.go entry point and modular packages for MQTT handling, storage, and API. Documentation is comprehensive: DESIGN.md explains the message flow; STORE.md details LMDB schema; HOOKS.md shows hook API usage. Community support is active on GitHub Discussions and the OwnTracks mailing list, with frequent releases (see Travis CI badge). Configuration is file‑based (recorder.yaml), making it straightforward to tweak MQTT topics, retention policies, or reverse‑geo settings without recompilation.

Use Cases

1. Fleet Tracking: Deploy on a company’s edge gateway to collect vehicle locations, expose a live map via the REST API, and hook into a central monitoring system.
2. Personal Privacy: Users can run Recorder on their home NAS, keeping all location data locally while still benefiting from OwnTracks’ client features.
3. IoT Gateways: Combine HTTP‑to‑MQTT bridging (as described in Tips and Tricks) with Recorder to ingest data from non‑OwnTracks sensors.
4. Research Projects: Researchers needing a lightweight, self‑hosted GPS logger can deploy Recorder on low‑power nodes and export data to CSV for analysis.

Advantages

• Zero External DB: Eliminates the operational burden of PostgreSQL/MySQL, reducing attack surface and simplifying backups.
• High Performance: LMDB’s memory‑mapped design yields sub‑millisecond write times, suitable for high‑frequency location streams.
• Cross‑Platform: Single binary works on Linux, macOS, Windows; Docker images cover most container platforms.
• **Open Source