WayPointDB is a lightweight GPS data collection API, just like Google's Timeline feature, that interacts with a PostgreSQL database and is deployed using Docker and Nginx. WayPointDB is focused on fast and efficient data collection and retrieval, so the user wont have to wait around for the webpage to load or the data to be processed, and can easily sift through their data using the Stats and Map pages.
- Multi-User support
- Multi-Trace per User support
- REST API for GPS data collection
- Pure Flask-Jinja-based interface
- Server side rendering for fast page loads
- Dockerized deployment
Map page
Stats page
Import page
Lifetime Heatmap
To run this project, you could use the following tools:
- Docker
- Docker Compose v2.24 or newer
To install the project, clone the repository, change directory to the project folder, build the Docker image, and run the Docker container (-d for detached mode)
git clone https://github.com/yniverz/WayPointDB
cd WayPointDB
docker compose build
docker compose up -dThe repo can also be deployed as a Portainer stack from Git: Stacks → Add stack → Repository, URL https://github.com/yniverz/WayPointDB, reference refs/heads/main (or a release tag such as refs/tags/v0.3.4), compose path docker-compose.yml. Set your settings (POSTGRES_PASSWORD, PHOTON_SERVER_*, TZ, ...) as the stack's environment variables; Portainer stores them in stack.env, which overrides the defaults from .env. To update, use "Pull and redeploy" (with re-build) or enable Portainer's automatic updates.
The project can be configured by modifying variables in the docker-compose.yml file. The following variables are commonly modified:
.env:PHOTON_SERVER_*The host, HTTPS status, and an optional API key of the Photon server (see Photon Server)- nginx: ports:
80:80The first port is the port at which WayPointDB is accessible, and can be customized to an available port on the host machine.
The project can be accessed by navigating to the IP address of the host machine on the specified port. Log in with the default credentials: admin@example.com and password. The E-Mail and password can be changed in the Account page and is strongly recommended.
There are currently two ways to collect GPS data using a mobile device:
- Using the Overland app, which can be configured to send data to WayPointDB using the
/api/v1/gps/overland?api_key=<KEY>API endpoint. - Using the OwnTracks app, which can be configured to send data to WayPointDB using the
/api/v1/gps/owntracks?api_key=<KEY>API endpoint - Apple AirTags are also finally supported using the WayPointDB AirTag Integration
Note: I recommend using the Overland app, as it is easy to setup and does not require an account.
/api/v1/gps/overlandcan also be reached using/api/v1/overland/batches/api/v1/gps/owntrackscan also be reached using/api/v1/owntracks/points
GPS data can be imported from a json file using the Import page, accessible from the Account page. The json file should be in a specific format, and an example can be found on the import page.
You can import GPS data from various sources, such as Google Timeline, GPX and GeoJson files. In order to do so, you need to transform the data to the required format. WayPointDB provides a transformation tool that can be accessed by visiting the /static/transform page and selecting the appropriate format.
First select an available format, then select the file to be transformed. After downloading the transformed file, you can import it using the Import page.
An API key for each user can be generated in the respective Account page, and is required for API requests.
WayPointDB has a Swagger API documentation page that can be accessed by navigating to /api/v1/docs.
Users can be added, edited, and deleted in the Manage Users page. Only admin users can view this page.
Users can add additional traces to their account in the Manage Traces page accessible from the Account page. These traces are like profiles for each account and can be selected in the menu bar. Traces can be shared or transfered to other users as well.
The WayPointDB iOS App is a native iOS app that can be used to view and manage WayPointDB data. It is a work in progress and is not yet fully functional.
Note: This app does NOT collect any gps data. use one of the options above instead. The iOS app is not available on the App Store, but can be built from source using Xcode.
Each user can schedule jobs (e.g. geocoding new points or generating statistics) on the Jobs page. Every enabled job runs once a day at the selected hour. New users start with geocoding of new points and statistics generation scheduled at 00:00.
The hour refers to the server time, which is UTC unless you set a timezone in the .env file:
TZ=Europe/BerlinTo get the latest release and automatically rebuild the image you can run ./update.sh. If you for some reason want the latest unreleased verion of the project, as found in the main branch, you can use the --unreleased flag.
WayPointDB can use a Photon server for reverse geocoding. It is recommended to use a self-hosted instance of the Photon server to avoid rate limiting, and to ensure the privacy of the data. Some hosting providers use an api key for authentication, which can be set in the .env file. WayPointDB will pass this as the X-Api-Key header in the requests to the Photon server.
To use Photon, set the following environment variables in the .env file in the project root (it is loaded into the backend container and is not tracked by git, so your settings survive updates):
# e.g. photon.komoot.io, optionally with :port
PHOTON_SERVER_HOST=photon.domain.tld
# false if the server uses plain HTTP (default: true)
PHOTON_SERVER_HTTPS=true
# optional, only if the server requires an api key
PHOTON_SERVER_API_KEY='your-api-key'Geocoding sends up to 4 requests to the Photon server in parallel. Set PHOTON_SERVER_CONCURRENCY to change this, e.g. to 1 for a public server with rate limits.
Wrap the API key in single quotes if it contains special characters such as \, $, # or spaces. After changing .env, recreate the backend container with docker compose up -d --force-recreate backend.