Self-hosted real-time location sharing platform with complete privacy and full control over your data.
NookMesh is an open-source real-time location sharing platform built around OwnTracks, MQTT, Docker, and a protected GeoJSON API, designed for users who want complete control over their infrastructure, authentication, and location data.
It was originally created for motorcycle trips among friends, but its modular architecture allows it to be adapted to families, outdoor groups, technical teams, communities, and future hybrid architectures with multiple location sources.
⚠️ Project under active development. The core architecture is functional and usable, although some capabilities continue to evolve.
- Real-time location tracking through OwnTracks + MQTT
- 100% self-hosted infrastructure
- Protected GeoJSON API with per-user authentication
- Direct visualization in Guru Maps
- Multi-user and multi-device support
- Advanced user visibility controls
- Automatic subscription and expiration management
- Modular Docker-based architecture
- Secure deployment through TLS (recommended)
- Foundation for future hybrid integrations
NookMesh currently uses:
- OwnTracks
- Mosquitto
- OwnTracks Recorder
- FastAPI
- Docker
- GeoJSON
- Guru Maps
- Subscription Service
NookMesh receives locations from mobile devices through OwnTracks, processes them within your own infrastructure, and exposes only authorized data to compatible clients.
All authentication, user management, expiration processing, visibility filtering, and access control occur entirely within your own backend.
📘 Detailed architecture documentation is available in the technical documentation.
Track the position of fellow riders during routes and long-distance trips directly in Guru Maps.
Share locations with trusted people using personalized visibility rules.
Hiking, cycling, off-roading, or any activity where coordinating positions is useful.
Manage temporary member access through automatic expirations and renewals without relying on external services.
Ideal for users who prefer full control over infrastructure, storage, and authentication.
Future integrations with mesh networks, gateways, and alternative location sources for scenarios without traditional mobile coverage.
You will need:
- Linux or a Docker-compatible NAS
- Docker Engine
- Docker Compose v2
jqopenssl- A domain or subdomains (recommended)
- Valid TLS certificates (recommended for production)
- OwnTracks app
- A compatible GeoJSON client (Guru Maps recommended)
Common supported environments:
- Synology NAS
- Ubuntu Server
- Debian
- Linux mini PCs
- Linux VPS
- Other Docker-compatible hosts
Clone the repository:
git clone https://github.com/sercontri/nookmesh.git
cd nookmeshCopy the example configuration:
cp config/users.example.json config/users.json
cp config/filtros.example.env config/filtros.env
cp config/recorder.example.env config/recorder.envEdit the configuration according to your environment.
Generate credentials and operational files:
./auth/generate.shThe generator automatically creates:
- MQTT credentials
- MQTT ACLs
- API tokens
- visibility runtime configuration
- operational user states
Start the services:
docker compose -f mqtt/docker-compose.yml up -d
docker compose -f recorder/docker-compose.yml up -d
docker compose -f worker/docker-compose.yml up -d
docker compose -f api/docker-compose.yml up -d
docker compose -f subscriptions/docker-compose.yml up -dConfigure:
- OwnTracks
- Guru Maps (or another compatible GeoJSON client)
- TLS (recommended)
NookMesh also includes a sample overlay for quick import into Guru Maps:
docs/assets/gurumaps/nookmesh_gurumaps_overlay.ms
📘 Full setup instructions are available in the technical documentation.
NookMesh is designed around a philosophy of privacy and data sovereignty.
With NookMesh:
- Your locations remain within your infrastructure
- Every user has independent MQTT credentials
- Every user receives an individual API token
- User visibility is controlled through internal rules
- Subscriptions and expirations are managed locally within your infrastructure
- Services can be protected with MQTT over TLS and HTTPS
- No mandatory dependency on external cloud platforms exists
Especially suited for users who value:
- privacy
- control
- transparency
- auditability
- self-hosting
The technical documentation includes:
- detailed installation
- users, states, and subscriptions
- visibility model
- OwnTracks integration
- Guru Maps integration
- MapCSS customization
- MQTT and TLS
- security and authentication
- GeoJSON endpoints
- internal architecture
- troubleshooting
- technical roadmap
📘 Complete Technical Documentation
NookMesh is an actively evolving project.
Planned development areas include:
- hybrid mesh network integration
- LTE + mesh deployments
- support for additional GeoJSON clients
- web-based administration panel
- improved observability
- more modular configuration
- improved deployment experience
- Docusaurus documentation portal
Contributions are welcome.
You can help by:
- reporting bugs
- proposing improvements
- improving documentation
- suggesting integrations
- submitting pull requests
- sharing real-world use cases
If you contribute code:
- do not include secrets or real credentials
- use example files
- maintain consistency with the current architecture
- document relevant changes
NookMesh is an independent project developed in personal time.
If you find it useful, you can support it by:
- ⭐ starring the repository
- 🐞 reporting bugs or improvements
- 📖 improving documentation
- 🔀 contributing code
- 📣 sharing the project
- ☕ supporting development on Ko-fi
Your support helps maintain testing infrastructure, improve documentation, and continue developing privacy-focused open-source tools.
NookMesh is distributed under the GNU Affero General Public License v3.0 (AGPLv3).
In summary:
- you may use it freely
- you may modify it
- you may deploy it on your infrastructure
- you may redistribute it
- you may offer services based on NookMesh while complying with AGPLv3 obligations
If you modify the project and provide it as a network-accessible service, those modifications must remain available under the same license.
See LICENSE for the full legal text.