dedicatedcode/reitti: Self-Hosted Location Tracking with Federation

dedicatedcode/reitti: Self-Hosted Location Tracking with Federation

Location history is one of the most sensitive datasets most people generate daily, yet the dominant options require surrendering that data to cloud services with opaque retention policies. For developers and privacy-conscious self-hosters, building a personal alternative typically meant stitching together GPS loggers, map tiles, and visualization tools—a brittle stack that collapses under its own complexity. dedicatedcode/reitti offers a different path: a comprehensive, self-hosted location tracking and analysis application that keeps your movement data on infrastructure you control, while still enabling selective sharing through a federated architecture. With 2,350 GitHub stars, a Java-based backend, and active development through mid-2026, it represents one of the more mature open-source entries in this space.

What is dedicatedcode/reitti?

dedicatedcode/reitti is a self-hosted personal location tracking and analysis application designed to help users understand their movement patterns and identify significant places. The name derives from Finnish, meaning "route" or "path"—a fitting choice given the tool's emphasis on tracing how individuals move through physical space over time.

The project is maintained by dedicatedcode and published under the GNU Affero General Public License v3.0 (AGPL-3.0), a copyleft license that ensures derivative works, including network-deployed services, remain open source. The repository has accumulated 2,350 stars and 71 forks, suggesting modest but genuine community traction rather than viral hype. Java serves as the primary language, indicating a backend-oriented architecture likely optimized for throughput and long-running processing jobs rather than rapid prototyping.

Reitti's relevance stems from a confluence of trends: growing developer interest in self-hosted infrastructure, regulatory pressure on location data brokers, and the maturation of containerized deployment patterns that make personal server management tractable. Unlike simpler GPS logging tools, Reitti bundles ingestion, storage, analysis, and visualization into a single deployable unit—complete with multi-user support, real-time sharing, and integrations with popular mobile tracking apps.

The application targets a technically literate audience comfortable with Docker^{↗ Bright Coding Blog} Compose deployments and environment variable configuration. It does not position itself as a consumer product; there is no managed SaaS tier, no mobile app of its own, and no venture-backed growth playbook. This is infrastructure software for people who want to own their data pipeline end-to-end.

Key Features

Map and Timeline Visualization. The core interface pairs an interactive daily timeline with a live map view. The timeline displays visits and trips with duration and distance calculations, while the map renders raw GPS tracks, detected places, and transport-mode segments. A fullscreen live mode supports kiosk-style displays for households or small teams wanting ambient location awareness.

Visit and Trip Detection. Reitti automatically identifies locations where users spend significant time and tracks movements between them. The system classifies transport modes—walking, cycling, driving—without requiring manual tagging. This transforms raw coordinate streams into semantically meaningful events: "45 minutes at Home," "12 minute drive to Grocery Store."

Significant Places. Users can name frequently visited locations, converting detected clusters into labeled waypoints. This personal gazetteer becomes the foundation for subsequent analysis and sharing controls.

Multi-Device Data Stitching. Reitti supports tracking multiple devices per user through a workbench interface. Data from the default device auto-merges into a unified timeline; secondary devices require manual stitching by selecting the device and time range. The workbench also enables direct map-based cleanup: dragging misplaced GPS points to correct locations and deleting outliers.

Live Location Sharing. Three sharing models accommodate different trust boundaries: same-instance sharing between registered users, cross-instance federation with explicitly trusted servers, and revocable "magic links" for temporary access by unauthenticated viewers. Federation is particularly notable—live positions exchange between instances while historical data remains server-local.

Custom Map Styles. Users can upload Mapbox GL style JSON files or link to remote style URLs from providers like MapTiler or Stadia Maps, or personal tile servers. This eliminates vendor lock-in to a single cartographic aesthetic.

Immich Photo Integration. Connecting a self-hosted Immich server overlays photos on the timeline at their capture locations and times, with fullscreen viewing and keyboard navigation.

