frontend/docs/config.md

Configuration

Overview

All custom configuation is stored in window.owntracks.config, which is a regular JavaScript object - so you can use template strings, spread syntax, comments and other JS features.

Some of the application state is synced to the URL's query parameters. If a parameter exists in the URL query, it takes precedence over the configured value - otherwise the configured value will be used and appended to the URL query.

Start with this:

window.owntracks = window.owntracks || {};
window.owntracks.config = {};

WARNING: if your configuration contains private data (most commonly your tile server access key), make sure to protect access to it properly, e.g. with basic authentication.

Options

• api
  • baseUrl
• endDateTime
• ignorePingLocation
• locale
• map
  • attribution
  • center
    • lat
    • lng
  • circle
  • circleMarker
  • controls
    • scale
      • display
      • imperial
      • maxWidth
      • metric
      • position
    • zoom
      • display
      • position
  • heatmap
    • blur
    • gradient
    • max
    • radius
  • layers
    • heatmap
    • last
    • line
    • points
  • maxNativeZoom
  • maxPointDistance
  • maxZoom
  • polyline
  • url
  • zoom
• onLocationChange
  • reloadHistory
• primaryColor
• selectedDevice
• selectedUser
• startDateTime
• verbose

api.baseUrl

Base URL for the recorder's HTTP and WebSocket API. Keep CORS in mind.

• Type: String
• Default: current protocol and host
• Examples:

  // API requests will be made to https://owntracks.example.com/api/0/...
  window.owntracks.config = {
    api: {
      baseUrl: "https://owntracks.example.com"
    }
  };
  

  // API requests will be made to https://example.com/owntracks/api/0/...
  window.owntracks.config = {
    api: {
      baseUrl: "https://example.com/owntracks/"
    }
  };
  

endDateTime

Initial end date and time (browser timezone) for fetched data.

• Type: Date
• Default: today, 23:59:59
• Example:

  // Data will be fetched up to 1970-01-01
  window.owntracks.config = {
    endDateTime: new Date(1970, 1, 1)
  };
  

ignorePingLocation

Remove the ping/ping location from the fetched data. This is useful when using the owntracks/recorder Docker image which has it enabled for health checks by default.

• Type: Boolean
• Default: true
• Example:

  // Don't ignore ping/ping location. Not sure why you'd do this :)
  window.owntracks.config = {
    ignorePingLocation: false
  };
  

locale

The language to use for the user interface. Available: de (German), en (English).

• Type: String
• Default: "en"

map.attribution

Attribution for map tiles.

• Type: String (may contain HTML)
• Default: "&copy; <a href="https://osm.org/copyright">OpenStreetMap</a> contributors"
• Example:

  // Make sure to add proper attribution!
  window.owntracks.config = {
    map: {
      attribution: "Map tiles © MyTileServerProvider"
    }
  };
  

map.center.lat

Initial map center latitude.

• Type: Number
• Default: 0

map.center.lng

Initial map center longitude.

• Type: Number
• Default: 0

map.circle

Location accuracy indicator configuation. color and fillColor default to primaryColor if null. See Vue2Leaflet l-circle documentation for all possible values.

• Type: Object
• Default:

  {
    color: null,
    fillColor: null,
    fillOpacity: 0.2
  }
  

map.circleMarker

Location point marker configuation. color defaults to primaryColor if null. See Vue2Leaflet l-circle-marker documentation for all possible values.

• Type: Object
• Default:

  {
    color: null,
    fillColor: "#fff",
    fillOpacity: 1,
    radius: 4
  }
  

map.controls.scale.display

Whether to show scale control or not.

• Type: Boolean
• Default: true

map.controls.scale.imperial

Whether to show an imperial scale (ft) or not.

• Type: Boolean
• Default: true

map.controls.scale.maxWidth

Maximum width of the scale control in pixels.

• Type: Number
• Default: 200

map.controls.scale.metric

Whether to show an metric scale (m) or not.

• Type: Boolean
• Default: true

map.controls.scale.position

Scale control position on the map. See Leaflet control position documentation for all possible values.

• Type: String
• Default: "bottomleft"

map.controls.zoom.display

