Reitti is a comprehensive personal location tracking and analysis application that helps you understand your movement patterns and significant places. The name "Reitti" comes from Finnish, meaning "route" or "path".

Features

Main View

Multiple Users View

Live View Mode

Statistics View

Login page

Core Location Analysis

• Visit Detection: Automatically identify places where you spend time
• Trip Analysis: Track your movements between locations with transport mode detection (walking, cycling, driving)
• Significant Places: Recognize and categorize frequently visited locations with custom naming
• Timeline View: Interactive daily timeline showing visits and trips with duration and distance information
• Raw Location Tracking: Visualize your complete movement path with detailed GPS tracks
• Multi-User-View: Visualize all your family and friends on a single map
• Live-Mode: Visualize incoming data automatically without having to reload the map
• Fullscreen-Mode: Display the map in fullscreen. Combined with the Live-Mode you got a nice kiosk-display

Data Import & Integration

• Multiple Import Formats: Support for GPX files, Google Takeout JSON, Google Timeline Exports, and GeoJSON files
• Real-time Data Ingestion: Live location updates via OwnTracks and GPSLogger mobile apps
• Batch Processing: Efficient handling of large location datasets with direct processing
• API Integration: RESTful API for programmatic data access and ingestion

Photo Management

• Immich Integration: Connect with self-hosted Immich photo servers
• Location-based Photos: View photos taken at specific locations and dates on your timeline
• Interactive Photo Viewer: Full-screen photo modal with keyboard navigation
• Photo Grid Display: Organized photo galleries for locations with multiple images

User Management & Security

• Multi-user Support: Multiple user accounts with individual data isolation
• API Token Management: Secure API access with token-based authentication
• User Profile Management: Customizable display names and secure password management

Geocoding & Address Resolution

• Multiple Geocoding Services: Support for custom geocoding providers (Nominatim, etc.)
• Automatic Address Resolution: Convert coordinates to human-readable addresses
• Service Management: Configure multiple geocoding services with automatic failover

Customization & Localization

• Multi-language Support: Available in English, Finnish, German, and French
• Unit System: Display distances in the Imperial or Metric system
• Queue Monitoring: Real-time job status and processing queue visibility
• Custom Tiles-Server: Ability to use your own tiles-server

Privacy & Self-hosting

• Complete Data Control: Your location data never leaves your server
• Self-hosted Solution: Deploy on your own infrastructure
• Asynchronous Processing: Handle large datasets efficiently with direct processing and RabbitMQ-based task scheduling

Getting Started

Prerequisites

• Java 25 or higher
• Maven 3.6 or higher
• Docker and Docker Compose
• PostgreSQL database with spatial extensions (PostGIS)
• Redis for caching and queueing

Quick Start with Docker

The easiest way to get started is using Docker Compose:

1. Get the docker compose file

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

   or manually downloading it here

2. Adjust the compose-file to your needs

3. Start all services (PostgreSQL, RabbitMQ, Redis and Reitti)

4. Access the application at http://localhost:8080

5. Login with admin:admin

Note for ARM64 users (Apple Silicon, etc.): Until postgis/docker-postgis#216 is fixed by the PostGIS team, users wanting to run Reitti on ARM64 platforms need to change the PostGIS image in the docker-compose file from image: postgis/postgis:17-3.5-alpine to image: imresamu/postgis:17-3.5-alpine.

Development Setup

For development or custom deployments:

1. Start infrastructure services

   docker compose up -d postgis rabbitmq

2. Build and run the application

3. Access the application at http://localhost:8080

Default username and password is admin

Building Docker Image

# Build the application
mvn clean package

# Build the Docker image
docker build -t reitti/reitti:latest .

Initial Configuration

After starting the application:

1. Generate API Token: Create an API token in Settings → API Tokens for mobile app integration
2. Configure Geocoding: Add geocoding services in Settings → Geocoding for address resolution. See Reverse Geocoding Options
3. Import Data: Upload your location data via Settings → Import Data. See Data Import
4. Set up Mobile Apps: Configure one of the supported apps for real-time tracking. See Mobile App Integration

