YunoHost / issues

General issue tracker for the YunoHost project
71 stars 8 forks source link

Series of issues running through install documentation for first time #1436

Open mitra42 opened 4 years ago

mitra42 commented 4 years ago

I’m trying to install Yunohost for the first time, so that I can build an installer for the Internet Archive offline server as one of our partners wanted to run it on Yunohost.

Since I’m coming to it with a fresh eye I thought the feedback might be useful. Note that even though I’m seriously experienced I hit multiple issues that almost made me give up, so I’m very worried that many other people will hit the same, or other problems.

I completely recognize its difficult to write docs for multiple situations and multiple levels of expertise, so this is just one data-point !

One consistent problem was the order of things, and getting sent off to pages, or being told to do something that only worked after doing something further down the page !

I’m happy to post these at individual issues, if that is preferred, but I thought it might be more useful strung together in the order encountered. I’m also happy to make the edits myself and submit PRs but I didn’t want to muck around with your docs when there might be other reasons for the way they are written, or other pathways/scenarious. where their order and logic make sense

First failure: RPI4 Downloaded image, flashed, inserted into RPI4 and it failed. Looking at the date on the image it looks like its from Feb which I think was before the RPI4 releases.

It booted on RPI3 fine, the docs missed that at this point on many systems you can get to it with ssh raspberrypi but I guess the docs are generic to all platforms, so presume this suggestion can't be added ? And I guess you can’t pick a common hostname for all of them (like “yunohost”) might not work ?

Next failure was following the Web Interface instructions it ran for ever

The install never completed, pacman kept animating, and there were never any errors, SSH-ing into the box worked (at raspberrypi) and the box hadn’t restarted or changed passwords. Its possible the domain was unavailable as I see it shows up somewhere else with dig mitra.nohost.me,

I re-flashed the image and tried again from the command line with a different domain name, which worked fairly quickly this time.

Next failure - port forwarding docs Next step on https://yunohost.org/#/postinstall is to go the Administration interface, But these instructions come BEFORE the instruction to setup port forwarding so the admin interface didn’t work.

On https://yunohost.org/#/postinstall

Next failure: endless loop Even after setting up port forwarding of 443 Both chrome or Firefox failedl to accèss https://mitra1.nohost.me/yunohost/admin (the forwarded port) getting stuck in a loop going back to the “its insecure” I’m not sure what was happening exactly - its possible the mitra1.nohost.me had not propagated, or that something I was doing to try and fix it was making it worse. (For example I tried accessing via VPN to make sure I was seeing the “outside the LAN” experience. ). I can’t give useful STR because this morning after running the UPnP instructions it works … on that point .

Finally - certificate warnings On https://yunohost.org/#/postinstall Don't be too afraid of the certificate warning, you'll probably be able to install a Let's Encrypt certificate :). I assume the smiley face means - “in theory you should be able to do it, but in practice you’ll get tripped up”

alexAubin commented 4 years ago

Thank you for your precious and important feedback :+1:

The install never completed, pacman kept animating, and there were never any errors, SSH-ing into the box worked (at raspberrypi) and the box hadn’t restarted or changed passwords. Its possible the domain was unavailable as I see it shows up somewhere else with dig mitra.nohost.me,

I believe that kind of bug will be fixed in 3.7 with this commit https://github.com/YunoHost/yunohost-admin/commit/2187657def8fef1f34a9daa985c22869d3e5c04e (not sure that's the right commit, but I think I fixed a similar issue about infinite pacman during postinstall)

Next failure - port forwarding docs Next step on https://yunohost.org/#/postinstall is to go the Administration interface, But these instructions come BEFORE the instruction to setup port forwarding so the admin interface didn’t work.

I'm confused about that part because the postinstall doc advises how to access the server using the local IP (@ home) or global IP (for a VPS), so no port forwarding should be needed this far.

(Though apart from that I do agree that the stuff at the end of this page should be made more obvious somehow, e.g. have these displayed directly on a congratulation screen after the postinstall finished, or in place of the "create the first user" warning at the end of the postinstall)

mitra42 commented 4 years ago

Sorry for any ambiguity - it says

This password will be used to access to your server's [administration interface.](https://yunohost.org/#/admin) You would also...

The obvious thing - since instructions are already confusing at this point - is to click on that link - which then gives you instructions on https://yunohost.org/#/admin to get to the admin interface which fail because ports haven't been forwarded.

Note - I say the instructions are confusing, because I'd just struggled through the web post-install (which failed) and the command line post-install (which worked) and are now reading through "Informations Asked" which is irrelevant since you've already guessed your way through those questions.

What I'd do .... in terms of order is something like