Whether to show zoom control or not.

• Type: Boolean
• Default: true

map.controls.zoom.position

Zoom control position on the map. See Leaflet control position documentation for all possible values.

• Type: String
• Default: "topleft"

map.heatmap.blur

Heatmap blur radius.

• Type: Number
• Default: 15

map.heatmap.gradient

Mapping of values between 0 and 1 to different colors. Defaults to simpleheat's default gradient if null.

• Type: Object or null
• Default: null

map.heatmap.max

Heatmap max data value.

• Type: Number
• Default: 20

map.heatmap.radius

Heatmap point radius.

• Type: Number
• Default: 25

map.layers.heatmap

Initial visibility of the heatmap layer.

• Type: Boolean
• Default: false

map.layers.last

Initial visibility of the last locations layer.

• Type: Boolean
• Default: true

map.layers.line

Initial visibility of the line layer.

• Type: Boolean
• Default: true

map.layers.points

Initial visibility of the points layer.

• Type: Boolean
• Default: false

map.maxNativeZoom

This is being used to fetch tiles in different resolutions - set to the highest value the configured tileserver supports.

• Type: Number
• Default: 19

map.maxPointDistance

Maximum distance (in meters) between points for them to be part of the the same line. This avoids straight lines going across the map when there's a ceartain distance between two points (which often indicates that they're not related). Set to null to disable splitting into separate lines.

• Type: Number or null
• Default: null
• Example:

  // Don't connect points with a distance of more than 1km
  window.owntracks.config = {
    map: {
      maxPointDistance: 1000
    }
  };
  

map.maxZoom

Allow zooming closer than the tile server supports, which will result in (slightly) blurry tiles on higher zoom levels. Set to the same value as map.maxNativeZoom to disable.

• Type: Number
• Default: 21

map.polyline

Location point marker configuation. color defaults to primaryColor if null. See Vue2Leaflet l-polyline documentation for all possible values.

• Type: Object
• Default:

  {
    color: null,
    fillColor: "transparent"
  }
  

map.url

Tile server URL. For more information see Leaflet tile layer documentation and this Wikipedia article.

• Type: String
• Default: "https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png"
• Example:

  // Use dark HDPI tiles from Mapbox
  window.owntracks.config = {
    map: {
      url: "https://api.mapbox.com/v4/mapbox.dark/{z}/{x}/{y}@2x.png?access_token=xxxxxxxxxxxxxxxx"
    }
  };
  

map.zoom

Initial map zoom level.

• Type: Number
• Default: 19

onLocationChange.reloadHistory

Whether to reload the location history (of selected date range) or not when a location update is received.

• Type: Boolean
• Default: false

primaryColor

Primary color for the user interface (navigation bar and various map elements).

• Type: String (CSS <color>)
• Default: "#3f51b5" (primary color from the OwnTracks Android app)
• Example:

  // Set the UI's primary color to 'rebeccapurple'
  window.owntracks.config = {
    primaryColor: "rebeccapurple"
  };
  

selectedDevice

Initial selected device. All devices will be shown by default if null. Will be ignored if selectedUser is null;

Only data for the selected user/device will be fetched, so you can use this to limit the amount of data fetched after page load.

• Type: String or null
• Default: null
• Example:

  // Select the device 'phone' from user 'foo' by default
  window.owntracks.config = {
    selectedUser: "foo",
    selectedDevice: "phone"
  };
  

selectedUser

Initial selected user. All users will be shown by default if null.

Only data for the selected user/device will be fetched, so you can use this to limit the amount of data fetched after page load.

• Type: String or null
• Default: null
• Example:

  // Select all devices from user 'foo' by default
  window.owntracks.config = {
    selectedUser: "foo"
  };
  

startDateTime

Initial start date and time (browser timezone) for fetched data.

• Type: Date
• Default: one month ago, 00:00:00
• Example:

  // Data will be fetched from the first day of the current month
  const startDateTime = new Date();
  startDateTime.setHours(0, 0, 0, 0);
  startDateTime.setDate(1);
  window.owntracks.config = {
    startDateTime
  };
  

verbose

Whether to enable verbose mode or not.

• Type: Boolean
• Default: false