Local (kind)

This guide walks through deploying NKP on your laptop with nic (the Nebari Infrastructure Core CLI). Use it to build and test a software pack, or to try NKP without a cloud account.

The local provider uses kind ("Kubernetes in Docker"), which runs a Kubernetes cluster inside Docker containers. nic ships with kind as a dependency so you don't need to install it separately.

What you get

When nic deploy finishes, you have all standard NKP services on a single-node kind cluster, with a self-signed certificate, local-only storage (no backups), and a GitOps repository on your disk.

Prerequisites

Install Docker Desktop (macOS, Windows) or Docker Engine (Linux), and make sure it is running.

On macOS, the cluster needs ports 80 and 443. To allow this, turn on Allow privileged port mapping under Settings → Advanced in Docker Desktop.

If you use Colima on macOS, install Colima and the Docker CLI, then start it:

colima start --cpu 8 --memory 16

If you also have Docker Desktop, docker commands now run on Colima instead. To switch back to Docker Desktop, run docker context use desktop-linux.

Install nic and kubectl

Follow Install NIC to install nic.
Install kubectl, the Kubernetes command-line tool. You'll use it to check that the platform is healthy.

Configuration

Download the starter config into the directory you'll deploy from:

curl -O https://raw.githubusercontent.com/nebari-dev/nebari-infrastructure-core/main/examples/local-config.yaml

The defaults work as is. To use hostnames other than *.nebari.local, change domain:

domain: packs.local  # gives packs.local, keycloak.packs.local, ...

Set it before your first deploy. To change it later, run nic deploy -f local-config.yaml --regen-apps.

For extra mounts and other kind options, see the comments in the config file and the local provider reference.

Deploy and verify

To create the cluster and install the platform, run:

nic deploy -f local-config.yaml

nic creates the kind cluster, bootstraps ArgoCD, and installs the foundational services. It takes a few minutes.

To point kubectl at the cluster you just created, write its kubeconfig (the file that tells kubectl how to connect) and use it:

nic kubeconfig -f local-config.yaml -o kubeconfig.yaml
export KUBECONFIG=$(pwd)/kubeconfig.yaml

Then check that the platform's apps are running:

kubectl get applications -n argocd

Every app should show Healthy within a few minutes. Some may stay OutOfSync, which is normal.

Open the platform

At the end of the deploy, nic prints a line to add to /etc/hosts, the file that tells your computer where to find a hostname:

  HOSTS FILE CONFIGURATION REQUIRED

  Point the platform hostnames at it by adding this line to /etc/hosts:

    127.0.0.1 nebari.local keycloak.nebari.local argocd.nebari.local

To add the line, run:

echo "127.0.0.1 nebari.local keycloak.nebari.local argocd.nebari.local" | sudo tee -a /etc/hosts

Open https://nebari.local. Skip past the browser's privacy warning (the cluster uses a self-signed certificate) by choosing Advanced, then continuing.

See Keycloak authentication to get the admin credentials and create your first user.

To open Argo CD at https://argocd.nebari.local, sign in as admin, not through Keycloak (which doesn't work locally yet). Get the password with:

nic outputs -f local-config.yaml --show-secrets

Add your software pack

With the platform running, install the pack you're building. See Deploy a pack.

If your pack has its own hostname (for example hub.nebari.local), add it to /etc/hosts the same way:

echo "127.0.0.1 hub.nebari.local" | sudo tee -a /etc/hosts

Destroy

To delete the cluster, follow Destroy a cluster. On a local cluster, two things stay behind:

The GitOps repository at ~/.nic/gitops/<project_name>. The next nic deploy reuses it, so delete it for a clean start.
The /etc/hosts line. Remove it if you no longer need it.