The overall idea of the distro structure is described here.
The static user files should reside in conf, the dynamically generated data in userdata, the read-only “binary” in runtime and optionally, bundles can be put in the addons folder.
Packaging systems such as apt, synology, snappy, etc. should simply only provision the runtime folder and also only update this while keeping the other folders in place.
So far the theory towards we strive, but currently there are a few issues:
- In openHAB 1, we started the OSGi framework always with the
-cleanoption, which discarded any information and hence made the static configuration files the only source for settings. In the new distro, we do not clean the OSGi framework upon startup, so that we can also change configuration through the Paper UI, the OSGi console or any other mechanism. The problem is that it is not obvious for the user what is installed and configured anymore (removing a bundle from addons does not uninstall it). The information is well-hidden somewhere in the OSGi cache inuserdata. - Replacing the runtime folder does not automatically upgrade the installation if the userdata folder is kept. We should find a good mechanism to update for online/offline distro likewise.
- The new ESH concepts store stuff (e.g. discovered things) in a database (in
userdata/mapdb), which is not human-readable - this isn’t nice for backups as it is either all or nothing and cannot be manually modified. An export to a human-readable format would be welcome. - Since items/things/sitemaps etc. in the
conffolder are considered to be read-only for the runtime, the UIs cannot be used to modify them - only information in the mapdb is modifiable. This leads to either/or configuration options, which make a smooth transition to the new concepts difficult. There is a discussion about possible solutions in the ESH forum.
In general, I see two sides in our user base that need to be served:
- The openHAB 1 users, who want to continue using what they have and know as smoothly as possible. Most stuff should be configured textually in the
conffolder and wiping theuserdatafolder should not really harm them. - New non-tech users, who want ease of setup and use, so what the new concepts of openHAB 2 promises. Possibly there is no textual configuration at all and all is done through UIs and configuration is stored in the mapdb and the OSGi framework.
Our distro should be able to support both and also a middle path (which will probably be the majority of users when the discovery feature is used more and more by the first group).
I would be interested in your ideas how we could tackle the above problems. Do you always want to have full control through textual files? Or would you also trust a setup where all your settings are soaked into a binary database file? What would you expect the UI to do if you try to modify a file that you have defined yourself in the conf folder?
I think we still need to clarify these point before it makes sense to write excessive documentation about it - so I count on your constructive ideas!