New folder structure

A lot has happened in the past couple of months including major changes to userdata. I would start over and only preserve your conf.

Thank you, I will give it a try.

Stan Seago

Also, is this the way I should get the most recent stable SNAPSHOT and install it?




sudo unzip -d /opt/openhab2

I am also only running idk 101 but I have downloaded


Should I install it and where? (I am on a RPi with Jessie)

Thanks again.

Stan Seago

The best idea is always to use the official install or upgrade instructions:

Easiest way is described here:

The best idea is always to use the official install or upgrade instructions:

Would be great if someone could add upgrade instructions for windows based systems :slight_smile:

Openhab2 is still in Beta so I fully understand all the structural changes which were done lately. I am using it since like a year now and really love it but having done an update now i feel the pain as dummy user. I am going to dig through all changes and error messages now to figure out to get like my hues working again. So reading the changes section here I will have to go through:

  • new folder structure
  • mapdb instead of jsondb
    Anything important structural which could be the cause of my system not working anymore I miss?

Would be really great to not only have a general Windows update instruction but also adding special cases there on structural changes. Not sure if I ask for too much here on a Beta system so :wink:


Yes, it would be nice if there were some instructions how to upgrade OH2 (snap-shot) for Windows based systems. As it now I am stuck at build #657 and can’t get newer versions to run.

A windows installation is a manual installation so you may use the upgrade instructions for manual linux installations.

I’m referring to this part:

Upgrade, Backup and Restore

To stay up to date with new releases, you should do regular upgrades of your manual installation. This is especially important if you are working with the latest snapshot as changes and fixes are incorporated constantly.

Your personal configuration will be retained on upgrades. We still recommend a backup before each upgrade.

To upgrade your manual installation, you simply need to replace the openHAB runtime files. Make sure to first stop your openHAB instance.

To make a backup of your openHAB 2 system, you need to retain your configuration and userdata files.

Instead of the linux command for backing up the system and unzipping you need to use the equivalent windows tools …

