From a610d2f35c4100dd241ad1b769e8639ae8cb3060 Mon Sep 17 00:00:00 2001 From: Asad Iqbal Date: Wed, 6 May 2026 15:46:33 +0500 Subject: [PATCH 1/5] docs: fix README Deploy section (Helm not docker), surface in-repo docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Deploy section opened with `docker pull tracebloc/client:latest`, but this repo ships a Helm chart — the actual install is `helm install`. External walkthrough URLs (`/local-linux`, `/local-macos`, `/aws`, `/deployment-overview`) didn't match any path in the tracebloc/docs tree, so they 404. The in-repo documentation (`docs/INSTALL.md`, `docs/MIGRATIONS.md`, `docs/migration-tools/README.md`, `client/MIGRATION.md`) was never linked from the README despite being the operational source of truth. Surgical change — the rest of the README stays as-is: - Replace `docker pull` with `helm repo add` + `helm install` (matches docs/INSTALL.md) - Call out chart version (v1.3.1) and platform support (AKS / EKS / bare-metal / OpenShift) up front - Table linking every in-repo operational doc - Fix external URLs to match actual tracebloc/docs paths (local-deployment-guide-linux, local-deployment-guide-macos, eks-client-deployment-guide, azure-deployment-guide) - Pull NetworkPolicy/CNI prerequisite into a callout Closes #101 Co-Authored-By: Claude Opus 4.7 (1M context) --- README.md | 25 ++++++++++++++++++------- 1 file changed, 18 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index e7f207c..b1eacab 100644 --- a/README.md +++ b/README.md @@ -50,18 +50,29 @@ For the threat model, defense layers, per-platform caveats, operator responsibil ## Deploy +This repo ships the **tracebloc** unified Helm chart (currently `v1.3.1`) — one chart for AKS, EKS, bare-metal, and OpenShift. + ```bash -docker pull tracebloc/client:latest +helm repo add tracebloc https://tracebloc.github.io/client +helm repo update +helm install my-tracebloc tracebloc/tracebloc \ + --namespace tracebloc --create-namespace \ + -f my-values.yaml ``` -Deployment varies by infrastructure. Follow the guide for your setup: +Full deployment guide → **[docs/INSTALL.md](docs/INSTALL.md)** (prerequisites, required values, upgrade & rollback, air-gapped install). + +| Topic | Where to look | +|---|---| +| Production install + required values | [docs/INSTALL.md](docs/INSTALL.md) | +| Threat model & operator responsibilities | [docs/SECURITY.md](docs/SECURITY.md) | +| Migrating from `eks-1.0.x` / `aks-*` charts to `client-1.x` | [docs/MIGRATIONS.md](docs/MIGRATIONS.md) | +| Per-tenant migration runbook | [docs/migration-tools/README.md](docs/migration-tools/README.md) | +| Per-platform value mapping | [client/MIGRATION.md](client/MIGRATION.md) | -- [Deployment overview](https://docs.tracebloc.io/environment-setup/deployment-overview) -- [Local — Linux](https://docs.tracebloc.io/environment-setup/local-linux) -- [Local — macOS](https://docs.tracebloc.io/environment-setup/local-macos) -- [AWS](https://docs.tracebloc.io/environment-setup/aws) +Platform-specific walkthroughs: [Linux](https://docs.tracebloc.io/environment-setup/local-deployment-guide-linux) · [macOS](https://docs.tracebloc.io/environment-setup/local-deployment-guide-macos) · [EKS](https://docs.tracebloc.io/environment-setup/eks-client-deployment-guide) · [Azure / AKS](https://docs.tracebloc.io/environment-setup/azure-deployment-guide) -Full documentation → [docs.tracebloc.io](https://docs.tracebloc.io/) +> **NetworkPolicy required.** The chart's training-pod egress lockdown only takes effect on a CNI that enforces NetworkPolicy. See [SECURITY.md § Per-platform caveats](docs/SECURITY.md#5-per-platform-caveats). ## Links From 885ae1843f59ea4960ba07062f67e481d0bc5cc0 Mon Sep 17 00:00:00 2001 From: Asad Iqbal Date: Wed, 6 May 2026 16:20:46 +0500 Subject: [PATCH 2/5] docs: surface standalone installer in README and INSTALL.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The standalone installer (bash <(curl -fsSL tracebloc.io/i.sh) / irm tracebloc.io/i.ps1 | iex) is the one-command path for evaluation, local dev, and first-time installs — it provisions a cluster, detects GPU drivers, and deploys the client. Today it isn't documented anywhere reachable from this repo, so readers see the multi-step helm install flow as the only option. README: - New "Quick install" subsection at the top of Deploy with macOS/Linux and Windows commands, brief description of what it does, and a pointer to the local helper scripts under scripts/ - Existing helm flow relabeled as "Helm install (production)" — now positioned as the option for existing production clusters docs/INSTALL.md: - Top-of-doc callout pointing at the standalone installer for non-production users - Production-focused content untouched Closes #103 Co-Authored-By: Claude Opus 4.7 (1M context) --- README.md | 22 ++++++++++++++++++++++ docs/INSTALL.md | 7 +++++++ 2 files changed, 29 insertions(+) diff --git a/README.md b/README.md index b1eacab..690fff8 100644 --- a/README.md +++ b/README.md @@ -52,6 +52,28 @@ For the threat model, defense layers, per-platform caveats, operator responsibil This repo ships the **tracebloc** unified Helm chart (currently `v1.3.1`) — one chart for AKS, EKS, bare-metal, and OpenShift. +### Quick install + +A single command provisions a local Kubernetes cluster, auto-detects and installs GPU drivers (NVIDIA or AMD), and deploys the tracebloc client. Best for evaluation, local dev, and first-time installs. + +**macOS / Linux** + +```bash +bash <(curl -fsSL tracebloc.io/i.sh) +``` + +**Windows** *(PowerShell as Administrator)* + +```powershell +irm tracebloc.io/i.ps1 | iex +``` + +The installer pulls helper scripts from this repo at runtime — see [`scripts/install-k8s.sh`](scripts/install-k8s.sh) and [`scripts/install-k8s.ps1`](scripts/install-k8s.ps1). + +### Helm install (production) + +For existing production clusters: + ```bash helm repo add tracebloc https://tracebloc.github.io/client helm repo update diff --git a/docs/INSTALL.md b/docs/INSTALL.md index 151d900..e76e5cd 100644 --- a/docs/INSTALL.md +++ b/docs/INSTALL.md @@ -2,6 +2,13 @@ This guide covers installing the **tracebloc** unified Helm chart (AKS, EKS, bare-metal, OpenShift) in a production-ready way. +> **Just trying it out?** For local dev or a quick evaluation, the standalone installer provisions a cluster, GPU drivers, and the client in a single command: +> +> - **macOS / Linux:** `bash <(curl -fsSL tracebloc.io/i.sh)` +> - **Windows:** `irm tracebloc.io/i.ps1 | iex` *(PowerShell as Administrator)* +> +> See the [README's Quick install section](../README.md#quick-install) for what it does. Continue here if you're deploying into an existing production cluster. + --- ## Prerequisites From e6dbf3fc634500f111a6e3eb37fb7bf64bdc2f7b Mon Sep 17 00:00:00 2001 From: Asad Iqbal Date: Wed, 6 May 2026 16:27:09 +0500 Subject: [PATCH 3/5] =?UTF-8?q?docs:=20reframe=20Quick=20install=20?= =?UTF-8?q?=E2=80=94=20same=20client,=20different=20cluster=20path?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Previous wording ("Best for evaluation, local dev, and first-time installs" / "Just trying it out? For local dev or a quick evaluation") implied the standalone installer produces a lesser/demo client. It doesn't — it produces the same full client, just on a cluster the script provisions for you. Reframes the differentiator around cluster ownership instead of install quality: - README: "Use this when you don't already have a cluster — the result is a full client install, not a demo." Helm subsection retitled from "Helm install (production)" to just "Helm install" with "For existing Kubernetes clusters". - INSTALL.md: callout opens with "Don't have a Kubernetes cluster yet?" and emphasizes "a full tracebloc client". Refs #103 --- README.md | 6 +++--- docs/INSTALL.md | 4 ++-- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 690fff8..68be198 100644 --- a/README.md +++ b/README.md @@ -54,7 +54,7 @@ This repo ships the **tracebloc** unified Helm chart (currently `v1.3.1`) — on ### Quick install -A single command provisions a local Kubernetes cluster, auto-detects and installs GPU drivers (NVIDIA or AMD), and deploys the tracebloc client. Best for evaluation, local dev, and first-time installs. +A single command provisions a Kubernetes cluster, auto-detects and installs GPU drivers (NVIDIA or AMD), and deploys the tracebloc client. Use this when you don't already have a cluster — the result is a full client install, not a demo. **macOS / Linux** @@ -70,9 +70,9 @@ irm tracebloc.io/i.ps1 | iex The installer pulls helper scripts from this repo at runtime — see [`scripts/install-k8s.sh`](scripts/install-k8s.sh) and [`scripts/install-k8s.ps1`](scripts/install-k8s.ps1). -### Helm install (production) +### Helm install -For existing production clusters: +For existing Kubernetes clusters: ```bash helm repo add tracebloc https://tracebloc.github.io/client diff --git a/docs/INSTALL.md b/docs/INSTALL.md index e76e5cd..0acb0bb 100644 --- a/docs/INSTALL.md +++ b/docs/INSTALL.md @@ -2,12 +2,12 @@ This guide covers installing the **tracebloc** unified Helm chart (AKS, EKS, bare-metal, OpenShift) in a production-ready way. -> **Just trying it out?** For local dev or a quick evaluation, the standalone installer provisions a cluster, GPU drivers, and the client in a single command: +> **Don't have a Kubernetes cluster yet?** The standalone installer provisions a cluster, installs GPU drivers, and deploys a full tracebloc client in a single command: > > - **macOS / Linux:** `bash <(curl -fsSL tracebloc.io/i.sh)` > - **Windows:** `irm tracebloc.io/i.ps1 | iex` *(PowerShell as Administrator)* > -> See the [README's Quick install section](../README.md#quick-install) for what it does. Continue here if you're deploying into an existing production cluster. +> See the [README's Quick install section](../README.md#quick-install) for what it does. Continue here if you're deploying into an existing cluster. --- From 9f10e8d4e0b3366036635147b60a522325f1701d Mon Sep 17 00:00:00 2001 From: Asad Iqbal Date: Wed, 6 May 2026 16:32:12 +0500 Subject: [PATCH 4/5] docs: explicit https:// on installer URLs (security) curl and PowerShell's irm both default to HTTP when no scheme is specified, so `curl -fsSL tracebloc.io/i.sh` and `irm tracebloc.io/i.ps1` issue plaintext requests. The downloaded body is piped straight into bash / iex, so a network-level attacker between the user and tracebloc.io could MITM the response and inject arbitrary code. Add explicit `https://` to every installer URL in README.md and docs/INSTALL.md so the request is encrypted from the first byte. Refs #103 --- README.md | 4 ++-- docs/INSTALL.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 68be198..787c113 100644 --- a/README.md +++ b/README.md @@ -59,13 +59,13 @@ A single command provisions a Kubernetes cluster, auto-detects and installs GPU **macOS / Linux** ```bash -bash <(curl -fsSL tracebloc.io/i.sh) +bash <(curl -fsSL https://tracebloc.io/i.sh) ``` **Windows** *(PowerShell as Administrator)* ```powershell -irm tracebloc.io/i.ps1 | iex +irm https://tracebloc.io/i.ps1 | iex ``` The installer pulls helper scripts from this repo at runtime — see [`scripts/install-k8s.sh`](scripts/install-k8s.sh) and [`scripts/install-k8s.ps1`](scripts/install-k8s.ps1). diff --git a/docs/INSTALL.md b/docs/INSTALL.md index 0acb0bb..d556ca8 100644 --- a/docs/INSTALL.md +++ b/docs/INSTALL.md @@ -4,8 +4,8 @@ This guide covers installing the **tracebloc** unified Helm chart (AKS, EKS, bar > **Don't have a Kubernetes cluster yet?** The standalone installer provisions a cluster, installs GPU drivers, and deploys a full tracebloc client in a single command: > -> - **macOS / Linux:** `bash <(curl -fsSL tracebloc.io/i.sh)` -> - **Windows:** `irm tracebloc.io/i.ps1 | iex` *(PowerShell as Administrator)* +> - **macOS / Linux:** `bash <(curl -fsSL https://tracebloc.io/i.sh)` +> - **Windows:** `irm https://tracebloc.io/i.ps1 | iex` *(PowerShell as Administrator)* > > See the [README's Quick install section](../README.md#quick-install) for what it does. Continue here if you're deploying into an existing cluster. From 0c423231048718cacf77860fb24dc8e2d96618cc Mon Sep 17 00:00:00 2001 From: Asad Iqbal Date: Wed, 6 May 2026 17:49:47 +0500 Subject: [PATCH 5/5] docs: drop stale tracebloc-helm-charts references in INSTALL.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The chart was renamed and consolidated into tracebloc/client. The "Publishing the chart (maintainers)" section still referenced tracebloc-helm-charts as a possible alternate development repo, which no longer exists. - Step 1: simplify "the repo that hosts the chart (e.g. tracebloc/client or tracebloc-helm-charts)" → "the tracebloc/client repo". - Step 5 ("If you develop in a different repo..."): removed entirely — there is no other repo. - Trailing **Note:** about the cross-repo workflow: removed for the same reason. Closes #105 --- docs/INSTALL.md | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/docs/INSTALL.md b/docs/INSTALL.md index d556ca8..81690c1 100644 --- a/docs/INSTALL.md +++ b/docs/INSTALL.md @@ -207,7 +207,7 @@ The chart repository used for installation is **[tracebloc/client](https://githu To make the chart available via `helm repo add tracebloc https://tracebloc.github.io/client`: -1. **In the repo that hosts the chart (e.g. tracebloc/client or tracebloc-helm-charts):** +1. **In the tracebloc/client repo:** Enable **GitHub Pages** → **Settings** → **Pages** → **Source**: branch `gh-pages` (root). 2. **Create a release or push a tag** @@ -224,8 +224,6 @@ To make the chart available via `helm repo add tracebloc https://tracebloc.githu 4. **First time only:** ensure the `gh-pages` branch exists. The workflow creates it if missing. -5. **If you develop in a different repo** (e.g. tracebloc-helm-charts): run the release workflow there to build the chart, then copy the generated `tracebloc-.tgz` and updated `index.yaml` into the **tracebloc/client** repo’s `gh-pages` branch so the chart is served at `https://tracebloc.github.io/client`. - After that, users can run: ```bash @@ -233,8 +231,6 @@ helm repo add tracebloc https://tracebloc.github.io/client helm install my-tracebloc tracebloc/tracebloc -n tracebloc -f my-values.yaml ``` -**Note:** If the chart is developed in a different repo (e.g. `tracebloc-helm-charts`), run the release workflow there to produce the `.tgz` and `index.yaml`, then copy the packaged chart and updated index into the `tracebloc/client` repo’s `gh-pages` branch (or run the same release workflow from the client repo) so the chart is served at `https://tracebloc.github.io/client`. - --- ## Pre-install checklist (production)