I was referring to #6,7,8 of the list in post #1
OH cloud, persistence and an overall summary, these are.
1 Like
Hmmm OK.
Perhaps a section is missing from post 1.
EDIT:
I made a pass at making the wording sound more like an introduction and less like a plan of what we plan to write. I updated links where they were missing and marked sections that are not yet written as [TBD].
I propose moving persistence before Pages so that when we discuss pages we can assume they have persistence set up when we talk about Chart pages and the analyze buttons and such. I didn’t want to do that unilaterally though.
Let me know if I missed a link anywhere.
I’m also going to add forward/back links to the bottom of each page so it’s easier to read them like they will be in the docs.
Added a few sentences to use the code tab and post the YAML when asking for help on the forum.
I’ve started with following the docs and building my OH3 server for learning and testing it a bit before really diving in all the way.
This section is clear, only one question. In the section File-based vs UI-driven configuration first the file based is mentioned.
When I have no clue to choose (especially new users), I would pick the first one. But likely the best option for a new user would be the UI based option.
Or is it just me with that strange behavior? 
We present the pros and the cons for both approaches. we then state that this good l guide isn’t going to present the text based approach (I. e. the user will have to look at the docs on their own). That seems pretty clear to me.
The text based configs are acknowledged so those users who are drawn to then can choose that approach. But those users will have to do so without the benefit of this tutorial. Only developers (who can figure it out from the reference docs without too much trouble) and existing OH 2 users (who already know how to use text based configs) are likely to go down that path.
We won’t code for you though. All we can do is present the pros and cons, which we’ve done. But if you have any suggestions for edits, the post is a wiki so have at it. It’s a group effort.
A practical note from an absolute beginner: It would be useful linking the active page of the installation procedure when mentioned in
This tutorial assumes users have read the concepts and installation guide already
It would be also useful to explain, besides the installation procedure, the one to make a complete uninstallation. Migrating from a tentative installation from 2 to 3, I’d like to be sure I get a full rollback to a clean state. Currently uninstalling OH2 service and deleting the openHAB2 folder - not sure if that’s a rough approach leaving some zombie stuff around- would be nice having a page just saying doing that works fine 
tagging @rlkoshak
1 Like
That’s easy. Just Read your Mail Really Fast (aka rm -rf /).
But seriously: No. This isn’t relevant for people to start with OH3 in the first place, and out of scope of this tutorial for those who don’t.
Common sense applies: make a system level backup and restore to get back there.
Well, sorry you think it’s useless. It just followed yesterday’s conversation with rloshak where I volunteered to review the doc as an absolute beginner and we agreed it was best done on 3 instead of 2.
not sure about your
rm -rf /
Really obscure for me. Is it a witty remark or is it something which can help? is it a command line command? not clear for an absolute beginner.
so you suggest I should use a restore point and restore the whole windows environment to do that? Doesn’t sound handy. I have been installing a bunch of apps to start openHAB, it would take a lot of work to roll back and reinstall everything again to get to a clen state from an app of about a couple of hundred megabytes. Uninstalling the whole Visual Studio suite would be way easier, in comparison.
In practice, here you go: I have been trying the last 3 hours.
and the most I have reched so far is this error log at the openhab prompt.
openhab> org.apache.felix.resolver.reason.ReasonException: Unable to resolve root: missing requirement [root] osgi.identity; osgi.identity=openhab-runtime-base; type=karaf.feature; version=“[3.0.0.RC1,3.0.0.RC1]”; filter:=“(&(osgi.identity=openhab-runtime-base)(type=karaf.feature)(version>=3.0.0.RC1)(version<=3.0.0.RC1))” [caused by: Unable to resolve openhab-runtime-base/3.0.0.RC1: missing requirement [openhab-runtime-base/3.0.0.RC1] osgi.identity; osgi.identity=openhab-core-io-rest-sitemap; type=karaf.feature [caused by: Unable to resolve openhab-core-io-rest-sitemap/3.0.0.RC1: missing requirement [openhab-core-io-rest-sitemap/3.0.0.RC1] osgi.identity; osgi.identity=org.openhab.core.io.rest.sitemap; type=osgi.bundle; version=“[3.0.0.RC1,3.0.0.RC1]”; r
and some other tons of error lines. Let’s see how far I can go.
Please don’t say in forum that new users do not want to spend time to contribute to improve documentation. I’m running the second day in trying to set up a working environment and maybe I will soon discover that trying to install 3 is not a good idea at all.
If you installed it on Windows (as your last comment indicates), I think this still applies to OH3: How do I uninstall OpenHAB2 from a Windows 10 PC
1 Like
thank you very much. Still wonder why is so hard to add a web page formalizing that and link it to the introduction. Baffling for me.
Java is cross platform and there are many installation methods and many OS/Platforms. Each combination would have a slightly different method for uninstallation. For instance, the commane mentioned earlier would not work on Windows.
exactly. That’s why I thought that a mention in the windows intallation page - like a header sayng “How to uninstall” ad a couple of bullet point would help. Better than absolute nothing. Just my opinion though.
I looked back at your first post here on this topic. Windows was not mentioned. The majority of developers & user have a UNIX-like OS like MacOS or Linux. That was the assumption without an OS mentioned.
you are correct. The fact is that every user assumes its system is the default. I did not think that the default of OH is Linux either.
In my view, purpose of documentation is helping people to get rid of assumptions to find solution.
Reading the documentation I just read obviously the page pertaining my OS and I did not understand that this introduction is meant only for Linux (is it?) -
I believe that the “curator” of any specific OS could easily add that piece of info, if relevant. Should be a piece of cake. You explain how to install, and how to uninstall. Comes together, usually. Especially when you don’t have an uninstall utility and you have no clue how settings work with java and the like.
Take my case for instance. I don’t know linux, I got Raspberry where, in the future, I’d like to run stuff including OH. But feels natural trying to understand OH on a OS like Windows I can easily navigate, first. Then, I will face Linux for Raspberry. It makes sense to me. And here I am.
1 Like
This tutorial here is designed to be system-independent.
For setting up OH3 on windows systems, this is the latest installation doc on GitHub: openhab-docs/installation/windows.md at main · openhab/openhab-docs · GitHub Feel free to create a new issue regarding information on how to uninstall OH3 for this page.
2 Likes
I thought I had a link to that section of the docs already. I’ll double check. Though I don’t know that we have a landing page for just “installation”. In which case which page would I link to, openHABian, Linux, Windows, QNAP?
I think that is something that belongs in the installation tutorials, not the Getting Started guide. The procedure is going to be different based on what platform and how OH was installed.
As I mentioned, it depends on how you installed it and on what platform. If on a Debian based Linux using apt, an apt-get purge openhab2 I think will get everything. If on another platform (e.g. Windows) deleting the folder you unzipped openHAB to would be sufficient I think. I don’t run Windows anymore so I don’t know how most users do that…
So, I agree unistallation probably needs to be covered somewhere but not in the Getting Started tutorial. It probably belongs in the installation instructions for the platform you are using because the procedures can be radically different between the platforms.
One thing you will find with openHAB is that only a relatively small minority of users run openHAB on anything but Linux. So almost all the advice provided is going to assume Linux unless you state otherwise in your original post. On Linux, especially if one uses openHABian where this stuff is preset up, Backup and restore can be as simple as a couple of commands. openHAB also comes with openhab-cli which offers backup and restore options, but just for openHAB, not the whole system.
Markus’s point though was that before making any major change to a system (e.g. installing or uninstalling software), creating a backup is a good idea.
The errors your are seeing are new to me. You might post about them in the OH 3 RC1 thread to see if this is a bug or something.
It’s mainly that no one has done it. I for one would welcome such a contribution.
The getting Started Tutorial is OS independent. And that’s why it doesn’t start with installation but instead asserts successful installation as a prerequisite. There are almost a dozen different platforms OH supports and we can’t cover them all in the Getting Started Tutorial.
But once installed, everything presented in the Getting Started Tutorial applies regardless of platform OH is installed on.
Also, it’s worth noting that when you create a new thread in the “Beginner’s” section of the forum, you are presented with a template asking for relevant information like what version of OH you are running and on what operating system and how it was installed.
I’m afraid you will find that there is no such curator most of the time. I don’t think anyone who actually runs OH on Windows has contributed much to the Windows Installation guide (I’d have to check to be sure).
I don’t think any one here is arguing that the information doesn’t belong in the docs. And I think we all agree it belongs in the installation page for Windows.
So, who’s going to go do it? That’s usually where everything breaks down. I’m currently booked trying to get this tutorial into the docs so I can’t do it right now. I’m hopeful that someone can step up and submit the content. It’s a great first PR really since the content is basically already written.
If anyone needs help navigating GitHub procedures I’m happy to help. It’s odd at first but pretty easy to get the hang of after a couple of times.
yes please. Not sure if I should fork, edit and submit some ways, never done that. I’m also fine interacting with someone who does that for me, in case that’s more polite to the doc team…
yes, absolutely. I actually was expecting an Introduction including a section about *where do you get the current info on how to set up the environment - *we might name it 0. Foundations. Commenting here because there is no 0 step, I looked for it in vain.
What I meant was at least providing a link to the active installation doc hub (found a lot of redundant sources and I have been quite confused which is the most udated: For instance the prerequisite section is repeated in the overview and the OS specific folder.
I understand there are multiple OS, but arranging a page bridging to OS specific instruction is not that hard.
restoring my laptop to a previous restore point is a process which -if there are no issues -takes 6 hours. And every app/setting you have installed after a restore point is zapped and need to be reinstalled afterwards. For windows users, it’s an emergency thing. Backup is easy/peasy for files, not for the registry
I understood what caused it. A bit long to explain - in short Zulu installation leaves the previous install folder untouched, so the JAVA_HOME points to a java installation no longer active. The documentation has still the old screenshots mentioning jre as path instead of zulu, so the documentation should be updated saying “be sure that the JAVA_PATH points to the same installation folder as the zulu instance you installed in prerequisites”. and change the screenshot. In bold. Maybe that’s silly, once you know it. I wasted nearly an hour to understand why.
Forgot to mention: in the page Windows | openHAB the whole second part and the screenshots in general are outdated and refer to OH2. I think it would be better placing a warning saying that in clear. Try putting yourself in the shoes of someone who has never had a peek on OH3 and cannot get that easily and has issues to fix.
Anyway - back to the topic of this specific Introduction: I understand conceptually the paragraph “An important decision: File-based vs UI-driven configuration” -
I just cannot understand where this tutorial branches - do I have to choose something in this phase or later or if it is referring to the YAML editor or the fact that somewhere (where?) you have to decide to handle things using an external editor like VScode+extension? This is interesting, important, but cryptic imho.
See How to file an Issue for some fist steps. It’s mostly focused on how to make small edits to the docs through the browser. But indeed, you will need to create a fork and you will probably want to create a new branch on your fork if the changes are involved. Once you commit your changes GitHub will show a button to create a PR.
If you run into trouble let me know.
One page, no. But we are talking about at least 9 pages.
And the Step 0 is intended to be covered by the prerequisites:
- You’ve read the concepts section of the docs
- You’ve installed OH
The Getting Started tutorial is not going to be the first things that users see when they look at the docs. In fact it’s going to be the last section under Concepts.
I already have it on my list to include a link to the concepts section and the Installation landing page. But I have no plans to include any installation or environment information in the Getting Started tutorial. It’s duplicative and will be just as confusing for new users to see all the instructions for all the supported platforms as it will be to not reproduce it here.
Sounds like a great first PR to submit. It’s short and relatively easy to implement.
It doesn’t branch. If you choose file based, as far as this tutorial is concerned, you are on your own. From that section:
In this tutorial targeting new users we’ll take a purely UI-driven approach. Review the reference documentation for details on the text based approach.
Further down just before the table of contents it also states (in the version that is checked in to GiHub right now):
This tutorial presents a series of steps that build upon one another so please review the tutorial in order. There may be concepts or steps that are presented earlier that are required to understand the parts of the tutorial presented later.
There is no branching in this tutorial. It gradually builds on the concepts presented earlier in the tutorial. It’s also not intended to be a reference. It’s not going to present everything. It’s just enough to get started.
This section exists though because:
- lots of existing users of OH mainly use file based configs and we need to tell those users that they will not be getting a Getting Started with File Based Configs from this tutorial
- it’s an important decision to make because switching between the two approaches is not easy; those users who are technically proficient enough to know out of the gate that they will not want to use the UI to create their configs need to know up front that it’s not easy to move to text based configs.
But most users should read the sentence above about how the tutorial is only going to present UI based configs and continue on.
got it. I assumed - at some point - it was possible to ask OH3 to show the textual files behind the scenes, save them and perform the switch. Do you mean that is not possible? And if that’s true, how is it possible to backup the config in case you have to reinstall/migrate to a new machine all your work? Would it be some weird form of binary export of something?
In the meanwhile there is nothing which can be done using VScode+extension then- do I get it right?
And where can I find the “reference documentation for details on the text based approach” - could a link be provided there? I think it would be useful.
You can see a textual representation of the stuff you do through the UI but not the textual representation. It’s a long complicated story but at a tl;dr:
- text based configs get loaded into openHAB’s memory as read only
- UI created stuff gets saved in a text based JSONDB file
- the UI will show you a YAML interpretation of the JSON for those elements that it supports doing so (click on the
codetab).
The third bullet point is all that is covered in this tutorial though. But that’s one technical reason why it’s so hard to move between text based configs and UI created configs.
Correct and that is what that section is supposed to be saying. You can go from text file based configs to the UI for Items. For all other text based configs you have to recreate them by hand through the UI. For anything done in the UI there is no way to export them to the text based config formats.
It’s all saved in userdata/jsondb. If you are backing things up you want all of the conf folder and most of the userdata folder. There is a backup.bat file (openhab-cli on Linux) that will grab the full config. Personally I check most of my userdata folder into git for version control. It’s all text.
If you want to configure openHAB through text based config files (.items, .things, .rules,.sitemaps, etc) then you really want to use VSCode with the OH extension. If you are following this tutorial than no, you don’t need it. It’s all done through MainUI (with one tiny exception).
It’s all unchanged from OH 2.5. So all the current docs cover it. There isn’t one link. Each file type has it’s one format and therefore it’s own set of pages in the docs.
1 Like