docs(software-packs): add NebariApp hands-on tutorial

[khuyentran1401]

Reference Issues or PRs

Fixes #675. See also nebari-dev/nebari-operator#136 (upstream bug that blocks Step 6 end-to-end).

What does this implement/fix?

• Adds a new tutorial under Software Packs that walks pack authors from a fresh laptop to a working NebariApp on a local Kind cluster.
• Follows the operator's own quickstart as a base, with edits to fix gaps that prevented it from working end-to-end (macOS networking setup, per-app /etc/hosts entry, Keycloak realm setup before auth).

Known limitation: Step 6 (Add login) describes the expected behavior but cannot complete end-to-end until nebari-operator#136 is fixed. The operator generates a SecurityPolicy with an unreachable Keycloak issuer URL, so the auth flow returns HTTP 500 instead of redirecting to the login page. The tutorial walks through the intended flow; once the upstream bug is resolved, the step works as written.

Testing

• Did you test the pull request locally?
• Did you add new tests?

[netlify]

✅ Deploy Preview for nebari-docs2 ready!

Name	Link
🔨 Latest commit	9740f33
🔍 Latest deploy log	https://app.netlify.com/projects/nebari-docs2/deploys/6a28ddb3b9202e0008c81f68
😎 Deploy Preview	https://deploy-preview-676--nebari-docs2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[viniciusdc]

Hey @khuyentran1401 I haven't looked deeply yet at the full lenghy of this documentation, but two things quickly surfaced when I glanced over tight now:

• The issue you mentioned and the quickstart docs only target maintainers of the operator itself, its not part of what a Nebari/NIC (NKP) user will see on a daily basis. For example, when a user sets its cluster using NIC the operator already comes installed within it and correctly configured to work on that given cluster, the user should only need to choose their own software pack of choice and install, things like the NebariApp CRD only make sense to devs whom will crreate or contribute with their own pack.
• Also, the operator is not a software pack its part of the fundational softwares that NIC manages, its not needed to be installed unless not yet present on the cluster.

[viniciusdc]

I will do another pass this afternoon, in the mean time can you fix the CI?

[khuyentran1401]

Thank, @viniciusdc . I added the note in the CI in #678

[dcmcand]

@khuyentran1401 I am going to suggest that this needs to be completely changed. As @viniciusdc said, no one using nebari will need to install the Nebari Operator manually. I think a far more useful approach here would be get a nebari cluster running locally using make localkind-up and then deploy a software pack locally, this could start with a simple existing helm chart, basically the content that https://github.com/nebari-dev/nebari-software-pack-template/tree/main/examples/wrap-existing-chart covers as a tutorial.

[khuyentran1401]

@khuyentran1401 I am going to suggest that this needs to be completely changed. As @viniciusdc said, no one using nebari will need to install the Nebari Operator manually. I think a far more useful approach here would be get a nebari cluster running locally using make localkind-up and then deploy a software pack locally, this could start with a simple existing helm chart, basically the content that https://github.com/nebari-dev/nebari-software-pack-template/tree/main/examples/wrap-existing-chart covers as a tutorial.

Thanks for the feedback. I am working on changing this.

[khuyentran1401]

@dcmcand @viniciusdc While working on this, I ran into an issue on macOS: make localkind-up doesn't bring the cluster up (#374).

The cause is a path mismatch: nic puts the gitops dir under $TMPDIR while the Makefile mounts /tmp, so ArgoCD's repo-server can't mount it.

I'm writing the tutorial assuming it's fixed. Fixing this issue would let readers run it cleanly. Can you take a look?