Documenting openHAB 2

Great starting point, thank you very much! I will try to contribute.

1 Like

Never realized there was an online editor. Gonna try it from my phone. I might be able to do more quick fixes that way while I’m on the go.

Here is a quick step-by-step I used to get going. I agree it is complicated but I do understand why these steps are necessary. These are taken from some notes I made and I really haven’t kept up. There may be errors or omissions. Note that this is really only necessary for major updates like the creation of a new document or major structural changes. For quick fixes use the online editor as @ThomDietrich described.

  1. You must have a GitHub account.

  2. Once logged in click on your icon in the upper right and select settings.

  3. If you have ssh set up (on windows this would be putty tools installed and pagent running with an ssh key loaded) add your ssh public key under SSH and GPG Keys. If not, generate a “Personal Access Token”. You need one or the other set up to interact with Github from the command line. On Windows you could also get the Github Client program but I have not had good experiences with it.

  4. Navigate to and press the “Fork” button at the top. This will give you your very own version to play with.

  5. Clone your Fork to your local machine.

  6. Add the original repo as the upstream with the command: git remote add upstream NOTE: use the http address if you did not upload an ssh key

  7. Checkout the gh-pages branch with the command: git checkout gh-pages

  8. Merge the changes from the upstream with your fork with the command: git merge upstream/gh-pages

  9. Create a new branch for the one issue you want to work on with the command: git checkout -b <name>

  10. Push the branch to github using the command git push origin docker

  11. Make your changes.

  12. As you go, add and commit changes with the commands git add . and git commit -m "message"

  13. When your changes are ready, go to the github page for your fork and create a PR. Make sure that the openhab/openhab-docs and appropriate branch is on the left and your new branch is selected on the right.

  14. Make sure to reference the Issue in your comment. Closes issue #XXX

  15. Additional commits can be made to the PR by making the changes locally to your branch and pushing the commits.

  16. you can work on more than one issue at a time by working on each one in a separate branch.

  17. Before creating a new branch, make sure to do steps 7 and 8 before creating a new branch to work on

Useful page:

When working with the docs, you can serve up the web pages as they will appear by changing directory to the source files and run jekyll serve and browse to http://localhost:4000/.

NOTE: The jekyll that came with Ubuntu as of a few months ago is not new enough and messes up the code blocks. Install the most recent version is possible.


Ok, I started slowly… will continue later on today and during the weekend

I made my first PR: for doc :

I hope that I did this correctly :slight_smile: I will contribute more stuff in the quick fixes soon also.

Edit: Oops… I just saw that @Benjy had already created a PR #240 for this document also :frowning: (i need to get more experience with github…)

1 Like

Oh no :disappointed_relieved: Maybe you can comment on his PR?
*teacher mode on* That’s why one normally first claims an Issue *teacher mode off* :blush:

Thanks for your help!!!

1 Like

Sorry Mr Dietrich :stuck_out_tongue:

But sorry @Dim ! I should have mentioned it!

1 Like

It was my bad. The PR info is online… I should have seen it :slight_smile:
I will comment on yours soon
For now, I got excited with something new here:

So I will tackle documentation in a bit :blush:

@ThomDietrich & @Benjy : I created a new PR for the windows installation instructions here: (view)

I also found a small bug with the service wrapper.

The java classpath in the default file that is created by the wrapper:install command is wrong (points to %KARAF_BASE% while it should be pointing to %KARAF_HOME%)

This is correct:*.jar

FYI karaf base and home should be the same by most of the time. Karaf home variable is used only when one karaf installation serves multiple processes. Wrapper script points to boot/main class which will not be present in children instances.
Even if its not used in OH better dont change it. :slight_smile:
// ok, after checking

OH2 actually uses that.

Thank you @splatch for the reply. I need some help here because I am stuck (I am trying to create a doc section on windows service installation steps)

I think that the problem is that the Karaf service wrapper installation does not take this directory layout file into account.

For example, if I execute:

