github/docker-recorder
1
0
Fork 0
mirror of https://github.com/owntracks/docker-recorder.git synced 2026-02-13 20:49:51 +00:00
Code Issues Packages Projects Releases Wiki Activity

cleanup README

Browse Source
This commit is contained in:
Steffen Vogel
2022-05-14 10:15:01 +02:00
parent 4ceee6d824
commit a81c66d220
1 changed files with 34 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files

63
README.md
View File

@@ -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