[DOC] - Improvements to local deployment docs

[kcpevey]

Preliminary Checks

• This issue is not a question, feature request, RFC, or anything other than a bug report. Please post those things in GitHub Discussions: https://github.com/nebari-dev/nebari/discussions

Summary

I went through the process of deploying Nebari locally on my mac following the Deploy Nebari on local machines docs. There were a few places I was confused as I was following along. I also had a few notes/commentary on my experience deploying this for the time in years.

• There is discussion about kind, but I never saw or interacted with it. It seems like this information belongs in reference, not the how-to document.
• An installed version of Nebari, for any directions please visit [Install Nebari](https://www.nebari.dev/docs/get-started/installing-nebari) section, these install instructions don't explain the how to locally install, which is the point of this how-to doc.
• confirmed that nebari is successfully installed in your environment. - how would I do this? Would a simple nebari --version work?
• 2. Executing the command below ... - this input being broken into multiple lines is confusing to try to read. It would be easier if it was one line that was scrollable.
  • half of the inputs here are explained before the command, and terraform-state awkwardly being by itself after the command. They should be combined.
  • omitting the --domain option is recommended - but you just told me to include the domain??
  • You will be prompted to enter values for some of the choices above if they are absent from the command line arguments (for example, project name and domain) but you just told me I could leave it off??
• Once nebari init is executed, you should then be able to see the following output: - I did not see this or any other output. It just exited and I was left wondering what just happened.
• 10+ lines later, I get the explanation that The Nebari initialization scripts create a nebari-config.yaml. This should be explained before ever running the init. We need an intro paragraph under the Initializing Nebari explaining what it is you're about to do and what it will achieve.
• In order to deploy the infrastructure, we need to set up a DNS record for the <domain> It was recommended I NOT set the domain. I have these instructions that assume that I DID set the domain, but what if I didn't?
• You can skip this section if you have an x86_64 machine. If you're using Mac M1, then the x86_64 docker images will not work out of the box. You would need to use images that are built with support for arm as well. - I'm confused at what this is trying to say. If the whole section is mac-specific, then the section heading should "customization of docker image for mac". And am I supposed to do something here?
• We're building all the docker images for both platforms except external images. The only external image relevant here is keycloak. You'd need to update the keycloak image for the deployment, which can be done by adding the override for the keycloak deployment to update the image: - who is "we"? The nebari team builds docker images for both platforms or I'm about to do that on my machine? "You would need to update the keyclock image" - is that supposed to mean "you NEED to update ..." and now I'm completely lost on why I'm doing this. Is this only for macs? What is an external image? It can't be one the nebari team doesn't manage because we are hosting it based on the given path? Why doesn't Nebari just build fill this out properly for me in the first place? Also, these are docker image changes, but where am I supposed to be making these changes?
• Increase fs watches I don't know what this is or why I need to change this. Or if I even really do need to change it?
• Missing at the end of the section - "tada, now you have a nebari-config.yml that is ready to be deployed locally."
• at some point in that section it mentions nebari init --guided-init - which feels like the more noobie path. Why wasn't I instructed to follow that? What is it?
• nebari deploy -c nebari-config.yaml --disable-prompt - what does "disable prompt" do and why would I want to do that as new user?
• I was told to run curl -k https://domain/hub/login to "verify" the deployment. I got back pages worth of html in my terminal. No idea if that means success?
• So, if you do not want to use Let's Encrypt, you can use the following workarounds to properly view the pages but you didn't explain what Let's encrypt is or does.
• Nebari also has a destroy command that works the same way the deploy works but instead of creating the provisioned resources it destroys it. - what are "provisioned" resources? docker images? what else did it do my machine? I probably should have been told a list of all the things it was going to do my machine before I started if its more than a docker image...