Fix all installation articles according to style guide (openhab#426)

* Add first version of styleguide, refine rules Signed-off-by: Thomas Dietrich <[email protected]> * Fix all installation articles according to style guide Signed-off-by: Thomas Dietrich <[email protected]>
semperor · Jul 6, 2017 · 5372975 · 5372975
1 parent a601f8c
commit 5372975
Show file tree

Hide file tree

Showing 14 changed files with 538 additions and 470 deletions.
diff --git a/installation/designer.md b/installation/designer.md
@@ -12,7 +12,8 @@ Just like known from other IDEs, the Designer allows to browse and edit the conf
 
 ## Network Preparations
 
-If your openHAB instance is set up on a different device or a dedicated system, the Designer can be installed and executed on your personal PC or Mac. The Designer needs to be able to access the configuration files on the remote openHAB host.
+If your openHAB instance is set up on a different device or a dedicated system, the Designer can be installed and executed on your personal PC or Mac.
+The Designer needs to be able to access the configuration files on the remote openHAB host.
 
 You have to have a [network share](https://en.wikipedia.org/wiki/Shared_resource) set up on the remote host and mounted on your local device.
 Steps needed to so are specific to the hosts operation system.
@@ -23,28 +24,28 @@ If you are using [openHABian](openhabian.html), the needed set of network shares
 
 ## Setup
 
-* Get the latest version from: [Eclipse SmartHome Designer Downloads](https://github.com/eclipse/smarthome/blob/master/docs/documentation/community/downloads.md#designer-builds) (*Note:* the "Snapshot" build is currently not recommended for daily use)
+- Get the latest version from: [Eclipse SmartHome Designer Downloads](https://github.com/eclipse/smarthome/blob/master/docs/documentation/community/downloads.md#designer-builds)
+  (*Note:* the "Snapshot" build is currently not recommended for daily use)
 
 The downloaded `.zip` archive contains the Designer executable.
 
-* **Windows**: Extract the archive to a path of your choosing, e.g. `C:\designer`
-* **Linux**: Extract the archive to a path of your choosing, e.g. `/opt/designer`
-* **Max OSX**: Extract the archive to your applications folder
+- **Windows**: Extract the archive to a path of your choosing, e.g. `C:\designer`
+- **Linux**: Extract the archive to a path of your choosing, e.g. `/opt/designer`
+- **Max OSX**: Extract the archive to your applications folder
 
 ## First Launch
 
-After launching the Designer executable, you will see an empty configuration file pane on the top left:
+After launching the Designer executable you will see an empty configuration file pane on the top left.
 
-![](images/smarthome-designer-10.png)
+  ![SmartHome Designer standard view](images/smarthome-designer-10.png)
 
-* Click on the "select a configuration folder" icon at the top right of the configuration window
-* Navigate to your openHAB configuration folder (containing `items`, `rules`, ...)
+Click on the "Select a configuration folder" icon at the top right of the configuration window and navigate to your openHAB configuration folder (containing `items`, `rules`, ...).
 
-![](images/smarthome-designer-15.png)
+  ![SmartHome Designer configuration folder selection](images/smarthome-designer-15.png)
 
-* The configuration pane should now list the different configuration folders:
+The configuration pane should now list the different configuration folders:
 
-![](images/smarthome-designer-20.png)
+  ![SmartHome Designer standard view with loaded configuration](images/smarthome-designer-20.png)
 
 ## Usage
 
@@ -53,6 +54,3 @@ Changes are automatically loaded by the openHAB runtime.
 More details about the syntax of the different configuration files can be found in the [Configuration]({{base}}/configuration/index.html) chapter.
 
 Hint: Press `<Ctrl + N>` to create a new file.
-
-
-
diff --git a/installation/docker.md b/installation/docker.md
@@ -5,31 +5,33 @@ title: Docker
 
 {% include base.html %}
 
-# Docker Installation
+# openHAB 2 inside a Docker Container
+
+Docker is the most popular among a collection of tools that provide containerization.
+Containerization allows one to run a server in its own isolated environment without the overhead of running a full virtual machine.
+
+This page is structured as follows:
 
 {::options toc_levels="2..4"/}
 
-* TOC
+- TOC
 {:toc}
 
-# Why Docker?
-
-Docker is the most popular among a collection of tools that provide containerization.
-Containerization allows one to run a server in its own isolated environment without the overhead of running a full virtual machine.
+## Why Docker?
 
 There are several reasons one would want to run openHAB in a Docker container.
 These include:
 
-* easily test out different versions
-* run multiple instances side by side
-* easily map the OH ports to other ports without modifying configs
-* isolate OH from the rest of your server environment (e.g. configure the container's networking so the only way it can be accessed is through a reverse proxy)
-* orchestration and automated deployment of OH and related servers
+- easily test out different versions
+- run multiple instances side by side
+- easily map the OH ports to other ports without modifying configs
+- isolate OH from the rest of your server environment (e.g. configure the container's networking so the only way it can be accessed is through a reverse proxy)
+- orchestration and automated deployment of OH and related servers
 
 However, this flexibility comes at a cost.
 For example, because openHAB is running in its own container with only enough installed to run openHAB, the Exec binding is very likely to be useless to you because the container will not have access to the programs and files you need.
 
-# About the openHAB installed in the Image
+## About the openHAB installed in the Image
 
 Inside the Docker Image, openHAB is installed to `/openhab`.
 The install is a manual installation so all of the files are located here.
@@ -39,14 +41,14 @@ The Image has a very minimal installation of Linux with no services running and
 
 At the time of this writing, the official image uses the latest snapshot version of openHAB 2.
 
-# Installation through Docker
+## Installation through Docker
 
-## Obtaining the Official image from DockerHub
+### Obtaining the Official image from DockerHub
 
 [Docker Hub](https://hub.docker.com/r/openhab/openhab/) has the basic information necessary to acquire and run the Docker image.
 Please review those instructions before continuing to select the correct image for your machine and download the image.
 
-## Create the openhab user
+### Create the openhab user
 
 Just because one is running in an isolated container does not mean running as root is recommended.
 So first create an `openhab` user configured to be a system user with no home and no shell.
@@ -62,7 +64,7 @@ Add your regular user to the `openhab` group.
 usermod -a -G openhab <user>
 ```
 
-## Create the openHAB conf, userdata, and addon directories
+### Create the openHAB conf, userdata, and addon directories
 
 These directories will be mounted into the running Docker container and are where the configurations and persistence data will be stored.
 Note that the software running inside a Docker container cannot follow the symbolic links located in a mounted volume.
@@ -76,7 +78,7 @@ mkdir /opt/openhab/addons
 chown -R openhab:openhab /opt/openhab
 ```
 
-## Running the Container as a Service Managed by Docker
+### Running the Container as a Service Managed by Docker
 
 Services can be run an maintained on a Linux machine one of two ways, using Docker or using the system's built in service management (e.g. systemd).
 If using docker to manage the service, run the following command:
@@ -97,19 +99,20 @@ docker run \
 ```
 
 Where `<uid>` is the user ID number for the `openhab` user which you can obtain using the command `id openhab`, `<version>` is the version of openHAB and `<arch>` is the architecture of your system.
-It is important that ID number is passed in as the ID for the `openhab` user inside the container will not match the id of the user on your host system and file permissions may be a bit odd (e.g. why does www-data own my openHAB config files?)
+It is important that the ID number is passed in.
+The ID for the `openhab` user inside the container will not match the ID of the user on your host system and file permissions may be a bit odd (e.g. why does www-data own my openHAB config files?).
 
-See below for an explanation of the fields passed to docker and potential additional fields.
+See below for an explanation of the fields passed to Docker and potential additional fields.
 
 Once it successfully runs (it should be listed with a CREATED time that does not include "restarting" when running `docker ps`):
 
-* To stop the service run `docker stop openhab`.
-* To restart the service run `docker restart openhab`
-* To start the service run `docker start openhab`
+- To stop the service run `docker stop openhab`.
+- To restart the service run `docker restart openhab`
+- To start the service run `docker start openhab`
 
 To change the runtime parameters stop the container then execute the long command above with the new parameters.
 
-## Running the Container as a Service Controlled by Systemd
+### Running the Container as a Service Controlled by Systemd
 
 If running on a Systemd based Linux distro (Ubuntu 16.1 to be specific).
 The following openhab2.service file will start a new openHAB 2 container every time it starts the service and destroy that container when the service stops.
@@ -143,47 +146,47 @@ WantedBy=multi-user.target
 ```
 
 Where `<uid>` is the user ID number for the `openhab` user which you can obtain using the command `id openhab`, `<version>` is the version of openHAB and `<arch>` is the architecture of your system.
-It is important that ID number is passed in as the ID for the `openhab` user inside the container will not match the id of the user on your host system and file permissions may be a bit odd (e.g. why does www-data own my openHAB config files?)
+It is important that the ID number is passed in.
+The ID for the `openhab` user inside the container will not match the ID of the user on your host system and file permissions may be a bit odd (e.g. why does www-data own my openHAB config files?).
 
 Place this openhab2.service file into `/etc/systemd/system`.
 
 Then run `sudo systemctl enable openhab2.service`.
 
 Finally run `sudo systemctl start openhab2.service` to start openHAB running.
 
-# Explanation of Arguments Passed to Docker
-
-* `/usr/bin/docker run` : create a new container from the passed in Image (last argument)
-* `--name=openhab` : give the container a human remember able name
-* `--net=host` : by default Docker will place a container into its own network stack. However, openHAB 2 requires UPnP discovery so this parameter makes the Docker container use the host's network stack.
-* `-v /etc/localtime:/etc/localtime:ro` : ties the time of the container to the host's time, read only so the container cannot change the host's time
-* `-v /etc/timezone:/etc/timezone:ro` : ties the timezone of the container to the host's time zone, read only so the container cannot change the host's time zone
-* `-v /opt/openhab/conf:/openhab/conf` : location of the conf folder for openHAB configurations (NOTE: you must create these folders on the host before running the container)
-* `-v /opt/openhab/userdata:/openhab/userdata` : location for logs, cache, persistence databases, etc.
-* `-v /opt/openhab/addons:/openhab/addons` : only needed if installing addons unavailable via PaperUI or the Karaf Console
-* `-v /opt/openhab/.java:/openhab/.java` : needed by the Nest binding (and others?), location of the security token
-* `--user=<uid>` : sets the user that runs the processes inside the container to match the uid passed, makes sure the `openhab` user can read and write to all needed files
-* `--device=/dev/ttyUSB0` : location of my zwave controller, change and/or add more --device tags to pass all your devices needed by openHAB to the container
-* `--restart=always` : if the container crashes or the syetem reboots the container is restarted
-* `openhab/openhab:<version>-<architecture>` : name of the Docker Image
-* `start_debug.sh` : You can start the container with the command ``docker run -it openhab/openhab:<version>-<architecture> ./start_debug.sh`` to get into the debug shell. You might need to mount additional volumes and parameters as described above.
-
-# Environment Variables
-
-*  `EXTRA_JAVA_OPTS`=""
-*  `LC_ALL`=en_US.UTF-8
-*  `LANG`=en_US.UTF-8
-*  `LANGUAGE`=en_US.UTF-8
-*  `OPENHAB_HTTP_PORT`=8080
-*  `OPENHAB_HTTPS_PORT`=8443
-*  `USER_ID`=9001
+## Explanation of Arguments Passed to Docker
+
+- `/usr/bin/docker run` : create a new container from the passed in Image (last argument)
+- `--name=openhab` : give the container a human remember able name
+- `--net=host` : by default Docker will place a container into its own network stack. However, openHAB 2 requires UPnP discovery so this parameter makes the Docker container use the host's network stack.
+- `-v /etc/localtime:/etc/localtime:ro` : ties the time of the container to the host's time, read only so the container cannot change the host's time
+- `-v /etc/timezone:/etc/timezone:ro` : ties the timezone of the container to the host's time zone, read only so the container cannot change the host's time zone
+- `-v /opt/openhab/conf:/openhab/conf` : location of the conf folder for openHAB configurations (NOTE: you must create these folders on the host before running the container)
+- `-v /opt/openhab/userdata:/openhab/userdata` : location for logs, cache, persistence databases, etc.
+- `-v /opt/openhab/addons:/openhab/addons` : only needed if installing addons unavailable via PaperUI or the Karaf Console
+- `-v /opt/openhab/.java:/openhab/.java` : needed by the Nest binding (and others?), location of the security token
+- `--user=<uid>` : sets the user that runs the processes inside the container to match the uid passed, makes sure the `openhab` user can read and write to all needed files
+- `--device=/dev/ttyUSB0` : location of my zwave controller, change and/or add more --device tags to pass all your devices needed by openHAB to the container
+- `--restart=always` : if the container crashes or the system reboots the container is restarted
+- `openhab/openhab:<version>-<architecture>` : name of the Docker Image
+- `start_debug.sh` : You can start the container with the command ``docker run -it openhab/openhab:<version>-<architecture> ./start_debug.sh`` to get into the debug shell. You might need to mount additional volumes and parameters as described above.
+
+## Environment Variables
+
+- `EXTRA_JAVA_OPTS`=""
+- `LC_ALL`=en_US.UTF-8
+- `LANG`=en_US.UTF-8
+- `LANGUAGE`=en_US.UTF-8
+- `OPENHAB_HTTP_PORT`=8080
+- `OPENHAB_HTTPS_PORT`=8443
+- `USER_ID`=9001
 
 By default the openHAB user in the container is running with:
 
-* `uid=9001(openhab) gid=9001(openhab) groups=9001(openhab)`
-
+- `uid=9001(openhab) gid=9001(openhab) groups=9001(openhab)`
 
-# Updating the Image
+## Updating the Image
 
 Use the following steps to update the docker image and all installed add-ons.