openhab> feature:install service-wrapper
openhab> wrapper:install --name "openHAB2" --display "openHAB2" --description "openHAB 2 Service"
Creating missing directory: C:\openHAB2\userdata\bin
Creating file: C:\openHAB2\userdata\bin\openHAB2-wrapper.exe
Creating file: C:\openHAB2\userdata\etc\openHAB2-wrapper.conf
Creating file: C:\openHAB2\userdata\bin\openHAB2-service.bat
Creating missing directory: C:\openHAB2\userdata\lib\wrapper
Creating file: C:\openHAB2\userdata\lib\wrapper\wrapper.dll
Creating file: C:\openHAB2\userdata\lib\wrapper\karaf-wrapper.jar
Creating file: C:\openHAB2\userdata\lib\wrapper\karaf-wrapper-main.jar

Setup complete.  You may wish to tweak the JVM properties in the wrapper configuration file:
before installing and starting the service.

MS Windows system detected:
To install the service, run:
  C:> C:\openHAB2\userdata\bin\openHAB2-service.bat install

Once installed, to start the service run:
  C:> net start "openHAB2"

Once running, to stop the service run:
  C:> net stop "openHAB2"

Once stopped, to remove the installed the service run:
  C:> C:\openHAB2\userdata\bin\openHAB2-service.bat remove


The C:\openHAB2\userdata\etc\openHAB2-wrapper.conf has the following lines:

# Wrapper Properties
set.default.JAVA_HOME=C:\Program Files\Java\jdk1.8.0_121

# Java Application

If I try to run C:> C:\openHAB2\userdata\bin\openHAB2-service.bat run, I get the following error:

jvm 1    | Error: Could not find or load main class org.apache.karaf.wrapper.internal.service.Main

The org.apache.karaf.main-4.0.8.jar is in C:\openHAB2\runtime\lib\boot

If I change*.jar to*.jar, the script runs:

c:\openHAB2\userdata\bin>openHAB2-service.bat run
wrapper  | --> Wrapper Started as Console
wrapper  | Launching a JVM...
jvm 1    | Wrapper (Version 3.2.3)
jvm 1    |   Copyright 1999-2006 Tanuki Software, Inc.  All Rights Reserved.
jvm 1    |
jvm 1    | Jan 25, 2017 7:40:24 AM org.apache.karaf.main.lock.SimpleFileLock lock
jvm 1    | INFO: Trying to lock C:\openHAB2\userdata\tmp\lock
jvm 1    | Jan 25, 2017 7:40:24 AM org.apache.karaf.main.lock.SimpleFileLock lock
jvm 1    | INFO: Lock acquired
jvm 1    | Jan 25, 2017 7:40:24 AM org.apache.karaf.main.Main$KarafLockCallback lockAquired
jvm 1    | INFO: Lock acquired. Setting startlevel to 100

but none of the environment variables of openHAB 2 are taken into account… so the application does not work

To fix this, I need to modify (significantly) the C:\openHAB2\userdata\etc\openHAB2-wrapper.conf file (as suggested here: Install openHAB 2 in Windows 10 as Windows Service)

See also my comment on:

Is there a better way to install the service wrapper on windows so it that doesn’t require all these fixes to the wrapper config?

Ps: Using OH 2.0.0 Stable Release Build

Hey @Dim,
I did check and you are completely right - wrapper.conf is completely invalid because it is made for vanila karaf. So far there is no easy way to customize that. It is possible to override this resource with a fragment “extension” which will be specific to OH2 so generated resources will be in syns with what OH needs.

Because service wrapper replaces startup scripts all environment variables which are set in oh2_dir_layout should be clonned to it, meaning


must be ported to


in wrapper.conf

It might work without it in first moment but later on every code which will call getenv("OPENHAB_USERDATA") will behave differently depending on the way OH was started (command line or service).

1 Like

I also had to port some stuff from C:\openHAB2\runtime\bin\setenv.bat to the wrapper.conf like:


