Merge pull request #883 from escalate/master

Update README.md with better instructions for running created by @escalate

README.md

@@ -70,24 +70,24 @@ ATTENTION: If running Java9, you will need to add the xml bind module
 ```
 java -jar  --add-modules java.xml.bind ha-bridge-5.2.1.jar
 ```
-### Automation on Linux systems
-To have this configured and running automatically there are a few resources to use. One is using Docker and a docker container has been built for this and can be gotten here: https://github.com/aptalca/docker-ha-bridge
 
-Create the directory and make sure that ha-bridge-5.2.1.jar is in your /home/pi/habridge directory.
+## Manual installation of ha-bridge and setup of systemd service
+Next gen Linux systems (this includes the Raspberry Pi), use systemd to run and manage services.
+Here is a link on how to use systemd: https://www.digitalocean.com/community/tutorials/how-to-use-systemctl-to-manage-systemd-services-and-units
+
+Create the directory and make sure that ha-bridge-5.2.1.jar is in your /home/pi/ha-bridge directory.
+
 ```
-pi@raspberrypi:~ $ mkdir habridge
+pi@raspberrypi:~ $ mkdir ha-bridge
-pi@raspberrypi:~ $ cd habridge
+pi@raspberrypi:~ $ cd ha-bridge
 
-pi@raspberrypi:~/habridge $ wget https://github.com/bwssytems/ha-bridge/releases/download/v5.2.1/ha-bridge-5.2.1.jar
+pi@raspberrypi:~/ha-bridge $ wget https://github.com/bwssytems/ha-bridge/releases/download/v5.2.1/ha-bridge-5.2.1.jar
 ```
 
-#### System Control Setup on a pi (preferred)
+Create the ha-bridge.service unit file:
-For next gen Linux systems (this includes the Raspberry Pi), here is a systemctl unit file that you can install. Here is a link on how to do this: https://www.digitalocean.com/community/tutorials/how-to-use-systemctl-to-manage-systemd-services-and-units
-
-Start here to create the habridge.service unit file:
 ```
 pi@raspberrypi:~ $ cd /etc/systemd/system
-pi@raspberrypi:~ $ sudo nano habridge.service
+pi@raspberrypi:~ $ sudo nano ha-bridge.service
 ```
 Copy the text below into the editor nano.
 ```
@@ -98,58 +98,92 @@ After=network.target
 
 [Service]
 Type=simple
+
 WorkingDirectory=/home/pi/habridge
 ExecStart=/usr/bin/java -jar -Dconfig.file=/home/pi/habridge/data/habridge.config /home/pi/habridge/ha-bridge-5.2.1.jar
 
 [Install]
 WantedBy=multi-user.target
 ```
+
 Save the file in the editor by hitting CTL-X and then saying Y to update and save.
 
 Reload the system control config:
 ```
 pi@raspberrypi:~ $ sudo systemctl daemon-reload
 ```
+
 To start the bridge:
 ```
-pi@raspberrypi:~ $ sudo systemctl start habridge.service
+pi@raspberrypi:~ $ sudo systemctl start ha-bridge.service
 ```
+
 To start the service at boot, use the `enable` command:
 ```
-pi@raspberrypi:~ $ sudo systemctl enable habridge.service
+pi@raspberrypi:~ $ sudo systemctl enable ha-bridge.service
 ```
+
 To look at the log, the output goes into the system log at `/var/log/syslog':
 ```
 pi@raspberrypi:~ $ tail -f /var/log/syslog
 ```
-#### Basic script setup to run the bridge on a pi.
 
-*NOTE ON RC.LOCAL*: Due to the way network subsystem is brought up on the pi, it uses the new systemctl to start services. The old style runlevel setup, which rc.local is part of does not get the benefit of knowing if the network has been fully realized. Starting ha-bridge from rc.local on next gen systems will cause unexpected results and issues with discovering registered devices. 
+### ha-bridge inside Docker container
+Docker start offering official support for Raspbian operating system since autumn 2016.
+Running services inside containers became to be a good alternative to normal installation method described before.
 
-Edit the shell script for starting:
+Install Docker Community Edition (CE) on Raspberry Pi
 ```
-pi@raspberrypi:~/habridge $ nano starthabridge.sh
+pi@raspberrypi:~ $ curl -fsSL get.docker.com -o get-docker.sh
+pi@raspberrypi:~ $ sudo sh get-docker.sh
 ```
-Then cut and past this, modify any locations that are not correct
-```
-cd /home/pi/habridge
-rm /home/pi/habridge/habridge-log.txt
-nohup java -jar -Dconfig.file=/home/pi/habridge/data/habridge.config /home/pi/habridge/ha-bridge-5.2.1.jar > /home/pi/habridge/habridge-log.txt 2>&1 &
 