Statistics and Summaries. Distance charts, top places rankings, and transport-mode breakdowns provide quantitative insight into movement patterns over configurable periods.

Use Cases

Personal Quantified Self Infrastructure. Developers already running home servers for services like Immich, Home Assistant, or Paperless can extend their stack with location history. Reitti complements these tools through shared self-hosting patterns—Docker Compose deployments, reverse proxy configuration, and backup procedures transfer directly.

Family Location Awareness. The multi-user view and same-instance sharing enable households to maintain mutual awareness without relying on Google Location Sharing or Apple's Find My. Parents can track children's locations; partners can coordinate arrivals. Data residency stays within the household's infrastructure.

Distributed Team Coordination. Small organizations with field personnel—delivery cooperatives, maintenance crews, research teams—can federate Reitti instances across members' personal servers. Each participant retains sovereignty over their historical data while sharing live positions during active operations.

Temporary Event Sharing. Magic links suit time-bounded scenarios: sharing ETA with friends for a group arrival, letting someone track a long-distance journey, or providing visibility during outdoor activities. Revocation ensures access expires when the social context concludes.

GPS Data Archaeology. Users with years of accumulated location exports—from Google Takeout, dedicated GPS loggers, or earlier apps—can consolidate and clean this history through Reitti's import pipeline and workbench tools. The transport-mode detection and place clustering retroactively structure previously unstructured coordinate dumps.

Installation & Setup

The documented quick start uses Docker Compose. Execute these commands exactly as provided:

mkdir reitti && cd reitti
wget https://raw.githubusercontent.com/dedicatedcode/reitti/refs/heads/main/docker-compose.yml
docker compose up -d

After container startup, open http://localhost:8080. The first login prompts for admin password creation. A default API token generates automatically, enabling immediate device connection without additional configuration.

ARM64 Consideration. Apple Silicon and other ARM64 users must modify the PostGIS image due to an upstream issue tracked at postgis/docker-postgis#216. Replace the PostGIS image in docker-compose.yml with:

# In docker-compose.yml, locate the postgis service image line
image: imresamu/postgis:17-3.5-alpine

Post-Deployment Configuration. The documentation recommends this sequence:

1. Devices: Navigate to Settings → Devices and consult the Devices Guide
2. Mobile App Connection: Use Settings → Integrations with the pre-generated API token; see the Mobile App Guide
3. Historical Data Import: Access Settings → Import Data per the Data Import Guide
4. Map Customization: Configure Settings → Map Styles following the Map Styles Guide
5. Sharing Setup: Enable Settings → Live Sharing with reference to the Live Sharing Guide

Real Code Examples

The README provides explicit Docker Compose deployment commands as its primary code-oriented documentation:

# Create project directory and enter it
mkdir reitti && cd reitti

# Download the official compose file from main branch
wget https://raw.githubusercontent.com/dedicatedcode/reitti/refs/heads/main/docker-compose.yml

# Start services in detached mode
docker compose up -d

This three-step pattern prioritizes operational simplicity over configurability. The wget pulls directly from refs/heads/main, meaning the compose file reflects current development state rather than a pinned release. Production deployments should consider referencing a specific tag or commit hash for reproducibility.

The environment variable configuration table defines key runtime parameters:

# Example .env file excerpt for production customization
POSTGIS_HOST=postgis          # PostgreSQL↗ Bright Coding Blog host (default: postgis)
POSTGIS_PORT=5432             # PostgreSQL port (default: 5432)
POSTGIS_DB=reittidb           # Database name (default: reittidb)
POSTGIS_USER=reitti           # Database user (default: reitti)
POSTGIS_PASSWORD=changeme     # CHANGE THIS in production
REDIS_HOST=redis              # Redis host for caching/queues (default: redis)
REDIS_PORT=6379               # Redis port (default: 6379)
OIDC_ENABLED=true             # Enable SSO integration (default: false)
OIDC_ISSUER_URI=https://auth.example.com
OIDC_CLIENT_ID=reitti-app
OIDC_CLIENT_SECRET=secret-here
BASE_PATH=/reitti             # Serve under sub-path if behind reverse proxy

