diff --git a/README.md b/README.md index 87b549e..70d6d72 100644 --- a/README.md +++ b/README.md @@ -6,12 +6,13 @@ Dockerfile for the [Recorder](https://github.com/owntracks/recorder) of the OwnTracks project. The image is [owntracks/recorder](https://hub.docker.com/r/owntracks/recorder). ## Quickstart + ```bash -$ docker volume create recorder_store -$ docker run -d -p 8083:8083 -v recorder_store:/store -e OTR_HOST=mqtt_broker owntracks/recorder +docker volume create recorder_store +docker run -d -p 8083:8083 -v recorder_store:/store -e OTR_HOST=mqtt_broker owntracks/recorder ``` -Recorder is now accessible at `http://localhost:8083`. +Recorder is now accessible at `http://localhost:8083`. `-p 8083:8083` makes the container reachable at port 8083. `-d` detaches the container into the background. The volume `recorder_store` is mounted at @@ -21,6 +22,7 @@ environment variables. Multiple `-e` parameters can be used for multiple environment variables. ## Configuration + The Recorder can be configured using two methods, environment variables and via the a `recorder.conf` file in the `/config` volume of the container. @@ -29,31 +31,33 @@ via the a `recorder.conf` file in the `/config` volume of the container. Can be passed to the container with the `-e` parameter. Example: ```bash -$ docker run -d -p 8083:8083 \ +docker run -d -p 8083:8083 \ -e OTR_HOST=mqtt_broker \ - -e OTR_PORT=1883 \ - -e OTR_USER=user \ - -e OTR_PASS=pass \ - owntracks/recorder + -e OTR_PORT=1883 \ + -e OTR_USER=user \ + -e OTR_PASS=pass \ + owntracks/recorder ``` The complete list of parameters can be found in the [recorder documentation](https://github.com/owntracks/recorder/blob/master/README.md#configuration-file). ### Configuration file + One can also use a configuration file. The container reads a `recorder.conf` file from the `/config` folder. To use this, create a folder e.g. `./config` and mount it into you docker container at `/config`. ```bash -$ mkdir config -$ docker run -d -p 8083:8083 -v recorder_store:/store -v ./config:/config owntracks/recorder +mkdir config +docker run -d -p 8083:8083 -v recorder_store:/store -v ./config:/config owntracks/recorder ``` Up on starting the recorder, a default `recorder.conf` file will be created if none exists. Possible options are documented [here](https://github.com/owntracks/recorder/blob/master/README.md#configuration-file). **Notes:** + - The value of `OTR_HOST` is as seen from the container. Thus `localhost` refers to the container not the host and should likely not be used. - Environment variables, overwrite the `recorder.conf` file options. @@ -66,14 +70,15 @@ The `/store` volume of the container is used for persistent storage of location data. The volume needs to be created explicitly. ```bash -$ docker volume create recorder_storage -$ docker run -d -p 8083:8083 -v recorder_store:/store owntracks/recorder +docker volume create recorder_storage +docker run -d -p 8083:8083 -v recorder_store:/store owntracks/recorder ``` + It is also possible to use a local folder instead of an static docker volume. ```bash -$ mkdir store -$ docker run -d -p 8083:8083 -v ./store:/store owntracks/recorder +mkdir store +docker run -d -p 8083:8083 -v ./store:/store owntracks/recorder ``` If nothing is mounted at `/store`, docker will create a unique volume @@ -81,13 +86,14 @@ automatically. However up on recreation of the docker container, this process will be repeated and another unique volume will be created. As a result, the container will have forgotten about previous tracks. -## TLS between MQTT broker and Recorder +## TLS between MQTT Broker and Recorder + The `OTR_CAPATH` of the container defaults to the `/config` volume. Thus certificates and key files belong into the `/config` volume. `OTR_CAFILE` must be configured for TLS. `OTR_CERTFILE` defaults to `cert.pem` and `OTR_KEYFILE` to `key.pem`. These files are optional and the options are ignored if the files don't exist. -## TLS encryption via reverse proxy +## TLS encryption via Reverse Proxy The Recorder has no encryption module by it self. Instead use a reverse proxy setup. See https://github.com/jwilder/nginx-proxy for how to do this in a semi @@ -97,17 +103,17 @@ details. ## Healthcheck -The Recorder container performs a Docker-style HEALTHCHECK on itself by periodically +The Recorder container performs a Docker-style `HEALTHCHECK` on itself by periodically running `recorder-health.sh` on itself. This program POSTS a `_type: location` JSON message to itself over HTTP to the ping-ping endpoint and verifies via the HTTP API whether the message was received. - ## Docker compose files -Save a file with the name [docker-compose.yml](docker-compose.yml) and following content. Run with -`docker-compose up` from the same folder. -``` yaml +Save a file with the name [docker-compose.yml](docker-compose.yml) and following content. +Run with `docker-compose up` from the same folder. + +```yaml version: '3' services: @@ -124,7 +130,6 @@ services: volumes: store: config: - ``` This [docker-compose.yml](docker-compose.yml) file creates `store` and `config` volumes. It is @@ -137,7 +142,7 @@ variables see An example might look like: -``` yaml +```yaml version: '3' services: @@ -156,7 +161,6 @@ services: volumes: store: - ``` ### With MQTT broker @@ -164,7 +168,7 @@ volumes: If you need to set up an MQTT broker, you can easily use, say, Mosquitto. There are ready to use containers available on docker hub. To use `eclipse-mosquitto` add something like [the following](docker-compose-mqtt.yml) to your `docker-compose.yml` file. -``` yaml +```yaml version: '3' services: @@ -196,6 +200,7 @@ volumes: mosquitto-logs: mosquitto-conf: ``` + See [here](https://hub.docker.com/_/eclipse-mosquitto) for info on the eclipse-mosquitto image and how to configure it. ### All in one solution with reverse proxy and Let's Encrypt @@ -222,7 +227,7 @@ There are some caveats people seem to step into: the virtual host, e.g. `owntrack.domain.com` in the **folder** `/etc/nginx/htpasswd` -``` yaml +```yaml version: '2' @@ -313,9 +318,10 @@ networks: external: name: nginx-proxy ``` + a minimal mosquitto.conf which can act as a start: -``` +``` allow_anonymous false password_file /etc/mosquitto/passwd #use mosquitto_passwd inside container to populate the passwd file @@ -338,8 +344,7 @@ cafile /etc/letsencrypt/live/mqtt.domain.com/chain.pem keyfile /etc/letsencrypt/live/mqtt.domain.com/key.pem ``` - -# Possible enhancements +## Possible enhancements - Maybe put the most common Mosquitto options in the section which uses an MQTT broker in the docker-compose file