diff --git a/installation/designer.md b/installation/designer.md index a80d962cd7..4fa74f8ce7 100644 --- 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 `` to create a new file. - - - diff --git a/installation/docker.md b/installation/docker.md index 131fa60973..d16a7fb306 100644 --- 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 ``` -## 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 `` is the user ID number for the `openhab` user which you can obtain using the command `id openhab`, `` is the version of openHAB and `` 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,7 +146,8 @@ WantedBy=multi-user.target ``` Where `` is the user ID number for the `openhab` user which you can obtain using the command `id openhab`, `` is the version of openHAB and `` 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`. @@ -151,39 +155,38 @@ 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=` : 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:-` : name of the Docker Image -* `start_debug.sh` : You can start the container with the command ``docker run -it openhab/openhab:- ./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=` : 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:-` : name of the Docker Image +- `start_debug.sh` : You can start the container with the command ``docker run -it openhab/openhab:- ./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. diff --git a/installation/index.md b/installation/index.md index bb87149087..8dbc5e16d8 100644 --- a/installation/index.md +++ b/installation/index.md @@ -16,43 +16,43 @@ Therefore, tutorials and help you may find on the internet for openHAB 1 **might ## Platform Recommendations -1. You are **new to openHAB 2** and want to give it a try? You are in luck: - - Set up openHAB 2 on your local PC or Mac in just a few steps. +1. You are **new to openHAB 2** and want to give it a try? You are in luck: + - Set up openHAB 2 on your local PC or Mac in just a few steps. -2. You gained some experience and want to use openHAB to seriously control your home? - Typical hardware and software requirements are: +2. You gained some experience and want to use openHAB to seriously control your home? + Typical hardware and software requirements are: - **24/7 availability:** A dedicated system connected by Ethernet and running continuously. - **Energy and space efficient:** A device capable of performing the task at hand without being exaggerated - **Extendibility:** Your system should be capable of running additional software like an MQTT broker or a persistence and graphing software. - - **Peripherals:** Depending on your home automation hardware, you will need additional peripheral devices such as a WiFi interface or a special USB radio module. + - **Peripherals:** Depending on your home automation hardware, you will need additional peripheral devices such as a WiFi interface or a special USB radio module. Many devices are suited to host a continuous installation of openHAB 2. Experiences with different devices and environments can be found in the [community forum hardware section](https://community.openhab.org/c/hardware/server). The [Raspberry Pi](rasppi.html) as a minimal sufficient device is quite popular, especially as we offer a quick setup with [openHABian](openhabian.html). A popular alternative is [our solution for the Synology DiskStation](synology.html), which many users already own in their homes. -The previously mentioned [openHABian](openhabian.html) can also be used to kickstart your openHAB 2 experience on existing debian/ubuntu based Linux systems. +The previously mentioned [openHABian](openhabian.html) can also be used to kickstart your openHAB 2 experience on existing Debian/Ubuntu based Linux systems. Please check the menu to the left for all available options. ## Prerequisites -Make sure that you have an up to date Java platform installed on your host system. +Make sure that you have an up to date Java platform installed on your host system. Zulu is currently the recommended Java platform for openHAB, although Oracle Java is also suitable for most configurations. -OpenJDK may be used, but it has some [known limitations](https://community.openhab.org/t/running-openhab-2-on-openjdk/21443/8?u=gatekeeper6838) with openHAB. +OpenJDK may be used, but it has some [known limitations](https://community.openhab.org/t/running-openhab-2-on-openjdk/21443/8?u=gatekeeper6838) with openHAB and is not recommended. | Java Platform | Advantages | Disadvantages | -| --- | --- | --- | +|---------------|------------|---------------| | [Zulu](https://www.azul.com/products/zulu/) | Completely open source, fully certified Java SE compliant build of OpenJDK, embedded version optimized for ARM devices [available here](http://www.azul.com/downloads/zulu-embedded/) | Not available in most default distribution package repositories | | [Oracle Java](https://java.com/en/) | Full openHAB support on all platforms | [Licensing restrictions](https://blog.takipi.com/running-java-on-docker-youre-breaking-the-law/), manual installation required on many Linux systems: [Ubuntu](https://help.ubuntu.com/community/Java), [Mint](https://community.linuxmint.com/tutorial/view/1091), and [Debian](https://wiki.debian.org/Java/Sun) are some examples | -| [OpenJDK](http://openjdk.java.net) | Supported by many Linux distributions, packages [typically available](http://openjdk.java.net/install/index.html) | [Performance issues](https://github.com/openhab/openhab-distro/issues/10#issuecomment-223786506) on ARM platforms, [compatibility issues](https://community.openhab.org/t/openhab-is-offline-message-fixed/17441/8) with certain bindings and certificates | +| [OpenJDK](http://openjdk.java.net) | Supported by many Linux distributions, packages [typically available](http://openjdk.java.net/install/index.html) | [Performance issues](https://github.com/openhab/openhab-distro/issues/10#issuecomment-223786506) on ARM platforms, [compatibility issues](https://community.openhab.org/t/openhab-is-offline-message-fixed/17441/8) with certain bindings and certificates | -> Make sure to use the 32-bit version of the JVM for ARM platforms, even on 64-bit operating systems. -> Serial connections won't work with a 64-bit JVM, preventing bindings like Z-Wave from functioning. +Please use the **32-bit version** of the JVM for ARM platforms, even on 64-bit operating systems. +Serial connections won't work with a 64-bit JVM, preventing bindings like Z-Wave from functioning. -As for now, a pre-release Java 9 installation is not recommended and is not yet supported by openHAB 2. +As for now, a pre-release **Java 9** installation is not recommended and is not yet supported by openHAB 2. -For best compatibility, namely with the openHAB Cloud service [myopenhab.org](http://www.myopenhab.org), the minimum recommended Orcacle Java 8 revision is "101". +For best compatibility, namely with the openHAB Cloud service [myopenhab.org](http://www.myopenhab.org), the minimum recommended Java 8 revision is "101". Attention: Most package managers serve an **older revision**. Check your current Java version by opening a command line console and typing `java -version`: @@ -66,14 +66,14 @@ Java HotSpot(TM) Client VM (build 25.121-b13, mixed mode) Before you can start, three decisions have to be made: -1. openHAB 2 is available as a platform independent archive file or through a package repository: - - **Manual setup:** Download and extract a platform independent zip archive: [Mac OS X](macosx.html), [Windows](windows.html), [Linux](linux.html#manual-installation) - - **Package setup:** Install though a package repository, including automatic updates. +1. openHAB 2 is available as a platform independent archive file or through a package repository: + - **Manual setup:** Download and extract a platform independent zip archive: [Mac OS X](macosx.html), [Windows](windows.html), [Linux](linux.html#manual-installation) + - **Package setup:** Install though a package repository, including automatic updates. This option is only available for Debian or Ubuntu derivatives and the recommended choice: [Linux (apt/deb)](linux.html#package-repository-installation) -2. Stable release or cutting edge: - - **Stable:** Use the latest official release ([hosted on Bintray](https://bintray.com/openhab/mvn/openhab-distro)). - - **Snapshot:** Benefit from the latest changes in the daily created snapshot ([hosted on CloudBees](https://openhab.ci.cloudbees.com/job/openHAB-Distribution)). +2. Stable release or cutting edge: + - **Stable:** Use the latest official release ([hosted on Bintray](https://bintray.com/openhab/mvn/openhab-distro)). + - **Snapshot:** Benefit from the latest changes in the daily created snapshot ([hosted on CloudBees](https://openhab.ci.cloudbees.com/job/openHAB-Distribution)). ## Installation @@ -83,9 +83,10 @@ Please follow the instructions in the installation article matching your platfor After you got openHAB 2 set up and running, there are a few additional setup steps you should consider: -* Configure a network share on your openHAB host device and mount it locally: [Linux Samba Share](linux.html#network-sharing), Windows file sharing, ... -* Install the [Eclipse SmartHome Designer](designer.html) on your local machine, to manage your (remote) configuration files. - The designer comes with built-in support for the openHAB syntax and elements. +- Configure a network share on your openHAB host device and mount it locally: [Linux Samba Share](linux.html#network-sharing), Windows file sharing, ... + +- Install the [Eclipse SmartHome Designer](designer.html) on your local machine, to manage your (remote) configuration files. + The designer comes with built-in support for the openHAB syntax and elements. ## Getting started diff --git a/installation/linux.md b/installation/linux.md index 8ea70584cc..dcf8f7f47d 100644 --- a/installation/linux.md +++ b/installation/linux.md @@ -15,13 +15,13 @@ This page is structured as follows: {::options toc_levels="2..4"/} -* TOC +- TOC {:toc} If you are unfamiliar with Linux, SSH and the Linux console or if you want to improve your skills, read up on these important topics. A lot of helpful articles can be found on the internet, for example: -* "Learn the ways of Linux-fu, for free" interactively with exercises at [linuxjourney.com](https://linuxjourney.com). +- "Learn the ways of Linux-fu, for free" interactively with exercises at [linuxjourney.com](https://linuxjourney.com). Linux file permissions is one of the biggest sources of issues, Linux novices run into. If you find yourself in a situation, where you have **no write access** to the openHAB configuration or system files wrong permissions and/or the incorrect use of `sudo` are often the cause. @@ -38,7 +38,8 @@ Apt Based Systems {% include collapsible/body.html %} A repository providing the latest Oracle Java 8 revision (above "101") is being maintained by the [Webupd8 Team](https://launchpad.net/~webupd8team/+archive/ubuntu/java). -Follow the provided guides for either a [repository based](http://www.webupd8.org/2012/09/install-oracle-java-8-in-ubuntu-via-ppa.html) or a [PPA based](http://www.webupd8.org/2014/03/how-to-install-oracle-java-8-in-debian.html) installation. +Follow the provided guides for either a +[repository based](http://www.webupd8.org/2012/09/install-oracle-java-8-in-ubuntu-via-ppa.html) or a [PPA based](http://www.webupd8.org/2014/03/how-to-install-oracle-java-8-in-debian.html) installation. In short these are the commands to execute step-by-step on most systems: ```shell @@ -58,11 +59,11 @@ Yum or Dnf Based Systems {% include collapsible/body.html %} To get the latest version go to the [Oracle Java 8 JRE Downloads Page](http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html). -You then need to accept the license agreement, copy the download link of the appropriate Linux .rpm package and then finally paste it place of "[Download Link Here]" below: +You then need to accept the license agreement, copy the download link of the appropriate Linux .rpm package and then finally paste it in place of "URL-HERE" below: ```shell cd ~ -wget --no-check-certificate --no-cookies --header "Cookie: oraclelicense=accept-securebackup-cookie" "[Download Link Here]" +wget --no-check-certificate --no-cookies --header "Cookie: oraclelicense=accept-securebackup-cookie" "URL-HERE" ``` You can then install the downloaded package with: @@ -101,37 +102,37 @@ sudo apt-get install apt-transport-https Then, you can choose between, *Official (Stable)*, *Beta* or *Snapshot* builds: -* **Stable Release** +- **Stable Release** - The stable builds contain the latest official release with tested features. + The stable builds contain the latest official release with tested features. - Add the **openHAB 2 Stable Repository** to your systems apt sources list: + Add the **openHAB 2 Stable Repository** to your systems apt sources list: - ```shell - echo 'deb https://dl.bintray.com/openhab/apt-repo2 stable main' | sudo tee /etc/apt/sources.list.d/openhab2.list - ``` + ```shell + echo 'deb https://dl.bintray.com/openhab/apt-repo2 stable main' | sudo tee /etc/apt/sources.list.d/openhab2.list + ``` -* **Testing Release** +- **Testing Release** - The beta and release candidate builds come out less frequently, but will contain new features that are currently in the testing phase. + The beta and release candidate builds come out less frequently, but will contain new features that are currently in the testing phase. - Add the **openHAB 2 Beta Repository** to your systems apt sources list: + Add the **openHAB 2 Beta Repository** to your systems apt sources list: - ```shell - echo 'deb https://dl.bintray.com/openhab/apt-repo2 testing main' | sudo tee /etc/apt/sources.list.d/openhab2.list - ``` + ```shell + echo 'deb https://dl.bintray.com/openhab/apt-repo2 testing main' | sudo tee /etc/apt/sources.list.d/openhab2.list + ``` -* **Snapshot Release** +- **Snapshot Release** - The snapshot build is created [almost daily](https://openhab.ci.cloudbees.com/job/openhab-linuxpkg/), and include the latest changes to the openHAB 2 core and add-ons. - These changes are often unstable, so you should use this branch only for testing or development purposes. + The snapshot build is created [almost daily](https://openhab.ci.cloudbees.com/job/openhab-linuxpkg/), and include the latest changes to the openHAB 2 core and add-ons. + These changes are often unstable, so you should use this branch only for testing or development purposes. - The snapshot repository is hosted in openHAB's [JFrog Artifactory instance](https://www.jfrog.com/Artifactory). - To use it, add the **openHAB 2 Unstable Repository** to your systems apt sources list: + The snapshot repository is hosted in openHAB's [JFrog Artifactory instance](https://www.jfrog.com/Artifactory). + To use it, add the **openHAB 2 Unstable Repository** to your systems apt sources list: - ```shell - echo 'deb https://openhab.jfrog.io/openhab/openhab-linuxpkg unstable main' | sudo tee /etc/apt/sources.list.d/openhab2.list - ``` + ```shell + echo 'deb https://openhab.jfrog.io/openhab/openhab-linuxpkg unstable main' | sudo tee /etc/apt/sources.list.d/openhab2.list + ``` Next, resynchronize the package index: @@ -162,45 +163,45 @@ Yum or Dnf Based Systems The RPM repo information should be defined inside a file, make a new file at `/etc/yum.repos.d/openhab.repo` with the following contents depending on your choice of release. You may add all three to the same file, but make sure the desired repo is is set to `enabled=1`: -* **Stable Release** +- **Stable Release** - The stable builds contain the latest official release with tested features. + The stable builds contain the latest official release with tested features. - ```text - [openHAB-Stable] - name=openHAB 2.x.x Stable - baseurl=https://dl.bintray.com/openhab/rpm-repo2/stable - gpgcheck=1 - gpgkey=https://bintray.com/user/downloadSubjectPublicKey?username=openhab - enabled=1 - ``` + ```text + [openHAB-Stable] + name=openHAB 2.x.x Stable + baseurl=https://dl.bintray.com/openhab/rpm-repo2/stable + gpgcheck=1 + gpgkey=https://bintray.com/user/downloadSubjectPublicKey?username=openhab + enabled=1 + ``` -* **Testing Release** +- **Testing Release** - The beta or release candidate builds come out less frequently, but will contain new features that are currently in the testing phase. + The beta or release candidate builds come out less frequently, but will contain new features that are currently in the testing phase. - ```text - [openHAB-Testing] - name=openHAB 2.x.x Testing - baseurl=https://dl.bintray.com/openhab/rpm-repo2/testing - gpgcheck=1 - gpgkey=https://bintray.com/user/downloadSubjectPublicKey?username=openhab - enabled=1 - ``` + ```text + [openHAB-Testing] + name=openHAB 2.x.x Testing + baseurl=https://dl.bintray.com/openhab/rpm-repo2/testing + gpgcheck=1 + gpgkey=https://bintray.com/user/downloadSubjectPublicKey?username=openhab + enabled=1 + ``` -* **Snapshot Release** +- **Snapshot Release** - The snapshot build is created [almost daily](https://openhab.ci.cloudbees.com/job/openhab-linuxpkg/), and include the latest changes to the openHAB 2 core and add-ons. - These changes are often unstable, so you should use this branch only for testing or development purposes. + The snapshot build is created [almost daily](https://openhab.ci.cloudbees.com/job/openhab-linuxpkg/), and include the latest changes to the openHAB 2 core and add-ons. + These changes are often unstable, so you should use this branch only for testing or development purposes. - ```text - [openHAB-Snapshots] - name=openHAB 2.x.x Snapshots - baseurl=https://openhab.jfrog.io/openhab/openhab-linuxpkg-rpm/unstable - gpgcheck=1 - gpgkey=https://openhab.jfrog.io/openhab/api/gpg/key/public - enabled=1 - ``` + ```text + [openHAB-Snapshots] + name=openHAB 2.x.x Snapshots + baseurl=https://openhab.jfrog.io/openhab/openhab-linuxpkg-rpm/unstable + gpgcheck=1 + gpgkey=https://openhab.jfrog.io/openhab/api/gpg/key/public + enabled=1 + ``` Now install openHAB with the following command, please note that for systems that support it `dnf` can be used instead of yum: @@ -248,7 +249,7 @@ Systems based on **systemd** (e.g. Debian 8, Ubuntu 15.x, Raspbian Jessie and ne ```shell sudo systemctl start openhab2.service sudo systemctl status openhab2.service - + sudo systemctl daemon-reload sudo systemctl enable openhab2.service ``` @@ -256,7 +257,6 @@ sudo systemctl enable openhab2.service {% include collapsible/item-end.html %} {% include collapsible/end.html %} - The first start may take **up to 15 minutes**, this is a good time to reward yourself with hot coffee or a freshly brewed tea! You should be able to reach the openHAB 2 portal at [http://openhab-device:8080](http://openhab-device:8080) at this point. @@ -279,10 +279,10 @@ Systems based on **sysVinit** (e.g. Ubuntu 14.x, Debian Wheezy and older): ```shell # Learn about the current service status sudo /etc/init.d/openhab2 status - + # (Re-)Start openHAB (background service) sudo /etc/init.d/openhab2 restart - + # Stop the openHAB background service sudo /etc/init.d/openhab2 stop @@ -300,13 +300,13 @@ Systems based on **systemd** (e.g. Debian 8, Ubuntu 15.x, Raspbian Jessie and ne ```shell # Learn about the current service status sudo systemctl status openhab2.service - + # (Re-)Start openHAB (background service) sudo systemctl restart openhab2.service - + # Stop the openHAB background service sudo systemctl stop openhab2.service - + # Make openHAB automatically start after booting the Linux host sudo systemctl daemon-reload sudo systemctl enable openhab2.service @@ -464,26 +464,26 @@ We are going to download a platform independent archive file and extract it to t Choose between the latest Beta release or a Snapshot with all incoming contributions, created daily. As openHAB 2 is still in an evolving state, the snapshot may be the **preferred choice**. -* **Official Release** +- **Official Release** - Download and extract the latest offical stable version of openHAB 2 from [bintray.com/openhab](https://bintray.com/openhab/mvn/openhab-distro) to your host: + Download and extract the latest offical stable version of openHAB 2 from [bintray.com/openhab](https://bintray.com/openhab/mvn/openhab-distro) to your host: - ```shell - cd /tmp - wget -O openhab-download.zip https://bintray.com/... # Insert download link here - sudo unzip openhab-download.zip -d /opt/openhab2 - rm openhab-download.zip - ``` + ```shell + cd /tmp + wget -O openhab-download.zip https://bintray.com/... # Insert download link here + sudo unzip openhab-download.zip -d /opt/openhab2 + rm openhab-download.zip + ``` -* **Beta/RC Release** +- **Beta/RC Release** - If available, beta or release candidate builds of openHAB 2 can also be downloaded from [bintray.com/openhab](https://bintray.com/openhab/mvn/openhab-distro) and extracted to your host as shown above. + If available, beta or release candidate builds of openHAB 2 can also be downloaded from [bintray.com/openhab](https://bintray.com/openhab/mvn/openhab-distro) and extracted to your host as shown above. -* **Snapshot Release** +- **Snapshot Release** - Download and extract the latest snapshot version of openHAB 2 from [openhab.ci.cloudbees.com](https://openhab.ci.cloudbees.com/job/openHAB-Distribution) to your host. The process is analogue to above. + Download and extract the latest snapshot version of openHAB 2 from [openhab.ci.cloudbees.com](https://openhab.ci.cloudbees.com/job/openHAB-Distribution) to your host. The process is analogue to above. -The extracted openHAB files should belong to the earlier created openhab user. +The extracted openHAB files should belong to the earlier created `openhab` user. Execute: ```shell @@ -603,39 +603,39 @@ This is especially important if you are working with the latest snapshot as chan openHAB uses a script to update to any other version, or from stable to snapshot and visa-versa. Your personal configuration will be retained on upgrades, but you should **stop openHAB** and perform a backup first. -* **Versions 2.1.0 and Above** +- **Versions 2.1.0 and Above** - From version 2.1.0, openHAB is distributed with the update script included. - This script should be called from within openHAB's root directory. - Assuming the openHAB directory is in `/opt/openhab`, simply run the following commands to update to the next major version of openHAB: + From version 2.1.0, openHAB is distributed with the update script included. + This script should be called from within openHAB's root directory. + Assuming the openHAB directory is in `/opt/openhab`, simply run the following commands to update to the next major version of openHAB: - ```bash - cd /opt/openhab - sudo runtime/bin/update - ``` - - You can also specify any version as a parameter. For example, to switch back to 2.0.0: - - ```bash - sudo runtime/bin/update 2.0.0 - ``` + ```bash + cd /opt/openhab + sudo runtime/bin/update + ``` - You may also change to openHAB's more frequent, but less stable snapshot builds. - Just append "-SNAPSHOT" to the target version, e.g.: + You can also specify any version as a parameter. For example, to switch back to 2.0.0: - ```bash - sudo runtime/bin/update 2.2.0-SNAPSHOT - ``` + ```bash + sudo runtime/bin/update 2.0.0 + ``` -* **Older Versions** + You may also change to openHAB's more frequent, but less stable snapshot builds. + Just append "-SNAPSHOT" to the target version, e.g.: - If you're using a version earlier than 2.1.0, then you can use the following commands in Terminal to download the script and run it. - Assuming the openHAB directory is in `/opt/openhab`: + ```bash + sudo runtime/bin/update 2.2.0-SNAPSHOT + ``` - ```bash - cd /opt/openhab - sudo sh -c "$(curl -fsSL https://raw.githubusercontent.com/openhab/openhab-distro/master/distributions/openhab/src/main/resources/bin/update)" -- 2.1.0 - ``` +- **Older Versions** + + If you're using a version earlier than 2.1.0, then you can use the following commands in Terminal to download the script and run it. + Assuming the openHAB directory is in `/opt/openhab`: + + ```bash + cd /opt/openhab + sudo sh -c "$(curl -fsSL https://raw.githubusercontent.com/openhab/openhab-distro/master/distributions/openhab/src/main/resources/bin/update)" -- 2.1.0 + ``` #### Uninstall @@ -665,13 +665,13 @@ In order to get more insight on what your openHAB system is doing and to see occ These will tell you everything you might need to know. Execute the following command in one session or have both files separated in sessions side by side: -* Package repository based installation: +- Package repository based installation: ```shell tail -f /var/log/openhab2/openhab.log -f /var/log/openhab2/events.log ``` -* Manual installation: +- Manual installation: ```shell tail -f /opt/openhab2/userdata/logs/openhab.log -f /opt/openhab2/userdata/logs/events.log @@ -728,7 +728,8 @@ setcap 'cap_net_raw,cap_net_admin=+eip cap_net_bind_service=+ep' $(realpath /usr ### Network Sharing openHAB depends on configuration files and folders with custom content (details in [Configuration]({{base}}/configuration/index.html) articles). -Because your openHAB installation most probably is stored on a remote device, being able to easily access and modify these files from your local PC or Mac is important, therefore setting up a [Samba](https://en.wikipedia.org/wiki/Samba_(software)) network share is **highly recommended**. +Because your openHAB installation most probably is stored on a remote device, being able to easily access and modify these files from your local PC or Mac is important. +Therefore setting up a [Samba](https://en.wikipedia.org/wiki/Samba_%28software%29) network share is **highly recommended**. The [Eclipse SmartHome Designer]({{base}}/installation/designer.html) software does also depend on a mounted share to access the openHAB configuration files. @@ -753,47 +754,46 @@ Next, add the desired share configurations to the end of the file: -* Package repository based installation: - - ```ini - [openHAB2-userdata] - comment=openHAB2 userdata - path=/var/lib/openhab2 - browseable=Yes - writeable=Yes - only guest=no - public=no - create mask=0777 - directory mask=0777 - - [openHAB2-conf] - comment=openHAB2 site configuration - path=/etc/openhab2 - browseable=Yes - writeable=Yes - only guest=no - public=no - create mask=0777 - directory mask=0777 - ``` - -* Manual installation: - - ```ini - [openHAB-files] - comment=openHAB2 - path=/opt/openhab2 - browseable=Yes - writeable=Yes - only guest=no - public=no - create mask=0777 - directory mask=0777 - ``` +- Package repository based installation: + + ```ini + [openHAB2-userdata] + comment=openHAB2 userdata + path=/var/lib/openhab2 + browseable=Yes + writeable=Yes + only guest=no + public=no + create mask=0777 + directory mask=0777 + + [openHAB2-conf] + comment=openHAB2 site configuration + path=/etc/openhab2 + browseable=Yes + writeable=Yes + only guest=no + public=no + create mask=0777 + directory mask=0777 + ``` + +- Manual installation: + + ```ini + [openHAB-files] + comment=openHAB2 + path=/opt/openhab2 + browseable=Yes + writeable=Yes + only guest=no + public=no + create mask=0777 + directory mask=0777 + ``` Save and close the samba configuration file. - The shares are configured to be not open for guests nor to the public. Let's activate the "openhab" user as a samba user and set his password (e.g. "habopen"): @@ -827,8 +827,8 @@ Check the network devices manager of your local operating system to find and acc These might however not be auto-discovered. You can also manually connect: -* **On Mac OS X:** Open Finder → Go → Connect to Server: `smb://openhab@openhab-device.local` -* **On Windows:** Open Windows Explorer → Address bar: `\\openhab-device.local` → Right click a share and assign a drive letter +- **On Mac OS X:** Open Finder → Go → Connect to Server: `smb://openhab@openhab-device.local` +- **On Windows:** Open Windows Explorer → Address bar: `\\openhab-device.local` → Right click a share and assign a drive letter Be sure to use the actual host name instead of `openhab-device`. When asked, authenticate with the username "openhab" and the chosen password. diff --git a/installation/macosx.md b/installation/macosx.md index e5dacd9cb2..c1c1a71b0c 100644 --- a/installation/macosx.md +++ b/installation/macosx.md @@ -11,10 +11,10 @@ This page is structured as follows: {::options toc_levels="2..4"/} -* TOC +- TOC {:toc} -If you're unfamilar with using the Mac OS terminal, then feel free to follow the many guides on the internet. For example: +If you're unfamiliar with using the Mac OS terminal, then feel free to follow the many guides on the internet. For example: [Macworld: How to use Terminal on mac](http://www.macworld.co.uk/feature/mac-software/how-use-terminal-on-mac-3608274/) @@ -25,40 +25,40 @@ First, make sure that your system meets the [prerequisites](index.html#prerequis You have the choice to use the current stable version or the latest snapshot build: -* **Stable** - - The stable builds have undergone testing, it is the recomended version to download. - Download the latest `openhab-2.x.x.zip` [here](https://bintray.com/openhab/mvn/openhab-distro/_latestVersion). - -* **Snapshot (Unstable)** - - Snapshots are built daily, and contain the latest changes to openHAB's source code. - These changes haven't undergone the same amount of testing as the stable releases, so only use them if you **need** a new feature. - Download the latest `openhab-2.x.x-SNAPSHOT.zip` [here](https://openhab.ci.cloudbees.com/job/openHAB-Distribution). - +- **Stable** + + The stable builds have undergone testing, it is the recommended version to download. + Download the latest `openhab-2.x.x.zip` [here](https://bintray.com/openhab/mvn/openhab-distro/_latestVersion). + +- **Snapshot (Unstable)** + + Snapshots are built daily, and contain the latest changes to openHAB's source code. + These changes haven't undergone the same amount of testing as the stable releases, so only use them if you **need** a new feature. + Download the latest `openhab-2.x.x-SNAPSHOT.zip` [here](https://openhab.ci.cloudbees.com/job/openHAB-Distribution). + The following instructions are performed in a terminal window. At first launch of the terminal, you will be inside your home directory. -Choose a folder name to host your install. Be aware that the path to this folder **must not contain any spaces**. +Choose a folder name to host your install. Be aware that the path to this folder **must not contain any spaces**. The path chosen here is `openhab`. -``` +```shell mkdir ~/openhab cd ~/openhab ``` -Next, unzip the file downloaded earlier. +Next, unzip the file downloaded earlier. Assuming that you have downloaded the **stable** build to your download folder, the command will be: -```sh +```shell unzip ~/Downloads/openhab-2.x.x.zip -d . ``` Check that the zip extraction was successful by using the `ls` command in order to check the contents of the folder. -```bash +```shell user:openhab $ ls -LICENSE.TXT conf start.bat start_debug.bat userdata -addons runtime start.sh start_debug.sh +LICENSE.TXT conf start.bat start_debug.bat userdata +addons runtime start.sh start_debug.sh ``` If you see something similar to the above, then you're all set to launch openHAB for the first time. @@ -67,21 +67,21 @@ If you see something similar to the above, then you're all set to launch openHAB From inside openHAB's root directory (e.g. `~/openhab/), run openHAB's startup script by using the following command. -```bash +```shell ./start.sh ``` -The first run may take a while to process, wait until the "openhab>" prompt appears, for example: +The first run may take a while to process, wait until the "`openhab>`" prompt appears, for example: -``` +```shell_session user:openhab $ sudo ./start.sh Launching the openHAB runtime... - __ _____ ____ - ____ ____ ___ ____ / / / / | / __ ) - / __ \/ __ \/ _ \/ __ \/ /_/ / /| | / __ | -/ /_/ / /_/ / __/ / / / __ / ___ |/ /_/ / -\____/ .___/\___/_/ /_/_/ /_/_/ |_/_____/ + __ _____ ____ + ____ ____ ___ ____ / / / / | / __ ) + / __ \/ __ \/ _ \/ __ \/ /_/ / /| | / __ | +/ /_/ / /_/ / __/ / / / __ / ___ |/ /_/ / +\____/ .___/\___/_/ /_/_/ /_/_/ |_/_____/ /_/ 2.0.0 ... @@ -92,7 +92,7 @@ Hit '' or type 'system:shutdown' or 'logout' to shutdown openHAB. openhab> ``` -Without closing the terminal, open your favorite web browser and type the following url : http://localhost:8080, you should see the openHAB welcome screen, and you're all set to [using openHAB]({{base}}/tutorials/beginner/1sttimesetup.html). +Without closing the terminal, open your favorite web browser and type the following URL: [http://localhost:8080](http://localhost:8080), you should see the openHAB welcome screen, and you're all set to [using openHAB]({{base}}/tutorials/beginner/1sttimesetup.html). ![](images/Accueil_Openhab_2.png) @@ -102,34 +102,34 @@ openHAB can use a script to update to any other version, or from stable to snaps ### Versions 2.1.0 and Above -From version 2.1.0, openHAB is distributed with the update script included. -This script should be called from within openHAB's root directory. +From version 2.1.0, openHAB is distributed with the update script included. +This script should be called from within openHAB's root directory. Assuming the openHAB directory is in `~/openhab`, simply run the following commands to update to the next major version of openHAB: -```bash +```shell cd ~/openhab sudo runtime/bin/update ``` You can also specify any version as a parameter. For example, to switch back to 2.0.0: - -```bash + +```shell sudo runtime/bin/update 2.0.0 ``` -You may also change to openHAB's more frequent, but less stable snapshot builds. +You may also change to openHAB's more frequent, but less stable snapshot builds. Just append "-SNAPSHOT" to the target version, e.g.: -```bash +```shell sudo runtime/bin/update 2.2.0-SNAPSHOT ``` ### Older Versions -If you're using a version earlier than 2.1.0, then you can use the following commands in Terminal to download the script and run it. +If you're using a version earlier than 2.1.0, then you can use the following commands in Terminal to download the script and run it. Assuming the openHAB directory is in `~/openhab` simply run the following commands to update to the next major version of openHAB: -```bash +```shell cd ~/openhab sudo sh -c "$(curl -fsSL https://raw.githubusercontent.com/openhab/openhab-distro/master/distributions/openhab/src/main/resources/bin/update)" -- 2.1.0 ``` diff --git a/installation/nginx.md b/installation/nginx.md deleted file mode 100644 index 3976310ae3..0000000000 --- a/installation/nginx.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -layout: redirected -sitemap: false -redirect_to: /installation/security.html ---- - - diff --git a/installation/pine.md b/installation/pine.md index b0cc6b8524..9147d42ef8 100644 --- a/installation/pine.md +++ b/installation/pine.md @@ -9,7 +9,7 @@ title: PINE A64 The [PINE A64](https://www.pine64.org/?page_id=1194) is a young but promising single-board computers (SBC) on the market. The project started off as a [Kickstarter campaign](https://www.kickstarter.com/projects/pine64/pine-a64-first-15-64-bit-single-board-super-comput) back in December 2015. -Single Board Computer powered by Quad-Core ARM Cortex A53 64-Bit Processor. +The Pine A64 is powered by Quad-Core ARM Cortex A53 64-Bit Processor. ![Pine A64](images/pine64.png) @@ -18,6 +18,6 @@ Please visit the [official homepage](https://www.pine64.org) and [wiki](http://w ## Recommended Setup We are proud to provide a system image for the Pine A64, including the latest version of openHAB 2 and many recommended settings and useful software additions. -The image is based on the official [Ubuntu Base Image by longsleep](http://wiki.pine64.org/index.php/Pine_A64_Software_Release) and the openHABian project. +The image is based on the official [Ubuntu Base Image by longsleep](http://wiki.pine64.org/index.php/Pine_A64_Software_Release) and developed and maintained by the openHABian project. Check out more details about [openHABian, the hassle-free openHAB setup](openhabian.html). diff --git a/installation/qnap.md b/installation/qnap.md index 87cc150c1a..fc4a15f5b5 100644 --- a/installation/qnap.md +++ b/installation/qnap.md @@ -14,42 +14,49 @@ Please find all details about the openHAB package for QNAP [here](https://github ## How to install -Check that your NAS has the most recent firmware version. Follow the instructions shown if a new version is announced when opening the admin GUI. +Check that your NAS has the most recent firmware version. +Follow the instructions shown if a new version is announced when opening the admin GUI. -1. Download the QPKG from the [releases section over on GitHub](https://github.com/openhab/openhab-qnap-qpkg/releases). +1. Download the QPKG from the [releases section over on GitHub](https://github.com/openhab/openhab-qnap-qpkg/releases). -2. Create a directory for your addons, configurations and userdata, by either - * Creating a share called "openHAB2" (recommended) - * Creating a folder called "openHAB2" inside the "Public" share - * Not creating any of them and therefore using `.qpkg/openHAB2/distribution` for all data (for testing or demonstration) +2. Create a directory for your addons, configurations and userdata, by either + - Creating a share called "openHAB2" (recommended) + - Creating a folder called "openHAB2" inside the "Public" share + - Not creating any of them and therefore using `.qpkg/openHAB2/distribution` for all data (for testing or demonstration) -3. Go to your NAS's App Center and make sure you have got "JRE" (for x86-CPU based NAS) or "JRE_ARM" (for ARM-CPU based NAS) installed. If that is not the case, go to the "Developer-Tools" section of the App Center, install the appropriate version and wait for a while until the Java installation has finished. +3. Go to your NAS's App Center and make sure you have got "JRE" (for x86-CPU based NAS) or "JRE_ARM" (for ARM-CPU based NAS) installed. + If that is not the case, go to the "Developer-Tools" section of the App Center, install the appropriate version and wait for a while until the Java installation has finished. -4. Open the "Install manually" dialog in the App Center by clicking the gear-wheel on the upper-right corner of the App Center and choose the `qpkg` you have downloaded. +4. Open the "Install manually" dialog in the App Center by clicking the gear-wheel on the upper-right corner of the App Center and choose the `qpkg` you have downloaded. ![AppCenter choose](https://github.com/openhab/openhab-qnap-qpkg/raw/master/docs/QTS_4.2.0_AppCenter%20choose.png) -5. Confirm the installation +5. Confirm the installation ![AppCenter confirm](https://github.com/openhab/openhab-qnap-qpkg/raw/master/docs/QTS_4.2.0_AppCenter%20confirm.png) -6. Wait while the package is being installed +6. Wait while the package is being installed ![AppCenter installing](https://github.com/openhab/openhab-qnap-qpkg/raw/master/docs/QTS_4.2.0_AppCenter%20installing.png) -7. When finished just close the dialog and wait for a while until openHAB has completely started. This may take several minutes. +7. When finished just close the dialog and wait for a while until openHAB has completely started. + This may take several minutes. ![AppCenter finished](https://github.com/openhab/openhab-qnap-qpkg/raw/master/docs/QTS_4.2.0_AppCenter%20finished.png) -8. Access openHAB via "[http://NAS_IP_or_DNS_address:8090](#)". If the interface does not start, retry after another minute. The initial startup takes some time. +8. Access openHAB via "[http://NAS_IP_or_DNS_address:8090](#)". + If the interface does not start, retry after another minute. + The initial startup takes some time. ## How to uninstall If you want to keep configuration files, copy them to a save place outside of the openhab-path. -1. Go to the "App Center" and remove the app like any other. -2. Additionally if wanted or needed, please remove the folders "addons", "conf" and "userdata" from the your directory, eg. "openHAB2" share or "Public"/openHAB2 +1. Go to the "App Center" and remove the app like any other. + +2. Additionally if wanted or needed, please remove the folders "addons", "conf" and "userdata" from the your directory, eg. "openHAB2" share or "Public"/openHAB2 If you have installed openHAB2 to `.qpkg` (see "How to install", third option) then all files get removed automatically. ## Known issues -* Please check our issue tracker: [https://github.com/openhab/openhab-qnap-qpkg/issues](https://github.com/openhab/openhab-qnap-qpkg/issues) + +- Please check our issue tracker: [https://github.com/openhab/openhab-qnap-qpkg/issues](https://github.com/openhab/openhab-qnap-qpkg/issues) diff --git a/installation/rasppi.md b/installation/rasppi.md index 6afa97190d..ede946abf8 100644 --- a/installation/rasppi.md +++ b/installation/rasppi.md @@ -17,16 +17,16 @@ These including the official [raspberrypi.org help articles](https://www.raspber Recommendations for a ["headless"](https://en.wikipedia.org/wiki/Headless_computer) hardware setup: -* [Raspberry Pi 2 or newer](https://en.wikipedia.org/wiki/Raspberry_Pi#Specifications), compare your existing device [here](https://en.wikipedia.org/wiki/Raspberry_Pi#Connectors) if you are unsure. -* SD card (16GB or more to support [wear-leveling](https://en.wikipedia.org/wiki/Wear_leveling)) -* Steady power supply -* Ethernet connection -* *No connected display or keyboard needed* +- [Raspberry Pi 2 or newer](https://en.wikipedia.org/wiki/Raspberry_Pi#Specifications), compare your existing device [here](https://en.wikipedia.org/wiki/Raspberry_Pi#Connectors) if you are unsure. +- SD card (16GB or more to support [wear-leveling](https://en.wikipedia.org/wiki/Wear_leveling)) +- Steady power supply +- Ethernet connection +- *No connected display or keyboard needed* ## Recommended Setup We are proud to provide a **preconfigured image** for the Raspberry Pi, with the latest build of openHAB 2 and many useful software components (like Samba, Grafana or Mosquitto) as optional setup steps. -**openHABian** is based on Raspbian and under constant improvement. +The image provided by the **openHABian** projects is based on Raspbian and under constant improvement. Check out more details about [openHABian, the hassle-free openHAB setup](openhabian.html). @@ -39,7 +39,7 @@ You may choose the "Lite" version. **Attention:** As of the November 2016 release, Raspbian has the SSH server disabled by default. You will have to enable it manually. -For headless setup, SSH can be enabled by placing a file named 'ssh', without any extension, onto the boot partition of the SD card. +For headless setup, SSH can be enabled by placing a file named "ssh", without any extension, onto the boot partition of the SD card. **Connecting:** Get your SD card and network cable plugged in and power up. @@ -52,11 +52,11 @@ If you are not able to connect, check your routers web frontend for newly connec Connected via SSH, execute the Raspbian configuration menu by running `sudo raspi-config`. Go through the following steps: -* Expand the file system -* Change your password -* (Change the host name if you wish, e.g. "openhabpi") -* From the advanced menu, change the memory split for the GPU to "16" -* Restart +- Expand the file system +- Change your password +- (Change the host name if you wish, e.g. "openhabpi") +- From the advanced menu, change the memory split for the GPU to "16" +- Restart As a good practice, run a full upgrade and install packages you like or need (a set of helpful packages is given as an example): @@ -72,9 +72,9 @@ Raspbian in the latest full version already includes Oracle Java 8. However, at the time of this writing, the installed revision is lower than the [recommended](index.html#prerequisites). Raspbian Lite comes without Java to begin with. -Please refer to the Linux article for instructions on [how to install the latest revision of Oracle Java 8](linux.html). +Please refer to the Linux article for instructions on [how to install the latest Java 8 revision](linux.html). **Installation:** Finally install openHAB on your Raspberry Pi, just as it is described in the [openHAB 2 on Linux](linux.html) article: -* [Package Repository based Installation on Linux](linux.html#package-repository-installation) +- [Package Repository based Installation on Linux](linux.html#package-repository-installation) diff --git a/installation/security.md b/installation/security.md index de0f104416..262cbae132 100644 --- a/installation/security.md +++ b/installation/security.md @@ -9,12 +9,12 @@ title: Securing Communication and Access openHAB has mainly two ways to be accessed: -1. Through the command line console, which is done through ssh and thus always authenticated and encrypted. You will find all details about this in the [Console documentation](/administration/console). +1. Through the command line console, which is done through SSH and thus always authenticated and encrypted. You will find all details about this in the [Console documentation](/administration/console). 2. Through HTTP(S), which we will look at in the following. {::options toc_levels="2..3"/} -* TOC +- TOC {:toc} ## Encrypted Communication @@ -37,12 +37,13 @@ Note that on slow hardware, this certificate generation can take up to several m openHAB does not (yet) support restricting access through HTTP(S) for certain users - there is no authentication in place, nor is there a limitation of functionality or information that different users can access. -**It is therefore vitally important that you MUST NOT directly expose your openHAB instance to the Internet (e.g. by opening a port in your firewall)!** +**Security Warning:** +It is vitally important that you MUST NOT directly expose your openHAB instance to the Internet (e.g. by opening a port in your firewall)! If you want to limit access to only certain network interfaces, you can do so in the file `$OPENHAB_USERDATA/etc/org.ops4j.pax.web.cfg` by editing the `org.ops4j.pax.web.listening.addresses` parameter. Setting it to -``` +```conf org.ops4j.pax.web.listening.addresses = 127.0.0.1 ``` @@ -70,7 +71,7 @@ The simplest way to get hold of such an openHAB Cloud is to register an account ### Running openHAB Behind a Reverse Proxy A reverse proxy simply directs client requests to the appropriate server. -This means you can proxy connections to *http://mydomain_or_myip* to your openHAB runtime. +This means you can proxy connections to `http://mydomain_or_myip` to your openHAB runtime. You just have to **replace *mydomain_or_myip*** with either an **internal or external IP** (e.g. xx.xx.xx.xx) or a **domain** if you own one that links to the external IP of openHAB (e.g. openhab.mydomain.tld). Running openHAB behind a reverse proxy allows you to access your openHAB runtime via port 80 (HTTP) and 443 (HTTPS). @@ -80,27 +81,27 @@ The good news is that [openHABian](openhabian) already offers the possibility to **Table of Content:** -* [Setting up NGINX](#nginx-setup) - * [Installation](#nginx-setup-install) - * [Basic Configuration](#nginx-setup-config) -* [Authentication with NGINX](#nginx-auth) - * [Creating the First User](#nginx-auth-user) - * [Referencing the File in the NGINX Configuration](#nginx-auth-file) - * [Adding or Removing users](#nginx-auth-users) -* [Making Exceptions for Specific IP addresses](#nginx-satisfy) -* [Setting up a Domain](#nginx-domain) -* [Enabling HTTPS](#nginx-https) -* [Using OpenSSL to Generate Self-Signed Certificates](#nginx-openssl) - * [Adding the Certificates to Your Proxy Server](#nginx-openssl-add) -* [Using Let's Encrypt to Generate Trusted Certificates](#nginx-letsencrypt) - * [Setting up the NGINX Proxy Server to Handle the Certificate Generation Procedure](#nginx-letsencrypt-generation) - * [Using Certbot](#nginx-letsencrypt-certbot) - * [Adding the Certificates to Your Proxy Server](#nginx-letsencrypt-add) -* [Setting Your NGINX Server to Listen to the HTTPS Port](#nginx-https-listen) -* [Redirecting HTTP Traffic to HTTPS](#nginx-httpredirect) -* [Putting it All Together](#nginx-summary) -* [Additional HTTPS Security](#nginx-https-security) -* [Further Reading](#nginx-further-reading) +- [Setting up NGINX](#nginx-setup) + - [Installation](#nginx-setup-install) + - [Basic Configuration](#nginx-setup-config) +- [Authentication with NGINX](#nginx-auth) + - [Creating the First User](#nginx-auth-user) + - [Referencing the File in the NGINX Configuration](#nginx-auth-file) + - [Adding or Removing users](#nginx-auth-users) +- [Making Exceptions for Specific IP addresses](#nginx-satisfy) +- [Setting up a Domain](#nginx-domain) +- [Enabling HTTPS](#nginx-https) +- [Using OpenSSL to Generate Self-Signed Certificates](#nginx-openssl) + - [Adding the Certificates to Your Proxy Server](#nginx-openssl-add) +- [Using Let's Encrypt to Generate Trusted Certificates](#nginx-letsencrypt) + - [Setting up the NGINX Proxy Server to Handle the Certificate Generation Procedure](#nginx-letsencrypt-generation) + - [Using Certbot](#nginx-letsencrypt-certbot) + - [Adding the Certificates to Your Proxy Server](#nginx-letsencrypt-add) +- [Setting Your NGINX Server to Listen to the HTTPS Port](#nginx-https-listen) +- [Redirecting HTTP Traffic to HTTPS](#nginx-httpredirect) +- [Putting it All Together](#nginx-summary) +- [Additional HTTPS Security](#nginx-https-security) +- [Further Reading](#nginx-further-reading) {: #nginx-setup} #### Setting up NGINX @@ -116,7 +117,7 @@ NGINX runs as a service in most Linux distributions, installation should be as s sudo apt-get update && sudo apt-get install nginx ``` -Once installed, you can test to see if the service is running correctly by going to *http://mydomain_or_myip*, you should see the default "Welcome to nginx" page. +Once installed, you can test to see if the service is running correctly by going to `http://mydomain_or_myip`, you should see the default "Welcome to nginx" page. If you don't, you may need to check your firewall or ports and check if port 80 (and 443 for HTTPS later) is not blocked and that services can use it. {: #nginx-setup-config} @@ -126,20 +127,20 @@ NGINX configures the server when it starts up based on configuration files. The location of the default setup is `/etc/nginx/sites-enabled/default`. To allow NGINX to proxy openHAB, you need to change this file (make a backup of it in a different folder first). The recommended configuration below assumes that you run the reverse proxy on the same machine as your openHAB runtime. -If this doesn't fit for you, you just have to replace `proxy_pass http://localhost:8080/` by your openHAB runtime hostname (such as *http://youropenhabhostname:8080/*). +If this doesn't fit for you, you just have to replace `proxy_pass http://localhost:8080/` by your openHAB runtime hostname (such as `http://youropenhabhostname:8080/`). ```nginx server { - listen 80; - server_name mydomain_or_myip; - - location / { - proxy_pass http://localhost:8080/; - proxy_set_header Host $http_host; - proxy_set_header X-Real-IP $remote_addr; - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; - proxy_set_header X-Forwarded-Proto $scheme; - } + listen 80; + server_name mydomain_or_myip; + + location / { + proxy_pass http://localhost:8080/; + proxy_set_header Host $http_host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + } } ``` @@ -163,7 +164,7 @@ If you see that the test is successful, you can restart the NGINX service with.. sudo service nginx restart ``` -...and then go to *http://mydomain_or_myip* to see your openHAB server. +...and then go to `http://mydomain_or_myip` to see your openHAB server. {: #nginx-auth} #### Authentication with NGINX @@ -199,8 +200,8 @@ Now the configuration file (`/etc/nginx/sites-enabled/openhab`) needs to be edit Open the configuration file and **add** the following lines underneath the proxy_* settings: ```nginx - auth_basic "Username and Password Required"; - auth_basic_user_file /etc/nginx/.htpasswd; + auth_basic "Username and Password Required"; + auth_basic_user_file /etc/nginx/.htpasswd; ``` Once done, **test and restart your NGINX service** and authentication should now be enabled on your server! @@ -230,10 +231,10 @@ In these cases NGINX can use the `satisfy any` directive followed by `allow` and These lines are placed in the `location{}` block. For example, by adding the lines: ```nginx - satisfy any; - allow 192.168.0.1/24; - allow 127.0.0.1; - deny all; + satisfy any; + allow 192.168.0.1/24; + allow 127.0.0.1; + deny all; ``` NGINX will allow anyone within the 192.168.0.1/24 range **and** the localhost to connect without a password. @@ -286,7 +287,9 @@ Common Name (e.g. server FQDN or YOUR name) []: xx.xx.xx.xx {: #nginx-openssl-add} ##### Adding the Certificates to Your Proxy Server -The certificate and key should have been placed in `/etc/ssl/`. NGINX needs to be told where these files are and then enable the reverse proxy to direct HTTPS traffic. In the NGINX configuration, place the following underneath your server_name variable: +The certificate and key should have been placed in `/etc/ssl/`. +NGINX needs to be told where these files are and then enable the reverse proxy to direct HTTPS traffic. +In the NGINX configuration, place the following underneath your `server_name` variable: ```nginx ssl_certificate /etc/ssl/openhab.crt; @@ -303,7 +306,8 @@ Let's Encrypt is a service that allows anyone with a valid domain to automatical {: #nginx-letsencrypt-generation} ##### Setting up the NGINX Proxy Server to Handle the Certificate Generation Procedure -Let's Encrypt needs to validate that the server has control of the domain, the most simple way of doing this is using a **webroot plugin** to place a file on the server, and then access it using a specific url: */.well-known/acme-challenge*. +Let's Encrypt needs to validate that the server has control of the domain. +The simplest way of doing this is using a **webroot plugin** to place a file on the server, and then access it using a specific url: */.well-known/acme-challenge*. Since the proxy only forwards traffic to the openHAB server, the server needs to be told to handle requests at this address differently. First, **create a directory** that Certbot can be given access to: @@ -350,11 +354,11 @@ In the NGINX configuration, place the following underneath your server_name vari Regardless of the option you choose, make sure you change the port to listen in on HTTPS traffic. ```nginx - listen 443 ssl; + listen 443 ssl; ``` After restarting NGINX service, you will be using a valid HTTPS certificate. -You can check by going to https://mydomain_or_myip and confirming with your browser that you have a valid certificate. +You can check by going to `https://mydomain_or_myip` and confirming with your browser that you have a valid certificate. **These certificates expire within a few months** so it is important to run the updater in a cron expression (and also restart NGINX) as explained in the Certbot setup instructions. If you want to keep hold of a HTTP server for some reason, just add `listen 80;` and remove the Strict-Transport-Security line. @@ -366,9 +370,9 @@ This will essentially replace the HTTP url with the HTTPS version! ```nginx server { - listen 80; - server_name mydomain_or_myip; - return 301 https://$server_name$request_uri; + listen 80; + server_name mydomain_or_myip; + return 301 https://$server_name$request_uri; } ``` @@ -379,36 +383,36 @@ After following all the steps on this page, you *should* have a NGINX server con ```nginx server { - listen 80; - server_name mydomain_or_myip; - return 301 https://$server_name$request_uri; + listen 80; + server_name mydomain_or_myip; + return 301 https://$server_name$request_uri; } server { - listen 443 ssl; - server_name mydomain_or_myip; - - ssl_certificate /etc/letsencrypt/live/mydomain/fullchain.pem; # or /etc/ssl/openhab.crt - ssl_certificate_key /etc/letsencrypt/live/mydomain/privkey.pem; # or /etc/ssl/openhab.key - add_header Strict-Transport-Security "max-age=31536000"; # Remove if using self-signed and are having trouble. - - location / { - proxy_pass http://localhost:8080/; - proxy_set_header Host $http_host; - proxy_set_header X-Real-IP $remote_addr; - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; - proxy_set_header X-Forwarded-Proto $scheme; - satisfy any; - allow 192.168.0.1/24; - allow 127.0.0.1; - deny all; - auth_basic "Username and Password Required"; - auth_basic_user_file /etc/nginx/.htpasswd; - } - - #### When using Let's Encrypt Only #### - location /.well-known/acme-challenge/ { - root /var/www/mydomain; - } + listen 443 ssl; + server_name mydomain_or_myip; + + ssl_certificate /etc/letsencrypt/live/mydomain/fullchain.pem; # or /etc/ssl/openhab.crt + ssl_certificate_key /etc/letsencrypt/live/mydomain/privkey.pem; # or /etc/ssl/openhab.key + add_header Strict-Transport-Security "max-age=31536000"; # Remove if using self-signed and are having trouble. + + location / { + proxy_pass http://localhost:8080/; + proxy_set_header Host $http_host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + satisfy any; + allow 192.168.0.1/24; + allow 127.0.0.1; + deny all; + auth_basic "Username and Password Required"; + auth_basic_user_file /etc/nginx/.htpasswd; + } + + #### When using Let's Encrypt Only #### + location /.well-known/acme-challenge/ { + root /var/www/mydomain; + } } ``` @@ -430,13 +434,13 @@ Now we can configure NGINX to use this key, as well as telling the client to use All of these settings are customisable, but make sure you [read up on](http://nginx.org/en/docs/http/configuring_https_servers.html) what these do first before changing them: ```nginx - ssl_protocols TLSv1 TLSv1.1 TLSv1.2; - ssl_prefer_server_ciphers on; - ssl_dhparam /etc/nginx/ssl/dhparam.pem; - ssl_ciphers ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-RSA-AES256-SHA:HIGH:!aNULL:!eNULL:!LOW:!3DES:!MD5:!EXP:!CBC:!EDH:!kEDH:!PSK:!SRP:!kECDH; - ssl_session_timeout 1d; - ssl_session_cache shared:SSL:10m; - keepalive_timeout 70; + ssl_protocols TLSv1 TLSv1.1 TLSv1.2; + ssl_prefer_server_ciphers on; + ssl_dhparam /etc/nginx/ssl/dhparam.pem; + ssl_ciphers ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-RSA-AES256-SHA:HIGH:!aNULL:!eNULL:!LOW:!3DES:!MD5:!EXP:!CBC:!EDH:!kEDH:!PSK:!SRP:!kECDH; + ssl_session_timeout 1d; + ssl_session_cache shared:SSL:10m; + keepalive_timeout 70; ``` Feel free to test the new configuration again on [SSL Labs](https://www.ssllabs.com/ssltest/). @@ -448,6 +452,6 @@ If you're achieving A or A+ here, then your client-openHAB communication is very The setup above is a suggestion for high compatibility with an A+ rating at the time of writing, however flaws in these settings (particularly the cyphers) may become known overtime. The following articles may be useful when understanding and changing these settings. - - [Better Crypto](https://bettercrypto.org/) - - [SSL Labs - Best Practices](https://www.ssllabs.com/projects/best-practices/) - - [Hynek Schlawack - Hardening Your Web Server’s SSL Ciphers](https://hynek.me/articles/hardening-your-web-servers-ssl-ciphers/) +- [Better Crypto](https://bettercrypto.org/) +- [SSL Labs - Best Practices](https://www.ssllabs.com/projects/best-practices/) +- [Hynek Schlawack - Hardening Your Web Server’s SSL Ciphers](https://hynek.me/articles/hardening-your-web-servers-ssl-ciphers/) diff --git a/installation/synology.md b/installation/synology.md index 3caf12031f..2f11e3c659 100644 --- a/installation/synology.md +++ b/installation/synology.md @@ -12,8 +12,12 @@ We are proud to be able to provide an [openHAB Synology package](https://github. ## Prerequisite - Install Java -Current releases of openHAB require Oracle Java due to the generation of certificates based on [EC](https://en.wikipedia.org/wiki/Elliptic_curve_cryptography) which is not available in free Java implementations. If you see the following error you are likely using OpenJDK: - java.security.NoSuchAlgorithmException: EC KeyPairGenerator not available +Current releases of openHAB require Oracle Java due to the generation of certificates based on [EC](https://en.wikipedia.org/wiki/Elliptic_curve_cryptography) which is not available in free Java implementations. +If you see the following error you are likely using OpenJDK: + +```text +java.security.NoSuchAlgorithmException: EC KeyPairGenerator not available +``` The easiest way to install Java is to include the [PC-Loadletter Repo](http://packages.pcloadletter.co.uk/). Download [Java8 SE](http://www.oracle.com/technetwork/java/embedded/index.html) [(latest ARMv6)](http://www.oracle.com/technetwork/java/embedded/embedded-se/downloads/javase-embedded-downloads-2209751.html) [(Java Cryptography Extension if required)](http://www.oracle.com/technetwork/java/javase/downloads/jce8-download-2133166.html) and put them in the public folder of your NAS. Then start the installation of Java8 SE. @@ -22,11 +26,11 @@ The easiest way to install Java is to include the [PC-Loadletter Repo](http://pa Download the latest SPK package: [Releases](https://github.com/openhab/openhab-syno-spk/releases) The SPK is a wrapper to download the latest openHAB release and does not contain openHAB itself. -1. Login and open the DiskStation Manager. -2. Go to Main Menu → Package Center. -3. Click on the Manual Install button. -4. Click "Choose File" and select the previously downloaded openHAB `.spk` file. -5. On the confirmation page: If you would like the package to run immediately after installation, make sure the box next to "Run after Installation" is ticked. +1. Login and open the DiskStation Manager. +2. Go to Main Menu → Package Center. +3. Click on the Manual Install button. +4. Click "Choose File" and select the previously downloaded openHAB `.spk` file. +5. On the confirmation page: If you would like the package to run immediately after installation, make sure the box next to "Run after Installation" is ticked. 6. Click Apply to start installation. If your NAS cannot connect to the internet, the installer will tell you to download and place the ZIP file into your NAS public folder. @@ -35,7 +39,7 @@ If your NAS cannot connect to the internet, the installer will tell you to downl The configuration files are located at: -``` +```conf /volume1/@appstore/openHAB2/userdata/config ``` diff --git a/installation/windows.md b/installation/windows.md index c79e216b40..14da7f4176 100644 --- a/installation/windows.md +++ b/installation/windows.md @@ -13,7 +13,7 @@ This page is structured as follows: {::options toc_levels="2..4"/} -* TOC +- TOC {:toc} ## Prerequisites @@ -23,7 +23,7 @@ First, be sure to check that your system has the necessary [prerequisites]({{bas Add the `JAVA_HOME` System Environment Variable in Windows. Navigate to: -* Control Panel ➡️ System and Security ➡️ System ➡️ Advanced System Settings ➡️ Environment Variables ➡️ System Variables +- Control Panel ➡️ System and Security ➡️ System ➡️ Advanced System Settings ➡️ Environment Variables ➡️ System Variables Create a New System Variable based on your Java installation directory: @@ -64,7 +64,6 @@ Assuming a successful install, you will now have various folders inside `C:\open | Userdata like rrd4j databases | `C:\openHAB2\userdata` | | Service configuration | `C:\openHAB2\userdata\etc` | - ## Backup Make sure that you make regular backups of the **conf** and **userdata** folders, you can zip and unzip these folders too and from openHAB installations (even across most versions). @@ -76,32 +75,35 @@ Which can be used any time after a failure. There is currently no automatic update script for Windows. To update manually, download a later version of the openHAB distribution zip file and follow these steps: -1. Stop the openHAB process if it is currently running. -2. Backup openHAB as described above. -3. Delete the following files and folders from your existing install: - - `userdata\etc\all.policy` - - `userdata\etc\branding.properties` - - `userdata\etc\branding-ssh.properties` - - `userdata\etc\config.properties` - - `userdata\etc\custom.properties` - - `userdata\etc\distribution.info` - - `userdata\etc\jre.properties` - - `userdata\etc\org.ops4j.pax.url.mvn.cfg` - - `userdata\etc\profile.cfg` - - `userdata\etc\startup.properties` - - `userdata\etc\version.properties` - - Any file in `userdata\etc` that starts with `org.apache.karaf` - - The `userdata\cache` folder - - The `userdata\tmp` folder - - The `runtime` folder -4. Copy and paste the contents of the zip file over your existing install, when prompted **do not overwrite existing files** +1. Stop the openHAB process if it is currently running. + +2. Backup openHAB as described above. + +3. Delete the following files and folders from your existing install: + - `userdata\etc\all.policy` + - `userdata\etc\branding.properties` + - `userdata\etc\branding-ssh.properties` + - `userdata\etc\config.properties` + - `userdata\etc\custom.properties` + - `userdata\etc\distribution.info` + - `userdata\etc\jre.properties` + - `userdata\etc\org.ops4j.pax.url.mvn.cfg` + - `userdata\etc\profile.cfg` + - `userdata\etc\startup.properties` + - `userdata\etc\version.properties` + - Any file in `userdata\etc` that starts with `org.apache.karaf` + - The `userdata\cache` folder + - The `userdata\tmp` folder + - The `runtime` folder + +4. Copy and paste the contents of the zip file over your existing install, when prompted **do not overwrite existing files** ## Starting openHAB as a Service By installing the openHAB process as a service in Windows, you can: -* Launch it automatically upon system startup -* Run it in the background +- Launch it automatically upon system startup +- Run it in the background **Windows Service Installation Steps** @@ -119,14 +121,14 @@ By installing the openHAB process as a service in Windows, you can: 4. Update the newly created `C:\openHAB2\userdata\etc\openHAB2-wrapper.conf` to include all necessary parameters. - * Copy all the config text from the below section and paste it in your `openHAB2-wrapper.conf`, replacing all existing content. - * Adapt the first entry (`OPENHAB_HOME`) to match your openHAB installation directory. + - Copy all the config text from the below section and paste it in your `openHAB2-wrapper.conf`, replacing all existing content. + - Adapt the first entry (`OPENHAB_HOME`) to match your openHAB installation directory. ```conf #******************************************************* # openHAB2-wrapper.conf for Windows Service Installation #******************************************************* - + # openHAB installation dir (Adapt this first setting to your system) set.default.OPENHAB_HOME=C:\openHAB2 @@ -203,22 +205,29 @@ By installing the openHAB process as a service in Windows, you can: 6. Your openHAB Windows service is now installed and running. Validate proper operations by: - * Browsing to [http://localhost:8080](http://localhost:8080) - * Verifying that the Windows Service is running and set to Automatic Startup type. - Use `services.msc` and find the `openHAB2` service. - ![Windows Service](images/Windows_Service.jpg) - * Logging in with an SSH client to the console (see info below) + - Browsing to [http://localhost:8080](http://localhost:8080) + + - Verifying that the Windows Service is running and set to Automatic Startup type. + Use `services.msc` and find the `openHAB2` service. + + ![Windows Service](images/Windows_Service.jpg) + + - Logging in with an SSH client to the console (see info below) ### Connecting to the openHAB console -* Install an SSH client application, e.g., [Putty](https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html), [KiTTY](http://kitty.9bis.net/) or [Xshell 5](https://www.netsarang.com/products/xsh_overview.html) -* Setup a session with the following parameters: - * Host: 127.0.0.1 - * Port: 8101 - * Username: `openhab` - * Password: `habopen` +- Install an SSH client application, e.g., [Putty](https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html), [KiTTY](http://kitty.9bis.net/) or [Xshell 5](https://www.netsarang.com/products/xsh_overview.html) + +- Setup a session with the following parameters: + - Host: 127.0.0.1 + - Port: 8101 + - Username: `openhab` + - Password: `habopen` ![SSH Connection 1](images/SSH_Connection_1.jpg) + ![SSH Connection 2](images/SSH_Connection_2.jpg) + ![SSH Connection 3](images/SSH_Connection_3.jpg) + ![SSH Connection 4](images/SSH_Connection_4.jpg) diff --git a/package.json b/package.json index b1e548ee36..d49f6f3da9 100644 --- a/package.json +++ b/package.json @@ -1,22 +1,23 @@ { "name": "openhab-docs", "version": "0.0.0", - "description": "(this npm package file is currently only used for remark-lint)", - "//": "", - "//": "A few usage notes:", - "//": "remark-lint is a Linter for Markdown files. With this file in place", - "//": "you can check all *.md files against the Markdown Style Guide of", - "//": "this project.", - "//": "", - "//": "Before you can start you need to install Node.js. Afterwards execute", - "//": "'npm install' to install all dependancies as defined in this file.", - "//": "The style check can be executed in the following ways:", - "//": " 1. From the console: 'npm run-script lint-md'", - "//": " 2. Inside the Atom editor with the linter-markdown package:", - "//": " https://atom.io/packages/linter-markdown", - "//": "", + "description": "(this package file is currently only used for remark-lint)", + "// 01": "", + "// 02": "A few usage notes: ", + "// 03": "remark-lint is a linter for markdown files. With this file in ", + "// 04": "place you can check all *.md files against the Style Guide of ", + "// 05": "this project. ", + "// 06": " ", + "// 07": "First install Node.js. Afterwards run 'npm install' inside this ", + "// 08": "folder to install all dependencies as defined in this file. ", + "// 09": " ", + "// 10": "The style check can be executed in the following ways: ", + "// 11": " 1. From the console: 'npm run-script lint-md' ", + "// 12": " 2. Inside the Atom editor with the linter-markdown package: ", + "// 13": " https://atom.io/packages/linter-markdown ", + "// 14": "", "main": "index.html", - "license" : "EPL-1.0", + "license": "EPL-1.0", "repository": { "type": "git", "url": "git+https://github.com/openhab/openhab-docs.git" @@ -26,20 +27,25 @@ }, "homepage": "https://github.com/openhab/openhab-docs#readme", "scripts": { - "lint-md": "remark ." + "lint-md": "remark .", + "lint-test": "remark styleguide.md" }, "dependencies": { "remark-cli": "^3.0.1", - "remark-preset-lint-consistent": "^2.0.0", - "remark-preset-lint-markdown-style-guide": "^1.0.0", - "remark-preset-lint-recommended": "^2.0.0", + "remark-lint-blockquote-indentation": "^1.0.0", "remark-lint-code-block-style": "^1.0.0", "remark-lint-fenced-code-flag": "^1.0.0", "remark-lint-list-item-indent": "^1.0.0", "remark-lint-maximum-line-length": "^1.0.0", + "remark-lint-no-blockquote-without-caret": "^1.0.0", "remark-lint-no-missing-blank-lines": "^1.0.0", "remark-lint-no-tabs": "^1.0.0", - "remark-lint-unordered-list-marker-style": "^1.0.0" + "remark-lint-ordered-list-marker-value": "^1.0.0", + "remark-lint-table-pipe-alignment": "^1.0.0", + "remark-lint-unordered-list-marker-style": "^1.0.0", + "remark-preset-lint-consistent": "^2.0.0", + "remark-preset-lint-markdown-style-guide": "^1.0.0", + "remark-preset-lint-recommended": "^2.0.0" }, "remarkConfig": { "plugins": [ @@ -59,16 +65,28 @@ "remark-lint-list-item-indent", "mixed" ], + [ + "remark-lint-blockquote-indentation", + 2 + ], [ "remark-lint-maximum-line-length", 240 ], + [ + "remark-lint-no-blockquote-without-caret", + true + ], [ "remark-lint-no-missing-blank-lines", { "exceptTightLists": true } ], + [ + "remark-lint-no-tabs", + true + ], [ "remark-lint-code-block-style", "fenced" @@ -78,8 +96,12 @@ true ], [ - "remark-lint-no-tabs", - true + "remark-lint-ordered-list-marker-value", + "ordered" + ], + [ + "remark-lint-table-pipe-alignment", + false ], [ "remark-lint-unordered-list-marker-style", diff --git a/styleguide.md b/styleguide.md new file mode 100644 index 0000000000..259678119d --- /dev/null +++ b/styleguide.md @@ -0,0 +1,27 @@ +--- +layout: documentation +title: openhab-docs Markdown StyleGuide +--- + +{% include base.html %} + +# openhab-docs Markdown StyleGuide + +An ordered list: + +1. Some text +2. Some more text + +An unordered list: + +- Some text +- Some more text + +An unordered loose list (applied if bigger or with nested lists): + +- Some text + - An indented item, making the list "loose" + +- Some more text + +- And even more text that could also strech over multiple lines