OwnTracks Frontend

Introduction

This is a web interface for OwnTracks built as a Vue.js single page application. The recorder itself already ships with some basic web pages, this is a more advanced interface with more functionality, all in one place.

Features

Last known (i.e. live) locations:
- Accuracy visualization (circle)
- Device friendly name and icon
- Detailed information (if available): time, latitude, longitude, height, battery, speed and regions
Location history (data points, line or both)
Location heatmap
Quickly fit all shown objects on the map into view
Display data in a specific date and time range
Filter by user or specific device
Calculation of distance travelled
Download selected location data as JSON
Highly customisable

Installation

Docker

A pre-built Docker image is available on Docker Hub as owntracks/frontend.

You can start a container directly via docker run:

$ docker run -d -p 80:80 -e SERVER_HOST=otrecorder-host -e SERVER_PORT=8083 owntracks/frontend

Or you can use docker-compose (if you also run the OwnTracks Recorder with the default compose config, and the service is named otrecorder):

version: "3"

services:
  owntracks-frontend:
    image: owntracks/frontend
    ports:
      - 80:80
    volumes:
      - ./path/to/custom/config.js:/usr/share/nginx/html/config/config.js
    environment:
      - SERVER_HOST=otrecorder
      - SERVER_PORT=8083
    restart: unless-stopped

To change the port on which the nginx server will listen on, set the LISTEN_PORT enviroment variable - default is 80.

To build the image from source replace image: with:

build:
  context: ./owntracks-frontend
  dockerfile: docker/Dockerfile

(assuming you have this repository cloned to owntracks-frontend in the same directory as docker-compose.yml)

Manually

Run yarn install to install dependencies
Run yarn build to compile and minify for production
Copy the content of the dist/ directory to your webroot

Configuration

It's possible to get started without any configuration change whatsoever, assuming your OwnTracks API is reachable at the root of the same host as the frontend.

Copy public/config/config.example.js to public/config/config.js and make changes as you wish.

See docs/config.md for all available options.

Development

Run yarn install to install dependencies
Run yarn serve to compile for development and start the hot-reload server
Run yarn lint:js to lint JavaScript/Vue files
Run yarn lint:md to lint Markdown files
Run yarn lint:scss to lint SCSS files
Run yarn format:js to format JavaScript/Vue files
Run yarn format:md to format Markdown files
Run yarn format:scss to format SCSS files
Run yarn test to run unit tests

CORS-Proxy

You can use the corsProxy.js script to use your production instance of OwnTracks for development without making changes to its CORS-Headers:

$ yarn cors-proxy

If you have basic authentication enabled, create a .env file with your credentials:

OT_BASIC_AUTH_USERNAME=user
OT_BASIC_AUTH_PASSWORD='P@$$w0rd'

Then run:

$ env $(cat .env | xargs) yarn cors-proxy

The default host and port it binds to is 0.0.0.0:8888. Change using the OT_PROXY_HOST and OT_PROXY_PORT environment variables.

Finally update api.baseUrl in your config to "http://0.0.0.0:8888/https://owntracks.example.com".

I18n

This project uses Vue I18n. To see missing and unused i18n entries, run:

$ yarn i18n:report

To add a new locale, copy en-US.json to <locale>.json in src/locales and start translating the individual strings. Make sure to mention the new locale to the docs!

For a specific example see commit b2edda4 where German translations were added.

Contributing

Please feel free to open an issue and discuss your ideas and report bugs. If you think you can help out with something, open a PR!

psi-4ward/frontend-timeline