Migration Tutorial Use of _default.sitemap

[rkoshak]

In a recent build something changed and the "hack" to set one of your sitemaps as the default that comes up by naming it _default.sitemap no longer works. The Migration Tutorial needs to be updated to remove that suggestion.

This should be replaced with instructions for how to set the default sitemap using runtime.cfg.

[kaikreuzer]

how to set the default sitemap using runtime.cfg.

Note: This should not go into runtime.cfg, but basicui.cfg and/or classicui.cfg.

[rkoshak]

Good to know. Not having any examples to go by I wasn't sure and since the config parameter is org.eclipse.smarthome.basicui:defaultSitemap it looked like something that went in runtime.cfg

If I put it into basicui.cfg does that mean I can drop the org.eclipse.smarthome.basicui: and just use defaultSitemap?

I've been struggling with keeping up with what parameters go where. This may be a side effect from using the Docker image/manual install. I don't get updates to runtime.cfg when new parameters or as to yet undocumented parameters get added with their comments (I've searched github to discover a couple) and since a lot of bindings don't generate a default .cfg file I'm kind of left guessing what parameters are.

I completely guessed at the name of the parameters for basicui and classicui and it seems I guess right. :-)

I'm not sure how to handle this in the docs yet, at least in such a way that the docs can keep up with development.

[ThomDietrich]

Just seeing this now. The option in basicui.cfg is there for a long time, I think it's safe to add the information to docs. https://github.com/openhab/openhab-distro/tree/master/features/openhab-demo-resources/src/main/resources/services

[kaikreuzer]

These .cfg files are indeed only installed, if people choose the demo setup - in a standard setup, they are not created in conf/services, but they are directly set as a configuration through the Karaf feature, which means that an according file is created in userdata/etc. It might make sense to change this, so that a file in conf/services is created. I am just not sure whether we are rather moving away from conf/services on the long run and rather suggest people to edit userdata/etc, because this is the file that is also edited by the Paper UI (and thus changes done through the UI won't be lost, while any entry in conf/services will overrule any other setting after a system restart again). Wdyt?

[ThomDietrich]

I did not know that. I had these files in my configs from day one and never started out with a fresh set.

These files/options should be available and documented. Doesn't matter where as long as it's consistent. Thereby I would agree userdata for manual AND PaperUI edits is the better place. However, for apt based installations this (and a few other cases) creates an awkward new problem: What is stored in /etc/openhab2 vs. /var/lib/openhab? I fear these two places can get into conflict at any time.

[rkoshak]

So should the new instructions have them edit userdata/etc/org.eclipse.smarthome.basicui.cfg or services/basicui.cfg?

And this raises another question I had that I never managed to get an answer to which is what takes precedence? If I edit a parameter in services and also edit it in PaperUI (or apparently in userdata/etc), which takes precedence? Does one take precedence when you edit it but then the other one take over upon a reboot (e.g. I edit a services .cfg then change it in PaperUI does PaperUI take precedence until a reboot at which time the services .cfg takes over?

My experiments to figure this out were a bit inconclusive though that may again be a side effect of running in Docker.

[kaikreuzer]

I fear these two places can get into conflict at any time.

Not more than conf/services and userdata/etc on a normal install, right?

[kaikreuzer]

And this raises another question I had that I never managed to get an answer to which is what takes precedence?

Just as I said above: "entry in conf/services will overrule any other setting after a system restart" So the conf folder can be regarded as a static configuration which is ALWAYS taken into account (at system startup). It is useful, if you want to have a reproducible setup. If you do not care about the runtime messing around in your configuration files, you can go for userdata/etc.

I am also not sure what to recommend the "average" user - the conf/services is the natural replacement of the openhab.cfg in OH1 and you can actually even drop your openhab.cfg file in there "as is". For "new" installs, people probably would rather go for the etc folder, although I do not like the fact that it is flooded with a lot of stuff that people should not touch at all and which is rather distracting. But I couldn't find a way to separate those things in Karaf.

[ThomDietrich]

With the said above I think we should give users both possibilities. The configuration in userdata is modified by PaperUI but still accessible by the user for manual edits. Everything under /etc is what I always would consider the static overruling configuration solely influenced by the end user. For this purpose I personally love the services folder. One clear place for absolute settings. Therefore I would vote to put a commented version of basicui.cfg into services just like for every other service/addon that provides specific configuration options. At this point the user can decide between two clearly distinguished options: use PaperUI for configuration or do absolute configuration in /etc/services. The choice is up to him/her and with the needed clarity I think there will not be much misconception.

In fact I believe, that other applications behave in a similar way. Apache2, mysql or other big linux software is configured in almost all aspects in a subfolder of /etc but retains further data/information in other folders or databases. Settings in /etc can always be considered as taking precedence.

As for the recommendation: I would go both ways:

"In order to define the name of your default sitemap, you have two options. You can either use PaperUI to select the prefered sitemap or you can manually set the name if your default sitemap inside services/basicui.cfg. Be aware that settings under services/ always take precedence."

[rkoshak]

From a user's perspective, what Thom describes is closer to the way I at least would expect it to work. We set the precedent that add-ons are configured in services and most other Debian installed software puts all their settings in /etc, or at least that is how it seems.

To have a split between some things get configured in /etc/openhab2 while others get configured in /var/lib/openhab2/userdata violates that expectation. Similar to my comments on the menu for transforms, actions, persistence, etc, I as a user would expect that all add-ons be they bindings or UIs, would be manually configured the same.

I also realize that doing so may be an impediment to advancing PaperUI et al to eliminate the need for manually editing text files in the first place.

[ThomDietrich]

I'm happy to realize, that this whole problem has been solved in the meantime. @rkoshak do you agree?