Improve installation docs
Feedback from @mart, copied from our Rocket Chat:
Overall impression:
- Most parts went smooth
- Documentation is clear
Setup used:
- A 'provisioning vps', which was buster, clean installed
- A OAS VPS, bullseye, clean installed
Issues allong the way:
Step: Clone the repo
The written refers to version 0.6, whille the example command refers to 0.7. I've used 0.7
Step: intall pip requirements
This is not working auto of the box. I think this is because an update on the cryptography package. at least on my buster system, I first had to execute:
pip install --upgrade pip
If i do not do that, get the message "error: can't find Rust compiler", on the page
https://cryptography.io/en/latest/faq/, this error is explained, hench I ran the update.
Step: click link
Not sure if it's a gitlab issue, but the referenced links do not work on how gitlab renders the pages
(create cluster manua) Step 3 create cluster
It is likely somebody has a new machine. Like in my case, I never logged in to that machine yet, so the ansbible script fails with
msg: Host key checking is enabled, and SSH reported an unrecognized or mismatching host key.
. Maybe add two small notes:
- make sure you can access the system with the right priveleges (we use ssh as user root, which is maybe not default for all users)
- make sure there the SSH public key is in you local known hosts file.
Final step
I feel a bit empty after reading and executing the documentation. I was all pumped up and excited to this all and then after the last step there is no way (clear) way on know how to continue
- there is no link to the OAS usage document
- the test link is not working
- after the last step, the URL is not working
And mainly that last thing is important to address. Because I didn't know where to go (hench, i only found the usage page later), i tried to go to https://oas.lightmoon.net, however, no connection at all.
After some time, I sshed into the kube system to see what is happening, and i saw a lot of activity. I think it needs to be clear that installation is now happening in the background and it can take a while to install everything.
My joy came back when i saw the login panel and 10 minutes later or so, nextcloud was also working.
So all in all, it went smooth and it felt kind of solid, i think adding something at the end of the documentation can help with setting the right expectations (be patients & here are the usage docs)