The DANGEROUS_LIFE variable warrants particular attention:

# WARNING: Enables data-reset features. Only enable during initial setup
# or when you explicitly intend to destroy and rebuild datasets.
DANGEROUS_LIFE=false          # Default: false

This guardrail prevents accidental data destruction in production. The naming convention—unconventional but memorable—reflects the irreversible consequences of activation.

Advanced Usage & Best Practices

Tag Selection Strategy. The project publishes five Docker image tags with distinct stability guarantees. For most self-hosters, the major-version tag (reitti:5) balances update receipt against breaking-change protection. Pin exact versions (reitti:5.0.2) for infrastructure-as-code deployments where reproducibility trumps convenience. Avoid next entirely—it carries explicit warnings about potential database schema corruption.

Backup Scope. Documentation specifies backing up the PostGIS database and Reitti storage volume (uploaded files, presumably including custom map styles and user content). Redis and stateless services require no backup attention. This simplifies disaster recovery to two artifacts rather than full system snapshots.

Federation Trust Model. Cross-instance sharing operates on explicit allowlisting rather than open federation. Administrators configure trusted instances individually; live positions flow only along these edges. This design choice prioritizes security over network effects—there is no global discovery mechanism or implicit trust inheritance.

Processing Tuning. The PROCESSING_BATCH_SIZE default of 1000 geo points per batch suits general deployments. Users with constrained memory or exceptionally dense track histories may need adjustment, though the README provides no specific guidance on optimal values for different hardware profiles.

Comparison with Alternatives

OwnTracks Recorder excels at minimal resource consumption and direct mobile integration but lacks analysis and visualization capabilities without additional tooling. Traccar targets commercial fleet management with device protocol breadth and alerting, making it heavier than necessary for personal use. Reitti occupies a middle ground: richer analysis than OwnTracks, more privacy-preserving architecture than Traccar's centralized model, and unique federation capabilities absent from both.

FAQ

Does Reitti require a dedicated mobile app? No. It integrates with existing apps including OwnTracks, GPSLogger, Overland, and Home Assistant. See the Mobile App Guide.

What database does Reitti use? PostgreSQL with PostGIS extension for geospatial operations.

Can I run Reitti without Docker? The README documents only Docker Compose deployment. Manual installation would require reverse-engineering from the compose file.

Is federation mandatory? No. Same-instance sharing and magic links function without configuring any external instances.

How does licensing affect my deployment? AGPL-3.0 requires sharing source code with users who interact with the service over a network. Personal or household use faces no practical obligation; commercial deployments need compliance planning.

What happens if I use the next tag? Database schema changes may occur without migration paths, risking data loss. Explicitly documented as unsuitable for production.

Does Reitti support OIDC providers beyond generic standards? The implementation uses standard OIDC discovery. Any compliant provider (Authentik, Keycloak, Authelia, commercial IdPs) should function, though specific provider quirks may require debugging.

Conclusion

dedicatedcode/reitti delivers a credible, feature-complete solution for developers and technical users seeking sovereignty over their location data. Its strengths—federated sharing with data residency, automatic transport-mode detection, multi-device stitching, and Immich integration—address real friction points in the self-hosted location stack. The AGPL-3.0 license and Java backend signal long-term maintainability intentions rather than rapid pivot potential.

The tool best serves users already committed to self-hosting infrastructure, comfortable with Docker operations, and seeking analysis capabilities beyond raw GPS logging. It is not the lightest option available, nor the simplest to deploy, but it offers a depth of functionality that lighter alternatives achieve only through external tool chaining.

For those evaluating their options, the live repository provides the compose file, issue tracker, and contribution guidelines. The project's active maintenance through July 2026 suggests continued evolution worth monitoring or participating in directly.