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".

• 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

• 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 queue-based processing
• API Integration: RESTful API for programmatic data access and ingestion

• 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

• 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

• 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

• 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

• 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 RabbitMQ-based processing

• Java 24 or higher
• Maven 3.6 or higher
• Docker and Docker Compose
• PostgreSQL database with spatial extensions (PostGIS)
• RabbitMQ for message processing
• Redis for caching

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

   Pay special attention to the Photon REGION. This should match your main location.

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

   docker compose up -d

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.

For development or custom deployments:

1. Start infrastructure services

   docker compose up -d postgis rabbitmq

2. Build and run the application

   mvn spring-boot:run

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

Default username and password is admin

# Build the application
mvn clean package

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

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
3. Import Data: Upload your location data via Settings → Import Data
4. Set up Mobile Apps: Configure OwnTracks or GPSLogger for real-time tracking

This repository contains Docker images for the Reitti application.

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

# 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 RABBITMQ_HOST=rabbitmq \
  -e RABBITMQ_PORT=5672 \
  -e RABBITMQ_USER=reitti \
  -e RABBITMQ_PASSWORD=reitti \
  -e REDIS_HOST=redis \
  -e REDIS_PORT=6379 \
  -e REDIS_USERNAME= \
  -e REDIS_PASSWORD= 
  dedicatedcode/reitti:latest

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

• PostgreSQL with PostGIS extensions
• RabbitMQ for message processing
• Redis for caching and session storage
• Reitti application with proper networking
• Persistent data volumes
• Health checks and restart policies

• develop - Bleeding Edge: Built from every push to 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.

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. Queue Processing: Data is queued in RabbitMQ for asynchronous processing:

   • Raw location points are validated and stored
   • Processing jobs are distributed across workers
   • Queue status is monitored in real-time

3. Analysis & Detection: Processing workers analyze the data to:

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

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

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

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

Configure mobile apps for automatic location tracking:

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

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

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.

The included docker-compose.yml configuration provides a local Photon instance for complete privacy and optimal performance.

Included Configuration:

photon:
  image: rtuszik/photon-docker:1.0.0
  environment:
    - UPDATE_STRATEGY=PARALLEL
    - REGION=de
  volumes:
    - photon-data:/photon/data
  ports:
    - "2322:2322"

Storage Requirements:

• Country-specific: 1-10GB depending on country size
• Global dataset: ~200GB for the complete worldwide index
• PARALLEL mode: Doubles storage requirements during updates (400GB total for global)

Configuration Options:

• REGION: Set to your main country code (e.g., de, us, fr) to save space
• UPDATE_STRATEGY=PARALLEL: Faster updates but requires double storage space
• Remove REGION: Download complete global dataset for worldwide coverage

Benefits:

• Complete privacy - no external API calls
• Fastest response times with no rate limits
• No dependency on external service availability
• No API usage fees or quotas

Remove the Photon service from docker-compose.yml and rely solely on configured external geocoding services.

To disable Photon:

1. Remove the photon service from docker-compose.yml
2. Remove PHOTON_BASE_URL environment variable from the reitti service
3. Configure external geocoding services in Settings → Geocoding

Supported Services:

• Nominatim (OpenStreetMap)
• Custom geocoding APIs
• Multiple services with automatic failover

Benefits:

• No local storage requirements
• Immediate setup without data downloads
• Access to multiple geocoding providers

Use both Photon and external services for maximum reliability.

How it works:

1. Photon is tried first for fast local geocoding
2. External services are used as fallback if Photon returns no results
3. Automatic failover ensures continuous operation

Configuration:

• Keep Photon service in docker-compose.yml
• Configure additional geocoding services in Settings → Geocoding
• Services are tried in order with automatic error handling

For Photon:

• Plan for significant disk space (see storage requirements above)
• Initial data download can take hours to days depending on dataset size
• Consider starting with country-specific data and expanding later
• Monitor disk space during initial setup, especially with PARALLEL mode

For External Services:

• Configure multiple services for redundancy
• Check rate limits and usage policies
• Consider geographic coverage of different providers

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.

Reitti's OIDC authentication follows a flexible user matching and creation 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

• 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

• 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

• 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

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

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.

• 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

• 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, 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, 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.

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

There are multiple ways of getting support:

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

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

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