Clean up and document configuration options

This commit is contained in:
Linus Groh
2019-09-29 08:00:16 +01:00
parent 69619665f4
commit be63a12607
4 changed files with 488 additions and 80 deletions

View File

@@ -51,6 +51,9 @@ services:
## 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.default.js`](public/config/config.default.js) to
`public/config/config.js` and make changes as you wish.

438
docs/config.md Normal file
View File

@@ -0,0 +1,438 @@
# 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:
```js
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`](#api.baseUrl)
- [`endDate`](#endDate)
- [`ignorePingLocation`](#ignorePingLocation)
- `map`
- [`attribution`](#map.attribution)
- `center`
- [`lat`](#map.center.lat)
- [`lng`](#map.center.lng)
- [`circle`](#map.circle)
- [`circleMarker`](#map.circleMarker)
- `controls`
- `scale`
- [`display`](#map.controls.scale.display)
- [`imperial`](#map.controls.scale.imperial)
- [`maxWidth`](#map.controls.scale.maxWidth)
- [`metric`](#map.controls.scale.metric)
- [`position`](#map.controls.scale.position)
- `zoom`
- [`display`](#map.controls.zoom.display)
- [`position`](#map.controls.zoom.position)
- `heatmap`
- [`blur`](#map.heatmap.blur)
- [`gradient`](#map.heatmap.gradient)
- [`max`](#map.heatmap.max)
- [`radius`](#map.heatmap.radius)
- `layers`
- [`heatmap`](#map.layers.heatmap)
- [`last`](#map.layers.last)
- [`line`](#map.layers.line)
- [`points`](#map.layers.points)
- [`maxNativeZoom`](#map.maxNativeZoom)
- [`maxPointDistance`](#map.maxPointDistance)
- [`maxZoom`](#map.maxZoom)
- [`polyline`](#map.polyline)
- [`url`](#map.url)
- [`zoom`](#map.zoom)
- [`primaryColor`](#primaryColor)
- [`selectedDevice`](#selectedDevice)
- [`selectedUser`](#selectedUser)
- [`startDate`](#startDate)
### `api.baseUrl`
Base URL for the recorder's HTTP and WebSocket API. Keep CORS in mind.
- Type: [`String`]
- Default: current protocol and host
- Examples:
```js
// API requests will be made to https://owntracks.example.com/api/0/...
window.owntracks.config = {
api: {
baseUrl: "https://owntracks.example.com"
}
};
```
```js
// API requests will be made to https://example.com/owntracks/api/0/...
window.owntracks.config = {
api: {
baseUrl: "https://example.com/owntracks/"
}
};
```
### `endDate`
Initial end date for fetched data.
- Type: [`Date`]
- Default: today
- Example:
```js
// Data will be fetched up to 1970-01-01
window.owntracks.config = {
endDate: 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](https://github.com/owntracks/recorder/issues/195#issuecomment-304004436).
- Type: [`Boolean`]
- Default: `true`
- Example:
```js
// Don't ignore ping/ping location. Not sure why you'd do this :)
window.owntracks.config = {
ignorePingLocation: false
};
```
### `map.attribution`
Attribution for map tiles.
- Type: [`String`] (may contain HTML)
- Default: `"&copy; <a href="https://osm.org/copyright">OpenStreetMap</a> contributors"`
- Example:
```js
// Make sure to add proper attribution!
window.owntracks.config = {
map: {
attribution: "Map tiles &copy; 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](https://korigan.github.io/Vue2Leaflet/#/components/l-circle/)
for all possible values.
- Type: [`Object`]
- Default:
```js
{
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](https://korigan.github.io/Vue2Leaflet/#/components/l-circle-marker/)
for all possible values.
- Type: [`Object`]
- Default:
```js
{
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](https://leafletjs.com/reference-1.5.0.html#control-position)
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](https://leafletjs.com/reference-1.5.0.html#control-position)
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](https://github.com/mourner/simpleheat/blob/c1998c36fa2f9a31350371fd42ee30eafcc78f9c/simpleheat.js#L22-L28)
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:
```js
// 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`](#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](https://korigan.github.io/Vue2Leaflet/#/components/l-polyline/)
for all possible values.
- Type: [`Object`]
- Default:
```js
{
color: null,
fillColor: "transparent"
}
```
### `map.url`
Tile server URL. For more information see [Leaflet tile layer documentation](https://leafletjs.com/reference-1.5.0.html#tilelayer-url-template)
and [this Wikipedia article](https://en.wikipedia.org/wiki/Tiled_web_map).
- Type: [`String`]
- Default: `"https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png"`
- Example:
```js
// 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`
### `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:
```js
// 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`](#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:
```js
// 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:
```js
// Select all devices from user 'foo' by default
window.owntracks.config = {
selectedUser: "foo"
};
```
### `startDate`
Initial start date for fetched data.
- Type: [`Date`]
- Default: one month ago
- Example:
```js
// Data will be fetched from the first day of the current month
const startDate = new Date();
startDate.setUTCHours(0, 0, 0, 0);
startDate.setUTCDate(1);
window.owntracks.config = {
startDate
};
```
[`Boolean`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean
[`Date`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date
[`Number`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number
[`Object`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object
[`String`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String
[CSS `<color>`]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value

View File

@@ -1,61 +1,23 @@
import deepmerge from "deepmerge";
const endDate = new Date();
endDate.setUTCHours(0);
endDate.setUTCMinutes(0);
endDate.setUTCSeconds(0);
endDate.setUTCHours(0, 0, 0, 0);
const startDate = new Date(endDate);
startDate.setUTCMonth(startDate.getMonth() - 1);
const DEFAULT_CONFIG = {
api: {
// API base URL, defaults to the current protocol and host. Keep CORS in mind.
baseUrl: `${window.location.protocol}//${window.location.host}`,
},
// Primary color for the user interface
primaryColor: "#3f51b5",
// Initial start and end date. Doesn't have to be hardcoded, see
// above. Defaults to one month ago - today.
startDate,
endDate,
// User and device selected by default. Set to null to show all by default.
selectedUser: null,
selectedDevice: null,
ignorePingLocation: true,
map: {
// Initial map center position
center: { lat: 0, lng: 0 },
// Initial map zoom
zoom: 19,
// This is being used to fetch tiles in different resolutions -
// set to the highest value the configured tileserver supports.
maxNativeZoom: 19,
// 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 `maxNativeZoom` to disable.
maxZoom: 21,
// Tile server URL. See Leaflet documentation for more info.
url: "https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png",
attribution:
'&copy; <a href="https://osm.org/copyright">OpenStreetMap</a> contributors',
// Leaflet map controls. Options should be self-explanatory.
controls: {
zoom: {
display: true,
position: "topleft",
},
scale: {
display: true,
position: "bottomleft",
maxWidth: 200,
metric: true,
imperial: true,
},
},
// `color` and `fillColor` default to `primaryColor` when null.
polyline: {
color: null,
fillColor: "transparent",
center: {
lat: 0,
lng: 0,
},
circle: {
color: null,
@@ -68,36 +30,45 @@ const DEFAULT_CONFIG = {
fillOpacity: 1,
radius: 4,
},
// Configuration for the heatmap (simpleheat). See
// https://github.com/mourner/simpleheat for more info.
controls: {
scale: {
display: true,
imperial: true,
maxWidth: 200,
metric: true,
position: "bottomleft",
},
zoom: {
display: true,
position: "topleft",
},
},
heatmap: {
blur: 15,
gradient: null,
max: 20,
radius: 25,
blur: 15,
// Uses simpleheat's default gradient when null. See
// https://github.com/mourner/simpleheat/blob/c1998c36fa2f9a31350371fd42ee30eafcc78f9c/simpleheat.js#L22-L28
gradient: null,
},
// Which layers to show by default. The source of truth at runtime
// is the Vuex store, which is initialized from these values and
// the query parameters, in that order.
layers: {
heatmap: false,
last: true,
line: true,
points: false,
heatmap: false,
},
// 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 large distance between two points (which
// usually indicates that they're not related). Set to Infinity to
// disable splitting into separate lines.
maxPointDistance: 1000,
maxNativeZoom: 19,
maxPointDistance: null,
maxZoom: 21,
polyline: {
color: null,
fillColor: "transparent",
},
url: "https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png",
zoom: 19,
},
// Remove the ping/ping location which is enabled in the recorder's
// Docker image for health checks by default:
// https://github.com/owntracks/recorder/issues/195#issuecomment-304004436
ignorePingLocation: true,
primaryColor: "#3f51b5",
selectedDevice: null,
selectedUser: null,
startDate,
};
// Use deepmerge to combine the default and user-defined configuration.

View File

@@ -28,7 +28,7 @@
<LCircle
v-for="l in lastLocations"
:key="`${l.topic}-circle`"
:lat-lng="{ lat: l.lat, lng: l.lon }"
:lat-lng="[l.lat, l.lon]"
:radius="l.acc"
:color="circle.color"
:fill-color="circle.fillColor"
@@ -60,8 +60,7 @@
v-for="(group, i) in locationHistoryLatLngGroups"
:key="i"
:lat-lngs="group"
:color="polyline.color"
:fill-color="polyline.fillColor"
v-bind="polyline"
/>
</template>
@@ -72,10 +71,7 @@
v-for="(l, n) in deviceLocations"
:key="`${user}-${device}-${n}`"
:lat-lng="[l.lat, l.lon]"
:radius="circleMarker.radius"
:color="circleMarker.color"
:fill-color="circleMarker.fillColor"
:fill-opacity="circleMarker.fillOpacity"
v-bind="circleMarker"
>
<LDeviceLocationPopup
:user="user"
@@ -152,17 +148,14 @@ export default {
},
data() {
return {
center: this.$store.state.map.center,
zoom: this.$store.state.map.zoom,
maxNativeZoom: config.map.maxNativeZoom,
maxZoom: config.map.maxZoom,
url: config.map.url,
attribution: config.map.attribution,
center: this.$store.state.map.center,
controls: config.map.controls,
polyline: {
...config.map.polyline,
color: config.map.polyline.color || config.primaryColor,
},
heatmap: config.map.heatmap,
maxZoom: config.map.maxZoom,
maxNativeZoom: config.map.maxNativeZoom,
url: config.map.url,
zoom: this.$store.state.map.zoom,
circle: {
...config.map.circle,
color: config.map.circle.color || config.primaryColor,
@@ -172,7 +165,10 @@ export default {
...config.map.circleMarker,
color: config.map.circleMarker.color || config.primaryColor,
},
heatmap: config.map.heatmap,
polyline: {
...config.map.polyline,
color: config.map.polyline.color || config.primaryColor,
},
};
},
mounted() {