GeoPulse

The self-hosted, source-available Google Timeline alternative.

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

Comprehensive timeline visualization with automatic trip classification.

---

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 support for OwnTracks, Kubernetes, Unraid, Proxmox or bare-metal installation? See the deployment options.

---

Why GeoPulse

• Self-hosted, no telemetry: Your location data remains on your own infrastructure.
• Open ecosystem: Works with popular GPS apps (OwnTracks, Overland, GPSLogger, Home Assistant, Colota, Traccar) and tools like Immich, Memos, and Weather.
• 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.
• Accessible & Localized: Currently available in English and Ukrainian, ensuring an inclusive experience across different regions.

---

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.
• Map Matching: Valhalla-backed route refinement makes noisy trip paths follow roads and paths while raw GPS remains authoritative.
• Panoramax: Optional public street-level imagery coverage and photo viewing on Timeline maps.
• Immich Integration: Photos from your library appear directly on your map timeline.
• Memos Integration: Timestamped notes from Memos can appear alongside your timeline.
• Weather Integration: Current weather enrichment is enabled by default for trips, stays, map layers, and journey insights; historical backfill is admin opt-in. See Weather processing architecture.

Sources & Syncing

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

AI Chat & MCP

• AI Chat: Bring your own OpenAI-compatible key for AI-assisted insights.
• MCP Server: Read-only, API-token-authenticated tools for AI clients to query their timeline and permitted friend data.

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.
• Backup & Restore: Encrypted, password-protected full backups with manual restore and scheduled automatic backups.

---

🏠 Home Assistant Integration

The GeoPulse for Home Assistant integration (installed via HACS) connects Home Assistant to GeoPulse with a single API token, in both directions:

• Home Assistant → GeoPulse: forward device_tracker and person entities. Points are queued on disk and retried, and recorder history can be backfilled.
• GeoPulse → Home Assistant: your current stay or trip and its place, today's distance, trips and stays, a presence tracker, friends on the map, and server health.
• Automations: events for geofence enter/leave, stay/trip started/ended, and tracking lost/resumed.

Requires GeoPulse 2.0+ and Home Assistant 2026.3+. See the integration README for setup.

---

📸 Feature Tour

Timeline & route replay Stays, trips, and data gaps with travel modes, weather, and step-by-step trip replay.
Location Analytics Explore every visit by map, city, and country.
Dashboard Selected period, 7-day, and 30-day overviews with charts, top places, and route stats.	Rewind Monthly and yearly summaries of distance, trips, highlights, and heatmaps.
Journey Insights Countries, cities, time patterns, weather, milestones, and badges.	City details Visit overview, top places, and every visit in a city.
Trip Plans Plan stops with travel modes and routed legs, then compare the plan with what you actually visited.
Location Sources Connect OwnTracks, Overland, GPSLogger, Home Assistant, Traccar, Dawarich, or Colota.	GPS Data Inspect, filter, and export raw location points.
Export & Import Full backups and GPX, GeoJSON, OwnTracks, or CSV exports with a date range.	Personal Settings Language, time zone, units, map appearance, and connected apps.
Administration Instance health, usage, users, backups, and audit logs.	System Settings Authentication, geocoding, weather, map matching, and more without restarts.
Mobile The web app works on phones and installs as a PWA.

Deployment Options

Choose the installation path that matches your environment:

Installation type	Best for	Guide
Docker Compose	Fastest path for local and single-server use	Docker Compose Guide
Unraid	Unraid NAS and homelab servers using Docker Compose	Unraid Guide
Proxmox VE LXC	Proxmox homelabs and VM hosts that prefer LXC containers	Proxmox VE LXC Guide
Kubernetes / Helm	Managed clusters and production Kubernetes environments	Kubernetes Quick Install
Helm values reference	Advanced Helm customization	Helm Values Reference
Manual installation	Bare metal servers or VMs without Docker/Kubernetes	Manual Installation Guide
Environment configuration	Reviewing all runtime settings	Environment Variables Reference

Kubernetes / Helm Quick Install

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

Or install the signed OCI chart from GHCR: helm install my-geopulse oci://ghcr.io/tess1o/charts/geopulse

Post-deployment steps:

1. Create the first account to become admin automatically, or set GEOPULSE_ADMIN_EMAIL for an explicit admin email.
2. Finish setup in the Admin Panel.
3. See Initial Setup Guide for more.

---

📖 Docs & Next Steps

• New users: Quick Start Guide
• GPS setup: GPS Sources Overview
• Home Assistant: GeoPulse for Home Assistant
• Deployment: Docker | Unraid | Proxmox | Kubernetes | Manual | 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