Docker Deployment

This repository contains Docker images for the Reitti application.

Production Deployment

For production use, we recommend using the provided docker-compose configuration:

# Pull the latest image
docker pull dedicatedcode/reitti:latest

# Start all services
docker compose up -d

# View logs
docker compose logs -f reitti

Standalone Docker Usage

# Run standalone with environment variables
docker run -p 8080:8080 \
  -e POSTGIS_HOST=postgres \
  -e POSTGIS_PORT=5432 \
  -e POSTGIS_DB=reittidb \
  -e POSTGIS_USER=reitti \
  -e POSTGIS_PASSWORD=reitti \
  -e REDIS_HOST=redis \
  -e REDIS_PORT=6379 \
  -e REDIS_USERNAME= \
  -e REDIS_PASSWORD= 
  dedicatedcode/reitti:latest

Docker Compose Configuration

The included docker-compose.yml provides a complete setup with:

• PostgreSQL with PostGIS extensions
• Redis for caching and queueing
• Reitti application with proper networking
• Persistent data volumes
• Health checks and restart policies

Environment Variables

Tags

• next - ⚠️ DANGER: ALPHA BUILD ⚠️ This is an alpha build that is recreated on every push to the next branch. DO NOT USE THIS TAG unless you are a developer testing the next version. It is guaranteed to have bugs, may delete your database, and can break your data. NOT FOR PRODUCTION OR IMPORTANT DATA.
• develop - Bleeding Edge: Built from every push to the main branch. For developers and early adopters who want the newest features and don't mind potential instability.
• latest - Stable Release: Updated with each stable release. For most users who want reliable, tested functionality with new features.
• x.y.z - Conservative: Specific version releases for users who want full control over updates and prefer to manually choose when to upgrade.

Data Flow & Architecture

Location Data Processing Pipeline

1. Data Ingestion: Location data enters the system via:

   • File uploads (GPX, Google Takeout, GeoJSON)
   • Real-time mobile app integration (OwnTracks, GPSLogger)
   • REST API endpoints

2. Analysis & Detection: The application directly processes the data to:

   • Detect significant places where you spend time
   • Identify trips between locations
   • Determine transport modes (walking, cycling, driving)
   • Calculate distances and durations

3. Storage & Indexing: Results are stored in PostgreSQL with:

   • Spatial indexing for efficient geographic queries
   • Temporal indexing for timeline operations
   • User data isolation and security

4. Task Scheduling: Redis is used for scheduling background tasks:

   • Reverse geocoding requests
   • User notifications
   • Other asynchronous operations

5. Visualization: Web interface displays processed data as:

   • Interactive timeline with visits and trips
   • Map visualization with location markers
   • Photo integration showing images taken at locations
   • Statistical summaries and insights

Mobile App Integration

Configure mobile apps for automatic location tracking:

• OwnTracks: Privacy-focused location sharing
• GPSLogger: Lightweight Android GPS logging
• Overland: Lightweight IOS GPS logging
• Home-Assistant: Use Home-Assistant to send location data
• Custom Apps: Use the REST API for custom integrations

Photo Integration

Connect with Immich photo servers to:

• Display photos taken at specific locations
• Show images on the timeline map
• Browse photo galleries by location and date

Reverse Geocoding Options

Reitti supports multiple approaches for reverse geocoding (converting coordinates to human-readable addresses). You can choose the option that best fits your privacy, performance, and storage requirements. For more information, visit the Reverse Geocoding Guide.

Open ID Connect (OIDC)

Reitti supports using a third party OIDC provider for sign-ins. It provides the following environment variables which are required for OIDC authentication.

• OIDC_ENABLED
• OIDC_CLIENT_ID
• OIDC_CLIENT_SECRET
• OIDC_ISSUER_URI
• OIDC_SCOPE (optional: should usually be set to "openid,profile")

