gpstracker/README.md

GPSTracker

Track your GPS data, from any data source

• Configuration
• Docker installation
• Local installation
  • Build
  • Run
• Usage
  • Initial setup
  • Ingestion
  • External data sources
• Development
  • Compile and Hot-Reload for Development
    • Backend
    • Frontend

GPSTracker is a simple Webapp that consists of:

• A backend that:
  • Can manage GPS data stored on a local db or on any compatible data source (supported: postgres, mysql, mariadb, mongodb, sqlite, snowflake), with arbitrary complex filtering, and expose them over a simple Web API.
  • Can ingest GPS location updates from HTTP.
• A frontend to display GPS data points and provides advanced filtering.

It is meant as a self-hosted and privacy-aware alternative to services like Google Maps Timeline.

Configuration

cp .env.example .env

See the provided .env.example for a reference.

Docker installation

docker compose up

Local installation

Build

Requirements:

• node
• typescript
• make

make

Or, if you want to build the backend and the frontend separately:

# Backend
make backend

# Frontend
make frontend

Run

npm run start

Usage

Initial setup

Once the application is running, you can access the frontend at http://localhost:3000 - or on whatever port you configured in the .env file.

Use the ADMIN_EMAIL and ADMIN_PASSWORD values from the .env file to log in.

You can then create a new device for your GPS data under the Devices menu, or at http://localhost:3000/devices. Take note of the deviceId, you will need it to ingest data.

Then create a new API token from the API menu, or at http://localhost:3000/api.

Ingestion

The application exposes a POST endpoint at /gpsdata that accepts a JSON payload containing the GPS data to ingest. Example:

curl -XPOST \
  -H "Authorization: Bearer your-api-token" \
  -H "Content-Type: application/json"
  -d '[{
      "deviceId": "your-device-id",
      "latitude": 40.7128,
      "longitude": -74.0060,
      "address": "260 Broadway",
      "locality": "New York, NY",
      "country": "us",
      "postalCode": "10007",
      "description": "New York City Hall",
      "timestamp": "2021-01-01T00:00:00Z"
    }]' http://localhost:3000/api/v1/gpsdata

You can wrap this in a script to ingest data from a file, or from a GPS tracker.

You can also configure a mobile app like GPSLogger to periodically send data to the endpoint - select Custom URL and use the /gpsdata endpoint with the API token as the Authorization header under the HTTP Headers section.

Or, for more advanced use cases, you can use a general-purpose application like Tasker in combination with AutoLocation to send data to the endpoint, or decouple the ingestion from the frontend by using an intermediate MQTT or Kafka broker.

External data sources

By default, the application will store the GPS data under the configured DB_URL database.

If you have an existing database with GPS data, you can configure it in the .env file through the DB_LOCATION_URL variable. The application will then read the data from the external source and expose it through the API.

Consult the .env.example file if the column names in your database differ from the default ones.

Note however that:

• The external data source must have a deviceId column (or whatever column name you configured in the .env file) that uniquely identifies the device that generated the data, and it must point to a valid device in the application database.

• Changes to the ownership of the devices or deletion of devices in the application database will not be reflected in the external data source.

Development

Compile and Hot-Reload for Development

Backend

npm run dev

Frontend

cd frontend
npm run dev