GeoPulse

<p align="center"> <img src="frontend/public/geopulse-logo.svg" alt="GeoPulse Logo" width="180"/> </p> <h3 align="center">The open-source, privacy-first Google Timeline alternative.</h3> <p align="center"> <a href="LICENSE"><img src="https://img.shields.io/badge/License-BSL_1.1-red" alt="License"></a> <a href="https://tess1o.github.io/geopulse/docs/getting-started/deployment/docker-compose"><img src="https://img.shields.io/badge/Docker-Ready-blue.svg" alt="Docker"></a> <img src="https://img.shields.io/badge/Self--Hosted-Yes-green.svg" alt="Self-Hosted"> <img src="https://img.shields.io/badge/Privacy-First-green.svg" alt="Privacy First"> </p>

GeoPulse transforms raw GPS data from OwnTracks, Overland, Dawarich, GPSLogger, Home Assistant, and other sources into a searchable timeline of stays, trips, and movement patterns. It runs fully on your own infrastructure and integrates with Immich so your photos appear directly on your map history.

<div align="center"> <img src="images/Timeline.jpg" alt="GeoPulse Timeline" width="800" style="border-radius: 8px;"/> <p><em>Comprehensive timeline visualization with automatic trip classification.</em></p> </div>

Quick installation

# Create directory and download config
mkdir geopulse && cd geopulse
curl -L -o .env https://raw.githubusercontent.com/tess1o/GeoPulse/main/.env.example
curl -L -o docker-compose.yml https://raw.githubusercontent.com/tess1o/GeoPulse/main/docker-compose.yml

# Start
docker compose up -d

Access: http://localhost:5555
Note: For production, review your .env for security-related settings first.

Need MQTT, custom domains, or hardening? See the Docker Deployment Guide.

Why GeoPulse

Privacy-first and self-hosted: Your location data remains on your own infrastructure.
Open ecosystem: Works with popular GPS apps (OwnTracks, Overland) and tools like Immich/Home Assistant.
Full data ownership: Import historical data and export your data in standard formats anytime.
Lightweight runtime: Typically under 100MB RAM and under 1% CPU in regular usage.

Features

Timeline & Analysis

Smart Detection: Automatically converts GPS points into stays, trips, and data gaps.
Custom Logic: Fully configurable detection sensitivity and travel mode classification.
Deep Insights: Analytics for distance, visit frequency, and movement patterns over time.
Immich Integration: Photos from your library appear directly on your map timeline.

Sources & Syncing

Real-time Tracking: Supports OwnTracks (HTTP/MQTT), Overland, GPSLogger, Home Assistant, Traccar, or Colota.
Universal Import: Bulk import from Google Timeline, GPX, GeoJSON, OwnTracks exports, and CSV.

Sharing & Privacy

Friends System: Per-user visibility controls for live location and history.
Guest Access: Shareable links with optional password protection and instant revocation.
Multi-user Ready: Built-in invitations, roles, and admin audit logs.
Enterprise Auth: OIDC/SSO support alongside standard username/password login.

Platform & Performance

Lightweight: Typically under 100MB RAM and 1% CPU usage.
Self-Sovereign: No telemetry, no analytics beacons, and no third-party tracking.
Data Freedom: Full data export and per-account deletion support.
Optional AI: Bring your own OpenAI-compatible key for AI-assisted insights.

📸 Feature Tour

<details> <summary>Click to expand gallery</summary>

Dashboard

Dashboard overview with key activity metrics High-level overview of your activity.

Journey Insights

Journey insights with milestones and badges Global travel statistics, milestones, and badges.

Monthly Trends

Monthly movement stats and heatmap Monthly summaries and movement heatmap.

Location Analytics

Location analytics map view Map-first analytics similar to Timeline views.

Country/City Stats

Country and city travel statistics Track travels by country and city.

GPS Data Management

Raw GPS data management interface Inspect and manage raw location points.

AI Assistant

AI chat assistant for location data questions Natural-language queries for your data.

</details>

Deployment Options

Docker Compose

Fastest path for local and single-server use. See the Full Docker Guide.

Kubernetes / Helm

Best for managed clusters and advanced production. See the Helm Guide.

helm repo add geopulse https://tess1o.github.io/geopulse/charts
helm repo update
helm install my-geopulse geopulse/geopulse

Post-deployment steps:

Set GEOPULSE_ADMIN_EMAIL to define the first admin.
Create an account with that email and finish setup in the Admin Panel.
See Initial Setup Guide for more.

📖 Docs & Next Steps

New users: Quick Start Guide
GPS setup: GPS Sources Overview
Deployment: Docker | Kubernetes | Env Variables
Administration: Admin Panel | OIDC/SSO
Maintenance: Backup & Restore | Updating
Full documentation: Documentation Portal

📜 License & Commercial Use

GeoPulse is licensed under the Business Source License 1.1 (BSL 1.1).

Free for personal, educational, and non-commercial use.
Commercial use requires a separate commercial license.

See LICENSE for full terms.
For commercial licensing: kerriden1@gmail.com

Geopulse

Install / Use

README