Installation document feedback

[ruzickap]

Is your feature request related to a problem? Please describe.

New users...

Describe the solution you'd like

I'm new user of the Educates who would like to give you feedback about the initial installation + documentation.

When I see the new project like this one I always want to try it in minimal & easy configuration - just to see it is "somehow running".

• Your documentation is sometimes quite detailed - which is not handy for attracting new users. "Quick Start Guide" should work "everywhere" where you can run kind and should contain only minimal list of commands to run the basic setup. Changing the OS / Docker Desktop settings is something I would like to avoid when "testing" some software...

• Downloading the CLI - maybe few curl commands may help (later brew for Mac).

• X.Y.Z - versions mentioned many times in the documents should be replaced by latest release to make it easier for the end users...

• Copy & Paste icons - every command should have the "copy & paste" command - to make the user's live easier (see the example below - top right icon):

• "Installation Instructions" are using commands like kapp and kctrl which may not be well known to the end users. Instead of redirecting the user to https://carvel.dev/ or https://carvel.dev/kapp-controller/docs/develop/install/ - he/she should be pointed to the exact commands...

  • Going through https://carvel.dev/ web pages - search for installation steps may not be great user experience...

• kapp and kctrl are modern way how to install complex apps. I'm not sure if it is even possible, but many people will still prefer to use Helm installation - which is still some kind of "standard" and easily understandable by everybody...

  • Helm values are usually the place where I would like to configure my Ingress + DNS + certificate, PVC, ...
  • It may not be trivial to install/integrate Educate to some already configured k8s cluster which is running ingress-nginx + external-dns + cert-manager + ... to perform the initial testing.

I'm pretty sure you will have answer on all the questions above, but this is just my first view to the project and few things I was "missing" / "would like to improve"...

Describe alternatives you've considered

I'm pretty sure everything is working fine but the learning curve is quite high...

Additional information

No response

[GrahamDumpleton]

Few comments on different issues to give some historical background or details of what already intend doing.

• Once upon a time it was possible to install without needing to make changes to Docker Desktop standard install. Docker started changing their defaults such that it was impossible to install things without changing some settings. I am not sure there is much we can do on this as it just can't work with out of the box defaults for Docker Desktop anymore. An absolute minimum is being able to create ports 80/443 so HTTP/HTTPS works. Running a Kubernetes ingress router on non standard ports isn't really practical.

• For the CLI, there is a Homebrew recipe at https://github.com/educates/homebrew-educates. We have been neglectful in ensuring is up to date and has not been added to docs either.

• In version 3.0 we are moving away from use of a Carvel Package Repository and so instructions when updated will not talk about kctrl and instead if wanting to use kapp-controller method of installation you will use kubectl to explicitly create namespace, service account, role binding, and then apply a Carvel App resource instead. This is only for where wanting to use kapp-controller though, as will be simpler and recommended to install using educates deploy-platform command into any Kubernetes cluster. So we are already moving away from having to have Carvel tools installed.

• There is no plans to use Helm for installation. Carvel tooling and installation using educates deploy-platform still has a values config file much like Helm does to configure everything. The values file allows you to disable/enable component services where you need them, or you don't need them if don't want an opinionated install and want to use your own installed services. The documentation hasn't been updated yet for new 3.0 version of CLI based installer where hopefully things will be a bit easier.

Note, just because didn't respond on something doesn't mean we will not take it on board and look at improving on things. Overall we are aware we need more user guides and tutorials, vs what is better called reference documentation as it is now.

[jorgemoralespou]

Hi @ruzickap thanks so much for looking at the project and taking the time to evaluate whether it can help you. We're aware there's big room for improvement, and that's why we want to make people aware of the project so we eventually get some contributions, so far it's mainly 2 people working on it. I know the risk of adopting such a project, but to be fair, we want more community, because the project itself, as you saw at DevConf is an amazing project ;-) We take note of all your issues and will try to address them as soon as possible. As @GrahamDumpleton mentions, we're now in the process of getting a new release (3.0) out which will bring many changes, and we haven't been able to update released documentation yet, as this is for released versions. We should be finished in a couple of weeks, at most, hopefully.

We've been aleady pointed to what I consider 2 of the main complains in your comment. First, the getting started, and yes, we need to make a better job there, and with the help of users we will get there. Sometimes it's difficult for us to write such basic Getting Started Guides mainly because we know the project so well, that everything seems way easy for us, but then comments like this helps us see where improvement needs to be made. On the Helm side, this is something we have neglected to do, but that, if anyone would want to contribute a HelmChart, we would be really happy to adopt. We have never used helm, as we're not fan of the tool, but we realise the importance f having a Helm installer, but as I said, our lack of knowledge on the tool and the fact that our current installer (coming in 3.0) is darn good, we have not taken serious the effort to bring Helm into Educates. We will start to consider as more people requests it.

Thanks again for all your effort on looking at the tool, and keep in mind that we're gonna be as supportive as possible, either here or in Kubernetes` Slack Educates Channel

[GrahamDumpleton]

FWIW, the latest develop builds of documentation where starting to update things for 3.0 can be found at:

• https://develop--educates-docs.netlify.app/

I have already added the copy button you suggested and also curl commands under tabs for different architectures.

• https://develop--educates-docs.netlify.app/getting-started/quick-start-guide#downloading-the-cli

The X.Y.Z issue in kctrl instruction section will in most cases go away as when switching to newer way of doing things you will either be using educates CLI, or for kapp-controller we can point at App resource YAML file under GitHub releases using a latest link.

Updates to the all the pages under "Installation Guides" still has to be done. I will be doing that over the next few days.

[ruzickap]

Thank you for your comments guys. Looking forward for the new release :-) Keep up the good work...

[jorgemoralespou]

I'm gonna leave this issue opened until we release 3.0 and all the things described are addressed, or else, until we create dedicated issues with the remaining things.