But be aware of all the structural changes especially when you are coming from an older version (prior to #624):

Magnus I just went through the upgrade process and I can give u a short rundown what I did … nothing to go to the official instructions but might be of help for you :slight_smile:

It didn’t took long to decide to start from scratch since fixing looked like impossible to me as newb. So I did following:

  1. backup copy of my current openhab folder
  2. replaced my current openhab folder with newest nightly build
  3. run the standard config from paper UI and made all general settings like language etc.
  4. copied all my rule files and the sitemap from my backup to the new structure.
  5. now the main difference starts since from what I have learned is that the intention is to not have items/thing files anymore. All things/items should be configured through the paper UI
  6. enable Item Linking “simple mode” under configuration system
  7. add the Bindings you need (e.g. the Hue Binding) from addons
  8. you should have lots of new stuff in your Inbox now.
  9. some bindings might need special attention like my Homematic Binding which needs to get the ip configured in config files or the hue binding. I used the openhab2 docu for bindings and even though some documentation in there might be outdated with the new structure I figured it out somehow. Like the hue binding docu is still describing the configuration with item and thing files instead of describing the setup within the paperui and I am pretty sure other binding docu is like the same state.
  10. within the Inbox accept all detected things until the Inbox is empty (you can hide not needed things as well but I just added everything)
  11. disable Item Linking “simple mode” under configuration system --> took my some time to figure this out. Without you will not see a sparate section for items within paperui. This might not be needed but I couldn’t figure out a better way to add items which are not related to a thing.
  12. Now I took my former item file as reference and started to add new linked items with the same names as used in my rules and sitemap.
    First I added items from type group according to my former groups within the config file. This is required to be able to assign a group to a item when creating it.
    To add the items you need to open a thing in paperui. There you will find available channels. On the right side of the channels are little arrows. If you press them you will find linked items to this channel. There click on the plus sign and pick “create new item” on the popup when u click on the item field. Then give it the same name, label, category and type as in your former items file. And if this item is part of a group you created earlier pick the right group —> this took some time!

Thats it in a nutshell even though I might have missed something. No clue if this is understandable or even the correct way but it looks like I am up and running again!

What I am still struggeling with is now what I should do if I want to update to a new nightly build again. I would really appreciate if someone with more experience could describe the standard windows update procedure within the official openhab docu with the new structure.


Sorry to be such newbish but which are the runtime files I need to replace. Would it be sufficiant to just replace the “runtime” folder and the files within the openhab root like the start.bat and leave everything else untouched? If yes that would be perfect :slight_smile:


I have never used openHAB with Windows, but … yes, that should do the trick.
With Raspbian I had a problem from one upgrade to another (don’t remember which one) and I had to replace all files in /userdata/etc except the host.key and the org.openhab.addons.cfg (and the logging files).
Maybe that is needed on Win too …

Thx Sihui lets see if some skilled openhabler who is using windows can confirm this. Hopefully not all skilled openhabler are using Linux :wink:


Thanks NoTechi for your description. Unfortunately that road was no option for me as I have to many things and items defined i both the database and files. By the way,I’m trying to upgrade snap-shot #657 to #692

Instead I tried to “decipher” the script files for linux and come up with this procedure:

  1. Backup your Openhab2 folder (you need files from there in a moment)
  2. Download and unzip the new distro. Rename the folder to whatever you usually call your openhab folder. I my case OpenHAB2
  3. Make a COPY of the newly created OpenHAB2 folder. (you need files from there in a moment)
  4. Copy the “conf” folder from your old openhab2 folder (the backup) to the new OpenHAB2 folder
  5. Copy the “userdata” folder from your old openhab2 folder (the backup) to the new OpenHAB2 folder
  6. Copy all /userdata/etc/*.properties files from the new openHAB2 COPY folder to the OpenHAB2 folder (step 3)
  7. Copy all /userdata/etc/org.apache,karaf., files from the new openHAB2 COPY folder to the OpenHAB2 folder (step 3)
  8. Remove the files in the /userdata/cache folder.

First I missed to clear the cache. The software started but it was still the old #657 version!! At least it was what is showed on screen. I don’t know if this is the right way to go as I don’t exactly know the function of the cache, but i seems to work!

The new version has only been running for 1 hour now so I it is too early to say everything is ok but at least it is a step forward :slight_smile:

I knew I had seen something:

Thx Magnus and Sihui trying to assist in figuring out how to update a Windows system. Sounds like it is still a bit tricky and might change as well on future changes.
I would wish there would be an update script/batch file included to the official Windows nightly builds. That way the developers could keep the update script updated in case of changes to other files.


Well, I would wish, we first of all have a stable upgrade mechanism, this is still not worked out. Once this is there, it should be easy to also provide update scripts (note that they do not exist for Linux either).

Looking forward to it :slight_smile:


Hey guys, @NoTechi @maze

We are always happy to receive help with the documentation. Would you care to propose changes/improvements for the Windows installation article?

The article can be found at

Whatever you decide, please create a ticket at

Regarding the update script for all OSes, I also like the idea. Please likewise create a ticket at

Does the new folder structure affect webapps being in conf/html as per this discussion:

and using http://ip-address/static/index.html to access it? Getting a “Not Found” on a .zip installation.

No, it does not touch this. I correctly see content on http://localhost:8080/static/index.html - check your url.

Thanks for the reply @Kai and a big thanks for all of the work you have put in to OH.
I have jumped around installing and re-installing so many times in recent days trying to find a way around the nrjavaserial issue Nrjavaserial upgrade causes "Serial Error: Port /dev/ttyACM0 does not exist" (/dev/ttyAMA0 in my case) that I have lost track of what I may have broken and what is a temporary issue in OH2.
I will do a complete purge and re-install to see if I can restore what I had.