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.
You must have a GitHub account.
Once logged in click on your icon in the upper right and select settings.
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.
Navigate to https://github.com/openhab/openhab-docs and press the “Fork” button at the top. This will give you your very own version to play with.
Clone your Fork to your local machine.
Add the original repo as the upstream with the command:
git remote add upstream firstname.lastname@example.org:openhab/openhab-docs.gitNOTE: use the http address if you did not upload an ssh key
Checkout the gh-pages branch with the command:
git checkout gh-pages
Merge the changes from the upstream with your fork with the command:
git merge upstream/gh-pages
Create a new branch for the one issue you want to work on with the command:
git checkout -b <name>
Push the branch to github using the command
git push origin docker
Make your changes.
As you go, add and commit changes with the commands
git add .and
git commit -m "message"
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.
Make sure to reference the Issue in your comment.
Closes issue #XXX
Additional commits can be made to the PR by making the changes locally to your branch and pushing the commits.
you can work on more than one issue at a time by working on each one in a separate branch.
Before creating a new branch, make sure to do steps 7 and 8 before creating a new branch to work on
Useful page: https://help.github.com/articles/fork-a-repo/
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 hope that I did this correctly I will contribute more stuff in the quick fixes soon also.
Oh no Maybe you can comment on his PR?
*teacher mode on* That’s why one normally first claims an Issue
*teacher mode off*
Thanks for your help!!!
Sorry Mr Dietrich
But sorry @Dim ! I should have mentioned it!
It was my bad. The PR info is online… I should have seen it
I will comment on yours soon
For now, I got excited with something new here:
So I will tackle documentation in a bit
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:
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.
// 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: C:\openHAB2\userdata\etc\openHAB2-wrapper.conf 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 openhab>
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 set.default.KARAF_HOME=C:\openHAB2\runtime set.default.KARAF_BASE=C:\openHAB2\userdata set.default.KARAF_DATA=C:\openHAB2\userdata set.default.KARAF_ETC=C:\openHAB2\userdata\etc # Java Application wrapper.working.dir=%KARAF_BASE% wrapper.java.command=%JAVA_HOME%/bin/java wrapper.java.mainclass=org.apache.karaf.wrapper.internal.service.Main wrapper.java.classpath.1=%KARAF_BASE%/lib/boot/*.jar wrapper.java.classpath.2=%KARAF_BASE%/lib/wrapper/*.jar wrapper.java.library.path.1=%KARAF_BASE%/lib/wrapper/
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
org.apache.karaf.main-4.0.8.jar is in
If I change
wrapper.java.classpath.1=%KARAF_HOME%/lib/boot/*.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) http://wrapper.tanukisoftware.org 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: https://github.com/openhab/openhab-docs/pull/262
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
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
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).
I also had to port some stuff from
C:\openHAB2\runtime\bin\setenv.bat to the wrapper.conf like:
:: set java options set JAVA_OPTS=%JAVA_OPTS% ^ -Dopenhab.home=%OPENHAB_HOME% ^ -Dopenhab.conf=%OPENHAB_CONF% ^ -Dopenhab.runtime=%OPENHAB_RUNTIME% ^ -Dopenhab.userdata=%OPENHAB_USERDATA% ^ -Dopenhab.logdir=%OPENHAB_LOGDIR% ^ -Dfelix.cm.dir=%OPENHAB_USERDATA%\config ^ -Dorg.osgi.service.http.port=%HTTP_PORT% ^ -Dorg.osgi.service.http.port.secure=%HTTPS_PORT%
wrapper.java.additional.10=-Dopenhab.home=C:\openHAB2 [...] wrapper.java.additional.16=-Dorg.osgi.service.http.port=8080 wrapper.java.additional.17=-Dorg.osgi.service.http.port.secure=8443
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:
There is so much to be done… I am reviewing now the list @ https://github.com/openhab/openhab-docs/issues
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 https://github.com/openhab/openhab-docs and it’s very easy (no need to install jekyll or anything else)
If anyone has any suggestions for improvement, please add comments to the PR!
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!
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 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” Let’s start with Things now and Services can wait a few more days.
See you on the other side!!
pinging this thread back to the top
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
If you find something wrong, please post a comment on:
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 https://github.com/openhab/openhab-docs/issues
Ps: “12 months later”
Pinging this one up on top