Improve Docker installation instructions and usage

While being at it, also adjust some other former path references, i.e.
"completely get rid of `/opt`".

Author: amotl

DOCKER.md

@@ -0,0 +1,145 @@
+# Running mqttwarn with Docker
+
+If you would rather use `mqttwarn` without installing Python and the
+required libraries, you can run it as a [Docker container](https://www.docker.com/).
+You need to install only the Docker executable.
+
+You can run the image as a service, i.e. in the background, or you can 
+run it interactively, perhaps to help diagnose a problem.
+
+## Interactively
+
+In order to verify `mqttwarn` works appropriately with the current
+configuration, you might want to invoke it interactively.
+
+The following commands assume you start from scratch and will guide you through
+the necessary steps needed to create a configuration and run it.
+
+Within an empty folder, create a baseline `mqttwarn.ini` file:
+```shell
+docker run -it --rm --volume=$PWD:/etc/mqttwarn jpmens/mqttwarn mqttwarn make-config > mqttwarn.ini
+touch samplefuncs.py
+```
+
+Then, assuming your MQTT broker runs on `localhost`, amend the `mqttwarn.ini` like:
+```ini
+hostname     = 'host.docker.internal'
+```
+
+Now, invoke `mqttwarn`:
+```shell
+docker run -it --rm --volume=$PWD:/etc/mqttwarn jpmens/mqttwarn
+```
+
+`Ctrl-C` will stop it. You can start and stop it as often as you like, here,
+probably editing the `.ini` file as you go.
+
+Note that you can run a local copy of the image, if you've built one (see below),
+by replacing `jpmens/mqttwarn` with `mqttwarn-local` in the following examples.
+
+
+## As a service
+
+This is the typical way of running `mqttwarn`.
+
+From the folder containing your `mqttwarn.ini` file, run `mqttwarn` in the
+background:
+```shell
+docker run --name=mqttwarn --detach --rm --volume=$PWD:/etc/mqttwarn jpmens/mqttwarn
+```
+
+Follow the log:
+```shell
+docker logs mqttwarn --follow
+```
+
+To stop the container:
+```shell
+docker stop mqttwarn
+```
+
+
+## Options
+
+### Configuration Location
+
+Run the Docker image from anywhere by specifying a full path to the
+configuration file:
+```shell
+--volume=/full/path/to/folder:/etc/mqttwarn
+```
+
+### Log file
+
+By default, the log output will be sent to STDERR.
+
+If you would like to log to a file on the host instead, add this to your
+`mqttwarn.ini` file:
+```ini
+logfile = '/log/mqttwarn.log'
+```
+Add this argument to `docker run`:
+```shell
+--volume=$PWD/log:/log
+```
+
+`mqttwarn.log` will be created in your current folder, and appended to each
+time the container is executed. You can delete the file between subsequent
+invocations.
+
+
+### If your MQTT Broker is also running in Docker on the same host
+
+If you give the MQTT broker container a name, then you can refer to it by name rather than by
+IP address. For instance, if it's named `mosquitto`, and started like
+```shell
+docker run --name=mosquitto -it --rm eclipse-mosquitto:1.6
+docker run --name=mosquitto -it --rm eclipse-mosquitto:2.0 mosquitto -c /mosquitto-no-auth.conf
+```
+put this in your `mqttwarn.ini` file:
+```ini
+hostname  = 'mosquitto'
+```
+Then add this argument to `docker run`:
+```shell
+--link=mosquitto
+```
+
+### Custom services
+You have the option to inject services to the official container.
+If you have a `myservice.py` file, you can add it to the services directory with a new volume mount:
+```
+-v $PWD/myservice.py:/usr/local/lib/python3.8/site-packages/mqttwarn/services/myservice.py
+```
+After doing this, you can use your service like:
+```ini
+[config:myservice]
+```
+For service development you probably also want to change the loglevel to `DEBUG`. 
+
+
+### A full example
+
+```shell
+docker run -it --rm --volume=$PWD:/etc/mqttwarn --link=mosquitto jpmens/mqttwarn
+```
+
+
+## Build the image
+
+If you are making any changes to the `mqttwarn` application or to the
+`Dockerfile`, you can build a local image from the files on your drive (not
+from the files on Github).
+
+Execute the following from the root of the project :
+```
+docker build -t mqttwarn-local .
+```
+
+You can then edit any files and rebuild the image as many times as you need. 
+You don't need to commit any changes.
+
+The name `mqttwarn-local` is not meaningful, other than making it obvious when
+you run it that you are using your own personal image. You can use any name you
+like, but avoid `mqttwarn` otherwise it's easily confused with the official
+images.

HANDBOOK.md

@@ -3404,158 +3404,9 @@ instead of waiting for the interval to elapse, you might want to configure:
 pinger = 10.5; now=true
 ```
 
+## Docker
 
-## Running with Docker
-
-If you would rather use `mqttwarn` without installing Python
-and the required libraries, you can run it as a [Docker container](https://www.docker.com/).
-You need to install only the Docker executable.
-
-### Run the Image
-
-You can run the image as a service, i.e. in the background, or you can 
-run it interactively, perhaps to help diagnose a problem.
-
-Note that you can run a local copy of the image, if you've built one (see below),
-by replacing `jpmens/mqttwarn` with `mqttwarn-local` in the following examples.
-
-#### As a Service
-
-This is the typical way of running `mqttwarn`.
-
-From the folder containing your `mqttwarn.ini` file:
-
-```
-$ docker run -d --rm --name mqttwarn \
-    -v $PWD:/opt/mqttwarn/conf \
-    jpmens/mqttwarn
-```
-
-To stop the container:
-```
-$ docker stop mqttwarn
-```
-
-#### Interactively
-
-If you want to experiment with your configuration, or to diagnose
-a problem, it can be simpler to restart the Python script,
-rather than to restart the Docker container.
-
-From the folder containing your `mqttwarn.ini` file:
-
-```
-$ docker run -it --rm \
-    -v $PWD:/opt/mqttwarn/conf \
-    --entrypoint bash \
-    jpmens/mqttwarn
-```
- 
-To start the application from within the container, just invoke
-```
-mqttwarn
-```
-
-`Ctrl-C` will stop it. You can start and stop it as often as you like, here, probably editing the `.ini` file as you go.
-
-`Ctrl-D` or `exit` will stop the container. 
-
-
-
-#### Options
-
-##### Configuration Location
-
-You can of course run the Docker image from anywhere if you 
-specify a full path to the configuration file:
-```
-     -v /full/path/to/folder:/opt/mqttwarn/conf
-```
-
-##### Functions
-If you have one or more files of Python functions in the same folder
-as your `.ini` file, then prefix
- the filenames in `.ini` file with a folder:
-```
-functions = 'functions/funcs.py'
-```
-Then add this argument to `docker run`:
-```
-    -v $PWD:/opt/mqttwarn/functions
-```
-
-##### Log file
-
-By default the log file will be created inside the container.
-If you would like instead log to a file on the host, add this to your
-`mqttwarn.ini` file:
-```
-logfile = 'log/mqttwarn.log'
-```
-Add this argument to `docker run`
-```
-    -v $PWD:/opt/mqttwarn/log
-```
-`mqttwarn.log` will be created in your current folder,
-and appended to
-each time the container is executed. You can delete the file
-between executions.
-
-Another solution is to write logs directly to stdout inside the container. That way they are piped to the docker logs engine and your terminal directly, without producing any files.
-```
-logfile = '/dev/stdout'
-```
-
-
-##### If your MQTT Broker is Also Running in Docker on the Same Host
-
-If you give the MQTT broker container a name, then you can 
-refer to it by name rather than by
-IP address.  For instance, if it's named `mosquitto` 
- put this in your `mqttwarn.ini` file:
-```
-hostname  = 'mosquitto'
-```
-Then add this argument to `docker run`:
-```
-    --link mosquitto
-```
-
-##### A full example
-
-If you have your `.ini` and Python files in your current directory,
-this will run `mqttwarn` and place the log file in the current directory:
-```
-$ docker run -d --rm --name mqttwarn \
-    -v $PWD:/opt/mqttwarn/conf \
-    -v $PWD:/opt/mqttwarn/functions \
-    -v $PWD:/opt/mqttwarn/log \
-    --link mosquitto \
-    jpmens/mqttwarn
-```
-
-
-
-### Build the image
-
-If you are making any changes to the `mqttwarn` application or to
-the `Dockerfile`, you can build a local image from the files on your drive
-(not from the files on Github).
-
-Execute the following from the root of the project :
-
-```
-docker build -t mqttwarn-local .
-```
-
-You can then edit any files and rebuild the image as many times as you need. 
-You don't need to commit any changes.
-
-The name `mqttwarn-local` is not meaningful, other than
-making it obvious when you run it that you are using your
-own personal image.  You can use any name you like, but avoid
-`mqttwarn` otherwise it's easily confused with the official images.
-
+In order to run `mqttwarn` on Docker, please follow up at [DOCKER.md](DOCKER.md).
 
 
 ## Examples ##

README.rst

@@ -23,6 +23,7 @@
 ########
 mqttwarn
 ########
+
 To *warn*, *alert*, or *notify*.
 
 .. image:: https://raw.githubusercontent.com/jpmens/mqttwarn/master/assets/google-definition.jpg
@@ -33,6 +34,7 @@ To *warn*, *alert*, or *notify*.
 *****
 About
 *****
+
 mqttwarn - subscribe to MQTT topics and notify pluggable services.
 
 
@@ -71,19 +73,22 @@ MQTT topic ``home/monitoring/+`` as notification via *e-mail* and *Pushover*.
 
 
 .. _handbook: https://github.com/jpmens/mqttwarn/blob/master/HANDBOOK.md
+.. _Docker handbook: https://github.com/jpmens/mqttwarn/blob/master/DOCKER.md
 .. _handbook_services: https://github.com/jpmens/mqttwarn/blob/master/HANDBOOK.md#supported-notification-services
 
 
 *************
 Documentation
 *************
+
 The handbook_ is the right place to read all about *mqttwarn*'s
 features and service plugins.
 
 
 ************
 Installation
 ************
+
 Synopsis::
 
     pip install --upgrade mqttwarn
@@ -97,10 +102,19 @@ You can also add support for multiple services, all at once::
     pip install --upgrade 'mqttwarn[apprise,asterisk,nsca,osxnotify,tootpaste,xmpp]'
 
 
+***************
+Container image
+***************
+
+For running ``mqttwarn`` on a container infrastructure like Docker or
+Kubernetes, there are images on Docker Hub called ``jpmens/mqttwarn``.
+To read more about this topic, please follow up on the `Docker handbook`_.
+
 
 *************
 Configuration
 *************
+
 First, create configuration and custom Python starter files
 ``mqttwarn.ini`` and ``samplefuncs.py`` and edit them to your taste::
 

etc/mqttwarn.openrc

@@ -1,10 +1,9 @@
 #!/sbin/openrc-run
 
-command="/usr/bin/python /opt/mqttwarn/mqttwarn.py"
+command="/usr/local/bin/mqttwarn"
 command_args="${MQTTWARN_OPTIONS}"
 command_background=yes
 pidfile=/run/mqttwarn.pid
-directory=/opt/mqttwarn
 
 name="mqttwarn"
 description="mqttwarn pluggable mqtt notification service"