Fresh-clone quickstart¶

This path uses only freshly cloned organization repositories. It does not rely on generated files or an older working tree.

1. Clone the repositories¶

export EDGE_WORKSPACE="$PWD/edge-computing-llm"
mkdir -p "$EDGE_WORKSPACE"
cd "$EDGE_WORKSPACE"

for repository in .github edge-llm-tests edge-cli k3s-nvidia-edge \
  llm-observability-stack gguf-observability; do
  git clone "https://github.com/Edge-Computing-LLM/$repository.git"
done

Verify that every implementation checkout is clean:

for repository in edge-llm-tests edge-cli k3s-nvidia-edge \
  llm-observability-stack gguf-observability; do
  git -C "$repository" status --short --branch
done

2. Build the control plane¶

cd "$EDGE_WORKSPACE/edge-cli"
go test ./...
go vet ./...
go build -o bin/edge ./cmd/edge

Create a fresh configuration so an older user configuration cannot select another checkout:

./bin/edge --config "$EDGE_WORKSPACE/edge-cli.yaml" config init

Edit that file so repos.k3sNvidiaEdge and repos.llmObservabilityStack point into $EDGE_WORKSPACE, then verify it:

./bin/edge --config "$EDGE_WORKSPACE/edge-cli.yaml" config show
./bin/edge --config "$EDGE_WORKSPACE/edge-cli.yaml" repo doctor

3. Run preflight and a dry run¶

./bin/edge --config "$EDGE_WORKSPACE/edge-cli.yaml" doctor
./bin/edge --config "$EDGE_WORKSPACE/edge-cli.yaml" --dry-run install all \
  --infra-repo-path "$EDGE_WORKSPACE/k3s-nvidia-edge" \
  --observability-repo-path "$EDGE_WORKSPACE/llm-observability-stack"

Read the rendered commands. Confirm namespaces, release names, values files, and kubeconfig before authorizing mutations.

4. Prepare nested Helm dependencies¶

The observability repository vendors a local kube-prometheus-stack dependency. A fresh checkout must build that nested chart before the root chart:

cd "$EDGE_WORKSPACE/llm-observability-stack"
helm dependency build charts/kube-prometheus-stack
helm dependency build .
helm lint .

Skipping the first command can produce a deceptively successful deployment without Grafana, kube-state-metrics, or node-exporter.

5. Install explicitly¶

For the default supported profile, use edge install all --yes after the dry run. For a model-specific low-VRAM overlay such as Gemma, use the documented two-values Helm command until the CLI exposes a model selector:

helm upgrade --install llm-observability-stack \
  "$EDGE_WORKSPACE/llm-observability-stack" \
  --namespace llm-observability --create-namespace \
  -f "$EDGE_WORKSPACE/llm-observability-stack/values.geforce-940m-k3s.yaml" \
  -f "$EDGE_WORKSPACE/llm-observability-stack/values.gemma-3-1b-geforce-940m-k3s.yaml"

The NVIDIA substrate must already be healthy. Follow NVIDIA substrate when it is not.

6. Verify the result¶

kubectl get nodes
kubectl get pods -A
kubectl get runtimeclass
kubectl get node -o jsonpath='{.items[0].status.allocatable.nvidia\.com/gpu}{"\n"}'
helm list -A

cd "$EDGE_WORKSPACE/edge-cli"
./bin/edge --config "$EDGE_WORKSPACE/edge-cli.yaml" status
./bin/edge --config "$EDGE_WORKSPACE/edge-cli.yaml" validate infra
./bin/edge --config "$EDGE_WORKSPACE/edge-cli.yaml" validate observability

Then run read-only tests and a controlled first inference.

Idempotency

Use helm upgrade --install for repeatable application changes. Never delete namespaces or PVCs merely to retry an install; diagnose the failed ownership layer first.