From 14533ba3c9ad64ec2bb04aaef475f4a355f81f82 Mon Sep 17 00:00:00 2001 From: Alex Jordan Date: Tue, 16 Aug 2016 13:25:01 -0400 Subject: [PATCH 1/8] Fix a couple small README typos --- README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index ca4e43d..d221b7e 100644 --- a/README.md +++ b/README.md @@ -665,7 +665,7 @@ After running `otr_hook()`, the _recorder_ attempts to invoke a Lua function for You define a hooklet function only if you're interested in expressly triggering on a particular JSON element. -### Environment +## Environment The following environment variables control _ocat_'s behaviour: @@ -1031,7 +1031,7 @@ You need a current version of the Mosquitto library (and you probably require th apt-get install build-essential linux-headers-$(uname -r) libcurl4-openssl-dev libmosquitto-dev liblua5.2-dev libsodium-dev libconfig-dev ``` -### Centos 7 +### CentOS 7 ``` yum groupinstall 'Development Tools' @@ -1058,7 +1058,7 @@ We create packages for releases for a few distributions. Please note that these Binaries (`ocat`, `ot-recorder`) from these packages run setuid to user `owntracks` so that they work for all users of the system. Note that, say, certificate files you provide must therefore also be readable by the user `owntracks`. -### Installing on Centos 7 +### Installing on CentOS 7 ``` curl -o /etc/yum.repos.d/mosquitto.repo http://download.opensuse.org/repositories/home:/oojah:/mqtt/CentOS_CentOS-7/home:oojah:mqtt.repo @@ -1068,7 +1068,7 @@ curl -o /etc/yum.repos.d/owntracks.repo http://repo.owntracks.org/centos/owntrac yum install ot-recorder ``` -### Installing on Raspian (wheezy) +### Installing on Raspian (Wheezy) ``` wget http://repo.owntracks.org/repo.owntracks.org.gpg.key @@ -1088,7 +1088,7 @@ apt-get update apt-get install ot-recorder ``` -#### sytemd service +#### systemd service The packages we provide have a systemd unit file in `/usr/share/doc/ot-recorder/ot-recorder.service` which you can use to have the Recorder started automatically: From 5edfd605ca0e116ba45595cfedd25e2144e08d5b Mon Sep 17 00:00:00 2001 From: Alex Jordan Date: Tue, 16 Aug 2016 13:25:24 -0400 Subject: [PATCH 2/8] Organize reverse proxy instructions in the README --- README.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index d221b7e..eea28a9 100644 --- a/README.md +++ b/README.md @@ -673,9 +673,11 @@ The following environment variables control _ocat_'s behaviour: * `OCAT_USERNAME` can be set to the preferred username. The `--user` option overrides this environment variable. * `OCAT_DEVICE` can be set to the preferred device name. The `--device` option overrides this environment variable. -### nginx +## Reverse proxy -Running the _recorder_ protected by an _nginx_ or _Apache_ server is possible and is the only recommended method if you want to server data behind _localhost_. This snippet shows how to do it, but you would also add authentication to that. +Running the _recorder_ protected by an _nginx_ or _Apache_ server is possible and is the only recommended method if you want to server data behind _localhost_. The snippets below show how to do it, but you would also add authentication to them. + +### nginx ``` server { @@ -710,8 +712,7 @@ server { ### Apache -Assuming you want to use Apache as a reverse proxy to the recorder, the following -may get you started. This will hand URIs which begin with `/otr/` to the _Recorder_. +This will hand URIs which begin with `/otr/` to the _recorder_. ``` From a13a1f9094035081117b048f84301ee5a77a72e8 Mon Sep 17 00:00:00 2001 From: Alex Jordan Date: Tue, 16 Aug 2016 13:26:14 -0400 Subject: [PATCH 3/8] Add basic Table of Contents to the README --- README.md | 74 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 74 insertions(+) diff --git a/README.md b/README.md index eea28a9..7889b92 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,80 @@ There are two main components: the _recorder_ obtains data via MQTT subscribes o We developed the _recorder_ as a one-stop solution to storing location data published by our OwnTracks apps (iOS and Android) and retrieving this data. Our previous offerings (`m2s`, `o2s`/`Pista`) also work of course, but we believe the _recorder_ is best suited to most environments. +## Table of Contents + +* `recorder` +* Installing +* Building from source +* Getting started +* `ot-recorder` options and variables +* The HTTP Server + * Last position of a particular user + * Display map with points starting at a particular date + * Display a track (a.k.a. linestring) + * Tabular display + * Live map +* `ocat` +* `ocat` examples + * List users and devices + * Show the last position reported by a user + * What were the last 4 positions reported? +* Design decisions +* Storage +* Configuration file +* Reverse Geo + * Precision + * The geo cache +* Monitoring +* HTTP server + * API + * `monitor` + * `last` + * `list` + * `locations` + * `q` + * `photo` + * `kill` + * `version` +* Lua hooks + * `otr_init` + * `otr_exit` + * `otr_hook` + * `otr_putrec` + * `otr_httpobject` + * Hooklets +* Environment +* Reverse proxy + * nginx + * Apache +* Views + * view JSON + * Authentication + * HTTP proxy +* HTTP mode + * Friends in HTTP mode + * Authentication +* Advanced topics + * Browser API keys + * The LMDB database + * `topic2tid` + * `keys` + * `friends` +* Encryption (*experimental!*) +* Prerequisites for building + * Debian + * CentOS 7 + * Ubuntu +* Packages + * Installing on CentOS 7 + * Installing on Raspian (Wheezy) + * Installing on Debian 8 (Jessie) + * systemd service +* Docker +* Tips and Tricks + * Gatewaying HTTP to MQTT + * Override reverse-geo precision + ## `recorder` The _recorder_ serves two purposes: From 0acc0b6a035c15337f107e23d42721ff6da2bd33 Mon Sep 17 00:00:00 2001 From: Alex Jordan Date: Tue, 16 Aug 2016 13:31:52 -0400 Subject: [PATCH 4/8] Fix "systemd service" heading level --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 7889b92..a2b78cd 100644 --- a/README.md +++ b/README.md @@ -78,7 +78,7 @@ We developed the _recorder_ as a one-stop solution to storing location data publ * Installing on CentOS 7 * Installing on Raspian (Wheezy) * Installing on Debian 8 (Jessie) - * systemd service + * systemd service * Docker * Tips and Tricks * Gatewaying HTTP to MQTT @@ -1163,7 +1163,7 @@ apt-get update apt-get install ot-recorder ``` -#### systemd service +### systemd service The packages we provide have a systemd unit file in `/usr/share/doc/ot-recorder/ot-recorder.service` which you can use to have the Recorder started automatically: From a4477ca11fc34717f12c758936c8c168796a2a77 Mon Sep 17 00:00:00 2001 From: Alex Jordan Date: Tue, 16 Aug 2016 13:36:13 -0400 Subject: [PATCH 5/8] Fix list indentation --- README.md | 92 +++++++++++++++++++++++++++---------------------------- 1 file changed, 46 insertions(+), 46 deletions(-) diff --git a/README.md b/README.md index a2b78cd..ebfabfe 100644 --- a/README.md +++ b/README.md @@ -18,71 +18,71 @@ We developed the _recorder_ as a one-stop solution to storing location data publ * Getting started * `ot-recorder` options and variables * The HTTP Server - * Last position of a particular user - * Display map with points starting at a particular date - * Display a track (a.k.a. linestring) - * Tabular display - * Live map + * Last position of a particular user + * Display map with points starting at a particular date + * Display a track (a.k.a. linestring) + * Tabular display + * Live map * `ocat` * `ocat` examples - * List users and devices - * Show the last position reported by a user - * What were the last 4 positions reported? + * List users and devices + * Show the last position reported by a user + * What were the last 4 positions reported? * Design decisions * Storage * Configuration file * Reverse Geo - * Precision - * The geo cache + * Precision + * The geo cache * Monitoring * HTTP server - * API - * `monitor` - * `last` - * `list` - * `locations` - * `q` - * `photo` - * `kill` - * `version` + * API + * `monitor` + * `last` + * `list` + * `locations` + * `q` + * `photo` + * `kill` + * `version` * Lua hooks - * `otr_init` - * `otr_exit` - * `otr_hook` - * `otr_putrec` - * `otr_httpobject` - * Hooklets + * `otr_init` + * `otr_exit` + * `otr_hook` + * `otr_putrec` + * `otr_httpobject` + * Hooklets * Environment * Reverse proxy - * nginx - * Apache + * nginx + * Apache * Views - * view JSON - * Authentication - * HTTP proxy + * view JSON + * Authentication + * HTTP proxy * HTTP mode - * Friends in HTTP mode - * Authentication + * Friends in HTTP mode + * Authentication * Advanced topics - * Browser API keys - * The LMDB database - * `topic2tid` - * `keys` - * `friends` + * Browser API keys + * The LMDB database + * `topic2tid` + * `keys` + * `friends` * Encryption (*experimental!*) * Prerequisites for building - * Debian - * CentOS 7 - * Ubuntu + * Debian + * CentOS 7 + * Ubuntu * Packages - * Installing on CentOS 7 - * Installing on Raspian (Wheezy) - * Installing on Debian 8 (Jessie) - * systemd service + * Installing on CentOS 7 + * Installing on Raspian (Wheezy) + * Installing on Debian 8 (Jessie) + * systemd service * Docker * Tips and Tricks - * Gatewaying HTTP to MQTT - * Override reverse-geo precision + * Gatewaying HTTP to MQTT + * Override reverse-geo precision ## `recorder` From a1907d2a55afca2bc1594bdcb0052435b11e68c4 Mon Sep 17 00:00:00 2001 From: Alex Jordan Date: Tue, 16 Aug 2016 13:58:54 -0400 Subject: [PATCH 6/8] Add links to the Table of Contents --- README.md | 142 +++++++++++++++++++++++++++--------------------------- 1 file changed, 71 insertions(+), 71 deletions(-) diff --git a/README.md b/README.md index ebfabfe..a0fa3db 100644 --- a/README.md +++ b/README.md @@ -12,77 +12,77 @@ We developed the _recorder_ as a one-stop solution to storing location data publ ## Table of Contents -* `recorder` -* Installing -* Building from source -* Getting started -* `ot-recorder` options and variables -* The HTTP Server - * Last position of a particular user - * Display map with points starting at a particular date - * Display a track (a.k.a. linestring) - * Tabular display - * Live map -* `ocat` -* `ocat` examples - * List users and devices - * Show the last position reported by a user - * What were the last 4 positions reported? -* Design decisions -* Storage -* Configuration file -* Reverse Geo - * Precision - * The geo cache -* Monitoring -* HTTP server - * API - * `monitor` - * `last` - * `list` - * `locations` - * `q` - * `photo` - * `kill` - * `version` -* Lua hooks - * `otr_init` - * `otr_exit` - * `otr_hook` - * `otr_putrec` - * `otr_httpobject` - * Hooklets -* Environment -* Reverse proxy - * nginx - * Apache -* Views - * view JSON - * Authentication - * HTTP proxy -* HTTP mode - * Friends in HTTP mode - * Authentication -* Advanced topics - * Browser API keys - * The LMDB database - * `topic2tid` - * `keys` - * `friends` -* Encryption (*experimental!*) -* Prerequisites for building - * Debian - * CentOS 7 - * Ubuntu -* Packages - * Installing on CentOS 7 - * Installing on Raspian (Wheezy) - * Installing on Debian 8 (Jessie) - * systemd service -* Docker -* Tips and Tricks - * Gatewaying HTTP to MQTT - * Override reverse-geo precision +* [`recorder`](#recorder) +* [Installing](#installing) +* [Building from source](#building-from-source) +* [Getting started](#building-from-source) +* [`ot-recorder` options and variables](#ot-recorder-options-and-variables) +* [The HTTP Server](#the-http-server) + * [Last position of a particular user](#last-position-of-a-particular-user) + * [Display map with points starting at a particular date](#last-position-of-a-particular-user) + * [Display a track (a.k.a. linestring)](#display-a-track-aka-linestring) + * [Tabular display](#tabular-display) + * [Live map](#live-map) +* [`ocat`](#live-map) +* [`ocat` examples](#ocat-examples) + * [List users and devices](#list-users-and-devices) + * [Show the last position reported by a user](#show-the-last-position-reported-by-a-user) + * [What were the last 4 positions reported?](#what-were-the-last-4-positions-reported) +* [Design decisions](#design-decisions) +* [Storage](#storage) +* [Configuration file](#configuration-file) +* [Reverse Geo](#reverse-geo) + * [Precision](#reverse-geo) + * [The geo cache](#the-geo-cache) +* [Monitoring](#monitoring) +* [HTTP server](#monitoring) + * [API](#monitoring) + * [`monitor`](#monitor) + * [`last`](#last) + * [`list`](#list) + * [`locations`](#locations) + * [`q`](#q) + * [`photo`](#photo) + * [`kill`](#kill) + * [`version`](#version) +* [Lua hooks](#lua-hooks) + * [`otr_init`](#otr_init) + * [`otr_exit`](#otr_exit) + * [`otr_hook`](#otr_hook) + * [`otr_putrec`](#otr_putrec) + * [`otr_httpobject`](#otr_httpobject) + * [Hooklets](#hooklets) +* [Environment](#environment) +* [Reverse proxy](#environment) + * [nginx](#environment) + * [Apache](#apache) +* [Views](#views) + * [view JSON](#view-json) + * [Authentication](#authentication) + * [HTTP proxy](#http-proxy) +* [HTTP mode](#http-mode) + * [Friends in HTTP mode](#friends-in-http-mode) + * [Authentication](#authentication-1) +* [Advanced topics](#advanced-topics) + * [Browser API keys](#browser-api-keys) + * [The LMDB database](#the-lmdb-database) + * [`topic2tid`](#topic2tid) + * [`keys`](#keys) + * [`friends`](#friends) +* [Encryption (*experimental!*)](#encryption-experimental) +* [Prerequisites for building](#prerequisites-for-building) + * [Debian](#debian) + * [CentOS 7](#centos-7) + * [Ubuntu](#ubuntu) +* [Packages](#packages) + * [Installing on CentOS 7](#installing-on-centos-7) + * [Installing on Raspian (Wheezy)](#installing-on-raspian-wheezy) + * [Installing on Debian 8 (Jessie)](#installing-on-debian-8-jessie) + * [systemd service](#systemd-service) +* [Docker](#docker) +* [Tips and Tricks](#tips-and-tricks) + * [Gatewaying HTTP to MQTT](#gatewaying-http-to-mqtt) + * [Override reverse-geo precision](#override-reverse-geo-precision) ## `recorder` From a89cb64dfa7a10d9fc44f7e37f253dc92d6307be Mon Sep 17 00:00:00 2001 From: Alex Jordan Date: Tue, 16 Aug 2016 14:03:09 -0400 Subject: [PATCH 7/8] Fix incorrect links --- README.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index a0fa3db..626523e 100644 --- a/README.md +++ b/README.md @@ -15,15 +15,15 @@ We developed the _recorder_ as a one-stop solution to storing location data publ * [`recorder`](#recorder) * [Installing](#installing) * [Building from source](#building-from-source) -* [Getting started](#building-from-source) +* [Getting started](#getting-started) * [`ot-recorder` options and variables](#ot-recorder-options-and-variables) * [The HTTP Server](#the-http-server) * [Last position of a particular user](#last-position-of-a-particular-user) - * [Display map with points starting at a particular date](#last-position-of-a-particular-user) + * [Display map with points starting at a particular date](#display-map-with-points-starting-at-a-particular-date) * [Display a track (a.k.a. linestring)](#display-a-track-aka-linestring) * [Tabular display](#tabular-display) * [Live map](#live-map) -* [`ocat`](#live-map) +* [`ocat`](#ocat) * [`ocat` examples](#ocat-examples) * [List users and devices](#list-users-and-devices) * [Show the last position reported by a user](#show-the-last-position-reported-by-a-user) @@ -32,11 +32,11 @@ We developed the _recorder_ as a one-stop solution to storing location data publ * [Storage](#storage) * [Configuration file](#configuration-file) * [Reverse Geo](#reverse-geo) - * [Precision](#reverse-geo) + * [Precision](#precisioin) * [The geo cache](#the-geo-cache) * [Monitoring](#monitoring) -* [HTTP server](#monitoring) - * [API](#monitoring) +* [HTTP server](#http-server) + * [API](#api) * [`monitor`](#monitor) * [`last`](#last) * [`list`](#list) @@ -53,8 +53,8 @@ We developed the _recorder_ as a one-stop solution to storing location data publ * [`otr_httpobject`](#otr_httpobject) * [Hooklets](#hooklets) * [Environment](#environment) -* [Reverse proxy](#environment) - * [nginx](#environment) +* [Reverse proxy](#reverse-proxy) + * [nginx](#nginx) * [Apache](#apache) * [Views](#views) * [view JSON](#view-json) From 816b55f88bea46a72b10cfa65029de6f8e0ee62e Mon Sep 17 00:00:00 2001 From: Alex Jordan Date: Tue, 16 Aug 2016 14:13:52 -0400 Subject: [PATCH 8/8] s/Websocket/WebSocket/g --- README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 626523e..45f4857 100644 --- a/README.md +++ b/README.md @@ -89,7 +89,7 @@ We developed the _recorder_ as a one-stop solution to storing location data publ The _recorder_ serves two purposes: 1. It subscribes to an MQTT broker and reads messages published from the OwnTracks apps, storing these in a particular fashion into what we call the _store_ which is basically a bunch of plain files on the file system. Alternatively the Recorder can listen on HTTP for OwnTracks-type JSON messages POSTed to its HTTP server. -2. It provides a Web server which serves static pages, a REST API you use to request data from the _store_, and a Websocket server. The distribution comes with a few examples of how to access the data through its HTTP interface (REST API). In particular a _table_ of last locations has been made available as well as a _live map_ which updates via the _recorder_'s Websocket interface when location publishes are received. In addition we provide maps with last points or tracks using the GeoJSON produced by the _recorder_. +2. It provides a Web server which serves static pages, a REST API you use to request data from the _store_, and a WebSocket server. The distribution comes with a few examples of how to access the data through its HTTP interface (REST API). In particular a _table_ of last locations has been made available as well as a _live map_ which updates via the _recorder_'s WebSocket interface when location publishes are received. In addition we provide maps with last points or tracks using the GeoJSON produced by the _recorder_. ## Installing @@ -267,7 +267,7 @@ The _recorder_'s Web server also provides a tabular display which shows the last #### Live map -The _recorder_'s built-in Websocket server updates a map as it receives publishes from the OwnTracks devices. Here's an example: +The _recorder_'s built-in WebSocket server updates a map as it receives publishes from the OwnTracks devices. Here's an example: ![Live map](assets/demo-live-map.png) @@ -547,7 +547,7 @@ OK ot-recorder pingping at http://127.0.0.1:8085: 0 seconds difference ## HTTP server -The _recorder_ has a built-in HTTP server with which it servers static files from either the compiled-in default `DOCROOT` directory or that specified at run-time with the `--doc-root` option. Furthermore, it serves JSON data from the API end-point at `/api/0/` and it has a built-in Websocket server for the live map. +The _recorder_ has a built-in HTTP server with which it servers static files from either the compiled-in default `DOCROOT` directory or that specified at run-time with the `--doc-root` option. Furthermore, it serves JSON data from the API end-point at `/api/0/` and it has a built-in WebSocket server for the live map. The API basically serves the same data as _ocat_ is able to produce. @@ -763,7 +763,7 @@ server { index index.html index.htm; } - # Proxy and upgrade Websocket connection + # Proxy and upgrade WebSocket connection location /otr/ws { rewrite ^/otr/(.*) /$1 break; proxy_pass http://127.0.0.1:8083; @@ -790,7 +790,7 @@ This will hand URIs which begin with `/otr/` to the _recorder_. ``` -# Websocket URL endpoint +# WebSocket URL endpoint # a2enmod proxy_wstunnel ProxyPass /otr/ws ws://127.0.0.1:8083/ws keepalive=on retry=60 ProxyPassReverse /otr/ws ws://127.0.0.1:8083/ws keepalive=on @@ -978,7 +978,7 @@ curl --data "${payload}" 'http://127.0.0.1:8085/pub?u=jane&d=3s' curl -H 'X-Limit-U: jane' -H 'X-Limit-D: 3s' --data "${payload}" 'http://127.0.0.1:8085/pub' ``` -The content of the request is used by the Recorder as though it had arrived as an MQTT message; Lua hooks and Websocket pushes are handled accordingly. +The content of the request is used by the Recorder as though it had arrived as an MQTT message; Lua hooks and WebSocket pushes are handled accordingly. If the Recorder is compiled without specifying `WITH_MQTT` at build time, support for MQTT is disabled completely.