-chmod 777 /home/pi/habridge/habridge-log.txt
+For every architecture there is a specialized ha-bridge Docker image available.
+Please use the suitable image from the following list.
+
+* Generic x86 / x86_64 system: [aptalca/home-automation-bridge](https://hub.docker.com/r/aptalca/home-automation-bridge)
+* Raspberry Pi 1 (ARM): [habridge/ha-bridge-raspberry-pi](https://hub.docker.com/r/habridge/ha-bridge-raspberry-pi)
+* Raspberry Pi 2 (ARM): [habridge/ha-bridge-raspberry-pi2](https://hub.docker.com/r/habridge/ha-bridge-raspberry-pi2)
+* Raspberry Pi 3 (ARM): [habridge/ha-bridge-raspberrypi3](https://hub.docker.com/r/habridge/ha-bridge-raspberrypi3)
+
+The following example explains how to run the latest version of ha-bridge Docker container on Raspberry Pi 3.
 ```
-Exit and save the file with ctrl-X and follow the prompts and then execute on the command line:
+pi@raspberrypi:~ $ docker pull habridge/ha-bridge-raspberrypi3
+pi@raspberrypi:~ $ docker run \
+    --name ha-bridge \
+    --rm \
+    --init \
+    --detach \
+    --net=host \
+    --volume=$PWD:/ha-bridge/data \
+    --volume=/etc/localtime:/etc/localtime:ro \
+    --volume=/etc/timezone:/etc/timezone:ro \
+    habridge/ha-bridge-raspberrypi3
 ```
-pi@raspberrypi:~/habridge $ chmod u+x starthabridge.sh
+
+To set additional arguments for ha-bridge just write them as arguments for docker run command.
 ```
-Then execute the script:
+pi@raspberrypi:~ $ docker run \
+     --name ha-bridge \
+     --rm \
+     --init \
+     --detach \
+     --net=host \
+     --volume=$PWD:/ha-bridge/data \
+     --volume=/etc/localtime:/etc/localtime:ro \
+     --volume=/etc/timezone:/etc/timezone:ro \
+     habridge/ha-bridge-raspberry-pi3 \
+     -Dserver.port=8080 \
+     -Dsecurity.key=secret
 ```
-pi@raspberrypi:~/habridge $ ./starthabridge.sh
+
+To halt the ha-bridge Docker container use the `stop` command:
 ```
-You should now be running the bridge. Check for errors:
+pi@raspberrypi:~ $ docker stop ha-bridge
-```
-pi@raspberrypi:~/habridge $ tail -f habridge-log.txt
 ```
+
+If you like to automate the deployment just use the Ansible role on https://github.com/escalate/ansible-ha-bridge-docker.
+
 ## Run ha-bridge alongside web server already on port 80
 These examples will help you proxy your current webserver requests to the ha-bridge running on a different port, such as 8080.
 
@@ -287,7 +321,7 @@ Provide IP Addresses of your HAL Systems that you want to utilize with the bridg
 #### MQTT Client IDs and IP Addresses
 Provide Client ID and IP Addresses and ports of your MQTT Brokers that you want to utilize with the bridge. Also, you can provide the username and password if you have secured your MQTT broker which is optional. When these Client ID and IP's are given, the bridge will be able to publish MQTT messages by the call it receives and send it to the target MQTT Broker you configure. The MQTT Messages Tab will become available to help you build messages.
 #### Home Assistant Names and IP Addresses
-Provide IP Addresses and ports of your Home Assistant that you want to utilize with the bridge. Also, give a meaningful name to each one so it is easy to decipher in the helper tab. When these names and IP's are given, the bridge will be able to control the devices or scenes by the call it receives and send it to the target Home Assistant and device/scene you configure. 
+<Provide IP Addresses and ports of your Home Assistant that you want to utilize with the bridge. Also, give a meaningful name to each one so it is easy to decipher in the helper tab. When these names and IP's are given, the bridge will be able to control the devices or scenes by the call it receives and send it to the target Home Assistant and device/scene you configure. 
 #### HomeWizard Gateways Names and IP Addresses
 Provide IP Addresses of your HomeWizard Systems that you want to utilize with the bridge. Also, give a meaningful name to each one so it is easy to decipher in the helper tab. When these names and IP's are given, the bridge will be able to control the devices or scenes by the call it receives and send it to the target HomeWizard and device/scene you configure. 
 #### Domoticz Names and IP Addresses