:: set java options
  -Dopenhab.home=%OPENHAB_HOME% ^
  -Dopenhab.conf=%OPENHAB_CONF% ^
  -Dopenhab.runtime=%OPENHAB_RUNTIME% ^
  -Dopenhab.userdata=%OPENHAB_USERDATA% ^
  -Dopenhab.logdir=%OPENHAB_LOGDIR% ^\config ^
  -Dorg.osgi.service.http.port=%HTTP_PORT% ^


because with only the oh2_dir_layout variables included in the wrapper.conf, I was still getting some errors.

With these 2 changes, I got the windows service working… but…still… I am not sure if the system is stable now… I may have missed some parameter or other environment variable in the wrapper.conf that will show it’s ugly face later down the road…

As @ThomDietrich suggested: The right move here is to create a script (which will be distributed with OH2) that produces a proper wrapper.conf file (and maybe takes care of the service installation commands also) so that people will not have to customize it to make it work. We need some scripting support to make this happen… @xsnrg made a very nice script for linux (for upgrading a manual OH2 installation) but we need 2 scripts for windows also (one for manual upgrades and one for generating a proper wrapper.conf/installing the windows service automatically)

Back to the original purpose of this thread:

Documenting openHAB :slight_smile:
There is so much to be done… I am reviewing now the list @

It would be great for more people to contribute also! It will make it easier for all.

I use the online editor in github when browsing and it’s very easy (no need to install jekyll or anything else)

1 Like

Great tip! :clap:

I took a crack @ Issue #202 with PR # 281 here: View (JsonDB Storage description)

I hope that I didn’t make a mess out of the info :smile: @chris @ThomDietrich @Benjy

If anyone has any suggestions for improvement, please add comments to the PR! :sunglasses:

1 Like

I made my first contribution to the documentation several days ago and I think I’d like to try and fill in some more. The two I’m most interested in tackling right now (Things and Services configuration) are completely lacking text, but I have some questions before I attempt to take these on.

First, a couple of general questions:

  • Is anyone already working on this? I don’t see any PRs or issues logged for the Things and Services pages, but I might have missed them.
  • Should I log an issue for each of the missing docs before I attempt to write them?

For the things configuration page, I’m thinking about covering:

  • Discovery based configuration
  • File based configuration
    • Basic syntax
    • A few key examples
    • Highlighting the fact that some bindings (for example, Z-Wave) do not currently work properly with things files

Does this look like a good start? Anything I should add / remove?

For the Services configuration page, I question what should really go here. I would like to add some documentation explaining the config files that go in the /conf/services folder, but I’m not sure if this is the appropriate section or if that has been adequately covered elsewhere. I’m guessing this is the place since I haven’t been able to find consistent info on it.



Hey Stephen, that sounds great!

The Things article is an important one to be written. There is currently no Issue for it and Yes, that’s exactly where you should start! :wink:
Over there we can also discuss all details and topics that you want to talk about. Your bullet points already contain a good summary. Maybe you can have a look at the items and the sitemap articles to get a feeling for the style we went with till now.
The last part about which bindings actually do and do not support Things should go into the introduction I’d say.

Regarding Services: I was also not sure about this one yet :confused: It was supposed to describe the services files. However these are becoming more and more irrelevant with the rise of Paper UI and there is also not much one can say other than “Set the options according to your needs” :wink: Let’s start with Things now and Services can wait a few more days.

See you on the other side!!

1 Like

pinging this thread back to the top :wink:

1 Like

I need beta testers for the Windows Service Installation instructions !

Please try them out in a Windows system and let me know if they are ok

Kudos to @ScoobyDrew who provided the fixes to the wrapper.conf

Windows Service Installation Steps Link

If you find something wrong, please post a comment on:

1 Like

Do we have any “emergencies” with regard to documentation updates that will help with the 2.3 Stable Release?

I will spend some time to refresh some stuff and look over

Ps: “12 months later” :slight_smile: