add general deployment documentation by andrewfulton9 · Pull Request #686 · nebari-dev/nebari-docs

andrewfulton9 · 2026-06-10T22:01:48Z

Reference Issues or PRs

Closes #680

What does this implement/fix?

Put a x in the boxes that apply

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds a feature)
Breaking change (fix or feature that would cause existing features not to work as expected)
Documentation Update
Code style update (formatting, renaming)
Refactoring (no functional changes, no API changes)
Build related changes
Other (please describe):

Testing

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

Documentation

Access-centered content checklist

Text styling

The content is written with plain language (where relevant).
If there are headers, they use the proper header tags (with only one level-one header: H1 or # in markdown).
All links describe where they link to (for example, check the Nebari website).
This content adheres to the Nebari style guides.

Non-text content

All content is represented as text (for example, images need alt text, and videos need captions or descriptive transcripts).
If there are emojis, there are not more than three in a row.
Don't use flashing GIFs or videos.
If the content were to be read as plain text, it still makes sense, and no information is missing.

Any other comments?

netlify · 2026-06-10T22:01:53Z

❌ Deploy Preview for nebari-docs2 failed.

Name	Link
🔨 Latest commit	`3cca70a`
🔍 Latest deploy log	https://app.netlify.com/projects/nebari-docs2/deploys/6a2c1fc4ba15120008bc9edb

khuyentran1401 · 2026-06-11T03:09:37Z

+description: Common GitOps setup, deploy, verify, update, and destroy steps shared by all NIC-managed providers.
+---
+
+This page covers the lifecycle steps that are common across all NIC-managed providers: setting up a GitOps repository, storing credentials, running `nic deploy`, verifying the cluster, signing in for the first time, updating, and tearing down.


Small thing: since the provider pages drive the actual flow and this page fills in the shared steps, it might help to say that at the top (something like "start on your provider's page, this covers the steps it links to").

This will make it clear to open the provider page first.

khuyentran1401 · 2026-06-11T03:12:29Z

+## Configuration
+
+Download a starter config from your provider's page. At minimum, every config requires these fields:
+
+```yaml
+project_name: my-cluster          # lowercase alphanumeric, hyphens, underscores
+domain: nebari.example.com        # a hostname you own
+
+certificate:
+  acme:
+    email: you@example.com        # required for Let's Encrypt; renewal notices go here
+
+git_repository:
+  url: "https://github.com/<your-org>/<your-gitops-repo>.git"
+  path: clusters/my-cluster       # subdirectory in the repo; conventionally matches project_name
+  auth:
+    token_env: GIT_TOKEN          # matches GIT_TOKEN set in .env
+
+cluster:
+  <provider>:
+    # Provider-specific fields — see your provider's page for required options.
+```
+
+For the full schema, see the [NIC configuration reference](https://github.com/nebari-dev/nebari-infrastructure-core/blob/main/docs/design-doc/appendix/16-configuration-reference.md).


I noticed the provider pages already include a complete starter config, so this generic version felt a bit redundant to me, and it's another place to keep in sync when a field changes.

Maybe we keep just the schema-reference link here and let each provider page own the full config?

khuyentran1401 · 2026-06-11T03:15:13Z

+After deploy completes, your cluster needs a DNS record to be reachable:
+
+- **Cloudflare-managed domains:** add `CLOUDFLARE_API_TOKEN` to your `.env` with `Zone:DNS:Edit` permission on your domain's zone. `nic` creates the record automatically.
+- **All other DNS providers:** `nic` prints the load balancer's IP address or hostname at the end of deploy. Create an **A record** at your DNS provider pointing your domain to that value. The cluster will not be reachable over HTTPS until the record propagates.


Small inconsistency I noticed: here we say to create an "A record", but the AWS page calls it an "A/CNAME record". It might be worth aligning the two pages on the same wording to avoid confusion.

khuyentran1401 · 2026-06-11T03:19:48Z

+- **Automatic TLS** for every service you publish ([cert-manager](https://cert-manager.io/) + Let's Encrypt).
+- **Single sign-on** across all services ([Keycloak](https://www.keycloak.org/)).
+- **Ingress routing** for any service you expose ([Envoy Gateway](https://gateway.envoyproxy.io/)).
+- **GitOps-driven updates:** future changes flow through a Git repo you own ([ArgoCD](https://argo-cd.readthedocs.io/)).


Small wording thing: this bullet lost the "roll out or roll back" detail the AWS page had. Spelling out that you deploy or revert apps by committing to the repo would make it less vague, I think.

khuyentran1401 · 2026-06-11T03:24:33Z

+
+```bash
+GIT_TOKEN=github_pat_...             # read+write, used by nic during deploy
+ARGOCD_GIT_TOKEN=github_pat_...      # read-only, used by ArgoCD to pull manifests


Might be worth adding "optional" here. This is up to you.

Co-authored-by: Khuyen Tran <khuyentran@codecut.ai>

andrewfulton9 · 2026-06-11T21:43:56Z

Thanks for the review, @khuyentran1401! I addressed all the comments. If you could give it another look, I would really appreciate it!

khuyentran1401 · 2026-06-12T10:28:33Z

 ---

-This page covers the lifecycle steps that are common across all NIC-managed providers: setting up a GitOps repository, storing credentials, running `nic deploy`, verifying the cluster, signing in for the first time, updating, and tearing down.
+Start on your provider's page — it walks you through the full deployment and links here for the shared steps. This page covers the lifecycle steps that are common across all NIC-managed providers: setting up a GitOps repository, storing credentials, running `nic deploy`, verifying the cluster, signing in for the first time, updating, and tearing down.


It is easy for readers who skim to miss this. Maybe add it in a note block?

Syntax:

:::note Your content :::

khuyentran1401 · 2026-06-12T10:33:39Z

+
+Start on your provider's page — it walks you through the full deployment and links here for the shared steps. This page covers the lifecycle steps that are common across all NIC-managed providers: setting up a GitOps repository, storing credentials, running `nic deploy`, verifying the cluster, signing in for the first time, updating, and tearing down.
+
+Provider-specific prerequisites, configuration, and cost notes are on each provider's page ([AWS](/docs/how-tos/providers/aws)).


This one only lists one provider. Can you link to this provide page instead? /docs/how-tos/providers

This page contains the support matrix and will be available after #685 is merged.

khuyentran1401 · 2026-06-12T11:34:23Z

@andrewfulton9 After this merges, let's split deploy.mdx into one page per topic under #630, matching the operational how-tos: GitOps and credentials to #688, deploy and verify to #689, DNS to #654, Keycloak to #656, Update to #658, and Destroy to #657.

That only became clear to me after I scoped #680, so it's not on your work here. I'd merge this as-is and do the split as follow-up.

Co-authored-by: Khuyen Tran <khuyentran@codecut.ai>

andrewfulton9 · 2026-06-12T15:05:01Z

Thanks for the feedback, @khuyentran1401! I addressed all the above comments. CI will fail until #685 is merged in

add general deployment page. Update AWS page.

3e1a72f

andrewfulton9 requested a review from khuyentran1401 June 10, 2026 22:01

github-project-automation Bot added this to 📖 - Documentation Jun 10, 2026

github-project-automation Bot moved this to Todo 📬 in 📖 - Documentation Jun 10, 2026

andrewfulton9 requested review from Copilot and dcmcand June 10, 2026 22:03

Copilot started reviewing on behalf of andrewfulton9 June 10, 2026 22:04 View session

andrewfulton9 requested review from kcpevey and marcelovilla and removed request for Copilot June 10, 2026 22:04

Update links

6b132eb

andrewfulton9 changed the title ~~add general deployment page. Update AWS page.~~ add general deployment documentation Jun 10, 2026

Remove hetzner link

753efea

andrewfulton9 mentioned this pull request Jun 10, 2026

Docs: Add hetzner provider how-to for deploying NKP #679

Open

10 tasks

khuyentran1401 requested changes Jun 11, 2026

View reviewed changes

andrewfulton9 and others added 2 commits June 11, 2026 08:50

Update docs/docs/how-tos/deploy.mdx

9bf8adc

Co-authored-by: Khuyen Tran <khuyentran@codecut.ai>

address review comments

18ef2f0

andrewfulton9 requested a review from khuyentran1401 June 11, 2026 21:43

khuyentran1401 requested changes Jun 12, 2026

View reviewed changes

Comment thread docs/docs/how-tos/providers/aws.mdx Outdated

andrewfulton9 and others added 3 commits June 12, 2026 08:58

Update docs/docs/how-tos/providers/aws.mdx

9f692f8

Co-authored-by: Khuyen Tran <khuyentran@codecut.ai>

change to note block

b353b8b

link to providers page

3cca70a

andrewfulton9 requested a review from khuyentran1401 June 12, 2026 15:05

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

add general deployment documentation#686

add general deployment documentation#686
andrewfulton9 wants to merge 8 commits into
mainfrom
docs/general-deployment

andrewfulton9 commented Jun 10, 2026

Uh oh!

netlify Bot commented Jun 10, 2026 •

edited

Loading

Uh oh!

Uh oh!

khuyentran1401 Jun 11, 2026

Uh oh!

khuyentran1401 Jun 11, 2026

Uh oh!

khuyentran1401 Jun 11, 2026

Uh oh!

khuyentran1401 Jun 11, 2026

Uh oh!

khuyentran1401 Jun 11, 2026

Uh oh!

andrewfulton9 commented Jun 11, 2026

Uh oh!

khuyentran1401 Jun 12, 2026

Uh oh!

khuyentran1401 Jun 12, 2026

Uh oh!

Uh oh!

khuyentran1401 commented Jun 12, 2026

Uh oh!

andrewfulton9 commented Jun 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants


		Start on your provider's page — it walks you through the full deployment and links here for the shared steps. This page covers the lifecycle steps that are common across all NIC-managed providers: setting up a GitOps repository, storing credentials, running `nic deploy`, verifying the cluster, signing in for the first time, updating, and tearing down.

		Provider-specific prerequisites, configuration, and cost notes are on each provider's page ([AWS](/docs/how-tos/providers/aws)).

Conversation

andrewfulton9 commented Jun 10, 2026

Reference Issues or PRs

What does this implement/fix?

Testing

Documentation

Access-centered content checklist

Text styling

Non-text content

Any other comments?

Uh oh!

netlify Bot commented Jun 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

❌ Deploy Preview for nebari-docs2 failed.

Uh oh!

Uh oh!

khuyentran1401 Jun 11, 2026

Choose a reason for hiding this comment

Uh oh!

khuyentran1401 Jun 11, 2026

Choose a reason for hiding this comment

Uh oh!

khuyentran1401 Jun 11, 2026

Choose a reason for hiding this comment

Uh oh!

khuyentran1401 Jun 11, 2026

Choose a reason for hiding this comment

Uh oh!

khuyentran1401 Jun 11, 2026

Choose a reason for hiding this comment

Uh oh!

andrewfulton9 commented Jun 11, 2026

Uh oh!

khuyentran1401 Jun 12, 2026

Choose a reason for hiding this comment

Uh oh!

khuyentran1401 Jun 12, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

khuyentran1401 commented Jun 12, 2026

Uh oh!

andrewfulton9 commented Jun 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

netlify Bot commented Jun 10, 2026 •

edited

Loading