Setting OIDC_ENABLED = true enables OIDC, whereas the remaining need to be found from your OIDC provider, e.g. github. See the Environment Variables section for examples.

For detailed OIDC configuration instructions and provider-specific examples, see the OIDC documentation.

There are two URLs provided by reitti that you should give to your OIDC provider (see their documentation for further information on this), one of which is required.

• (Required) Callback URL: https:///login/oauth2/code/oauth (e.g. https://reitti.internal/login/oauth2/code/oauth)
• (Optional) Logout callback URL: https:///logout/connect/back-channel/oauth

The logout callback URL will allow your OIDC provider to sign you out of Reitti when you sign out from your provider. If you don't set it, you will have to manually sign out of Reitti even if you sign out from your OIDC provider.

Login Requirements

Reitti's OIDC authentication follows a flexible user matching and creation process:

User Matching Process

1. Primary Match: First attempts to find an existing user by external_id (format: {issuer}:{subject})
2. Fallback Match: If no external_id match, searches for a user with the OIDC preferred_username
3. Account Linking: When a username match is found, the account is updated with the external_id for future logins

User Creation

• Automatic Registration: When OIDC_SIGN_UP_ENABLED=true (default), new users are automatically created if no match is found
• Registration Disabled: When OIDC_SIGN_UP_ENABLED=false, login fails with an error if no existing user matches

User Data Handling

• Username: Set to the OIDC preferred_username
• Display Name: Updated from OIDC name claim on each login
• External ID: Set to {issuer}:{subject} for permanent account linking
• Profile URL: Updated from OIDC profile claim if available
• Avatar: Automatically downloaded from OIDC picture claim if provided

Password Management

• Local Login Enabled (DISABLE_LOCAL_LOGIN=false): Existing passwords are preserved, allowing both OIDC and local authentication
• Local Login Disabled (DISABLE_LOCAL_LOGIN=true): Passwords are cleared from accounts to enforce OIDC-only authentication

Required OIDC Claims

Your OIDC provider must provide these claims for successful authentication:

• sub (subject) Required for external_id generation
• preferred_username - Required for username assignment
• name - Recommended for display name
• profile - Optional for profile URL
• picture - Optional for avatar download

PKCE

To enable PKCE for the OIDC Client, you need to set OIDC_AUTHENTICATION_METHOD to none and make sure that you do not set OIDC_CLIENT_SECRET.

Security Considerations

• External IDs are immutable once set, ensuring account security even if usernames change in the OIDC provider
• User data is updated on each login to keep information current
• Avatar downloads are performed securely with error handling for network failures

Technologies

Backup & Data Persistence

• Backup Requirements:
  • The PostGIS database needs to be backed up regularly. This database contains all user location data, analysis results, and other persistent information.
  • The storage path used by Reitti needs to be backed up regularly. This contains uploaded files.
• Stateless Services: All other components (RabbitMQ for task scheduling, Redis, Photon, etc.) are stateless and do not store any important data. These can be redeployed or restarted without risk of data loss.

Recommended Backup Strategy:

• Use standard PostgreSQL backup tools (such as pg_dump or physical volume snapshots) to back up your database.
• Back up the entire storage directory/volume used by Reitti for file storage.
• Ensure backups are performed regularly and stored securely.
• No backup is needed for RabbitMQ (task scheduling), Redis, Photon.

Restore:

• In case of disaster recovery, restore both the PostGIS database and the storage path to recover all user data and history.

For more details, see the Reitti backup documentation.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Getting support

There are multiple ways of getting support:

• create a new issue
• tag me on Lemmy
• or join #reitti on irc.dedicatedcode.com

Translations

We are using weblate to translate Reitti. If you want to add your language, click on this link

Support the Project

Star History

License

This project is licensed under the MIT License, see the LICENSE file for details.