LocationHistory

Build status:

Private, self-hosted, and secure location tracking.

LocationHistory is an open-source alternative to Google's "Find Your Phone" (and essentially also Google Timeline). It allows you to track your device's location, store the data on your own server, and visualize your history without sharing your data with third parties.

• Designed with privacy as the core feature, LocationHistory ensures that your movement data remains your own.
• Completely FOSS - only uses open source libraries.
• (Of course) completely free of external tracking or adverts.

How To Use It

1. Get the Android app from the releases page (F-Droid releases hopefully coming soon!)
2. To host your LocationHistory server via Docker Compose, you just need 2 files:
   1. Copy the example docker-compose.yml (you shouldn't need to change anything here)
   2. Copy the example .env file into the same directory and customise the variables according the explanations
3. Run with docker compose up
4. You should now have a working location history server! Check connectivity via the app.

Security

Client communication uses auto-generated self-signed SSL certificates, with a TOFU (trust-on-first-use) model.

⚠ By default the admin endpoint is NOT using SSL, in order to enable a user-friendly setup (i.e. avoiding self-signed certificate headaches).

Therefore, unless you configure SSL for the UI, logging into the backend should only be done on your local network & not exposed externally (otherwise your admin password could be exposed)!

Optional SSL setup is coming soon.

---

Project Structure

This repository is a monorepo containing all components:

Component	Description
Server	The gRPC backend that ingests and stores location data, also serving the UI
Client	Native Android application for battery-friendly background location syncing
UI	Modern TypeScript-based web dashboard for visualizing history.
Shared	Shared protocol definitions and logic.

Getting Started

Prerequisites

• Java 17+ (Required for Server & Android builds)
• Node.js 18+ & npm (Required for UI)
• sbt (Scala Build Tool)
• Docker (For packaging and running locally)

Build & Run

We use a root Makefile to orchestrate builds across the entire stack.

Running locally

This is a quick way to run everything locally.

See each individual component README for instructions how to customise the environment.

# Note that you'll need to run each of these commands in individual shells
# Run the server
RUN_ARGS='--admin-password=password --storage-type=in_memory' make -C server run
# Run the UI proxy
make -C ui run-proxy
# Run the UI
make -C ui init-local-env run

Running locally via Docker

If you want to test the full Docker stack, you can run like so:

1. Make a copy of the example docker-compose.yml and .env file
2. Customise it to your liking (it might just work out of the box though)
3. Package everything locally: make package-all
4. Run docker compose up

Your components should be running on ports specified in the .env file.

Pushing to a local test server

Note that this is quite setup dependant, but you should be able to run something like this to build everything locally and push & reload containers on a local server.

TEST_SERVER=<user>@<server> USE_DOCKER=true PLATFORM=linux/amd64 make package-all push-test

License

This project is licensed under the GPLv3 License.