From 23dd9aa103db17cbc69c3bbc6970c7c449838af0 Mon Sep 17 00:00:00 2001 From: Divya Date: Fri, 29 May 2026 16:36:33 +0530 Subject: [PATCH 01/12] fix: block bots from crawling Mintlify static assets Re-applied on top of current main (original branch fix/robots-txt-block-static-assets was cut from an old initial-commit state and rebasing produced unrelated conflicts in favicon/logo/.mintignore/docs.json). Clarity data shows bots (Apple, OpenAI, Google) spending ~200 requests/week on /mintlify-assets/_next/static/ JS/CSS chunks. These have zero SEO value. Adds custom robots.txt that blocks /mintlify-assets/ while keeping the existing /cdn-cgi/ block and sitemap reference. Co-Authored-By: Claude Opus 4.7 (1M context) --- robots.txt | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 robots.txt diff --git a/robots.txt b/robots.txt new file mode 100644 index 0000000..a2a4eae --- /dev/null +++ b/robots.txt @@ -0,0 +1,5 @@ +User-agent: * +Disallow: /cdn-cgi/ +Disallow: /mintlify-assets/ + +Sitemap: https://docs.tracebloc.io/sitemap.xml From c7d111847d6cec984a5f948fa5025b41407c7052 Mon Sep 17 00:00:00 2001 From: Divya Date: Mon, 1 Jun 2026 15:10:50 +0530 Subject: [PATCH 02/12] docs: make declarative-ingest staging self-contained (issue #131 B/C) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fixes the docs side of data-ingestors#131: - B2 / B1: section 2 of the declarative path linked out for the staging recipe and described `kubectl cp` while the Detailed Setup section (further down on the same page) prescribed a host-path `cp -R`. Replaced section 2 with an inline host-path recipe that matches the Detailed Setup section, and demoted `kubectl cp` to a Note for multi-node / EKS deployments. The recipe now uses a `` subdirectory so the path lines up with the `/data/shared//...` style used in ingest.yaml examples. - C2: section 4 was silent on where CLIENT_ID / CLIENT_PASSWORD come from in the declarative path. Added a sentence noting the ingestor Pod inherits them from the Kubernetes Secret the parent tracebloc/client chart creates in at install time — no creds are passed on the `helm install` line. - C5: section 4 mentioned the run-twice rule only as a trailing parenthetical. Promoted it to bolded prose and added a worked train + test pair (two `helm install` invocations, distinct release names + `table:` + `intent:`) so the rule is concrete. Co-Authored-By: Claude Opus 4.7 (1M context) --- create-use-case/prepare-dataset.mdx | 32 +++++++++++++++++++++++++---- 1 file changed, 28 insertions(+), 4 deletions(-) diff --git a/create-use-case/prepare-dataset.mdx b/create-use-case/prepare-dataset.mdx index 05d77a3..3133093 100644 --- a/create-use-case/prepare-dataset.mdx +++ b/create-use-case/prepare-dataset.mdx @@ -50,7 +50,23 @@ Append `--version ` to pin a specific chart version. ### 2. Stage your data on the cluster's shared PVC -The chart **doesn't transport data into the cluster** — it points at data already accessible to the cluster's shared PVC (`client-pvc` by default, mounted at `/data/shared/` inside the ingestor Pod). Before installing, get your raw files there. The simplest pattern for a small dataset is a throwaway `kubectl cp` Pod that mounts the PVC; for production you'd typically use an init container with cloud-storage sync. Full staging recipe and manifests live in the [client ingestor README](https://github.com/tracebloc/client/blob/develop/ingestor/README.md#stage-your-data-on-the-shared-pvc). +The chart **doesn't transport data into the cluster** — it points at data already accessible to the cluster's shared PVC (`client-pvc` by default, mounted at `/data/shared/` inside the ingestor Pod). Before installing, get your raw files there. + +For a single-node workspace (the default install), the PVC is backed by a host directory the installer created at `~/.tracebloc//data/`. Drop your files into a per-dataset subdirectory: + +```bash +# Host path on the machine where the tracebloc client is installed. +# Pick a per dataset — it becomes the path you reference in ingest.yaml. +mkdir -p ~/.tracebloc//data/ +cp -R LOCAL_PATH/images ~/.tracebloc//data// +cp LOCAL_PATH/labels.csv ~/.tracebloc//data// +``` + +Inside the ingestor Pod those files appear at `/data/shared//...` — that's what you'll put in `ingest.yaml` below. + + +For multi-node or EKS deployments where the PVC isn't backed by a local host path, use a throwaway `kubectl cp` Pod or a cloud-storage init container instead. See the [client ingestor README](https://github.com/tracebloc/client/blob/develop/ingestor/README.md#stage-your-data-on-the-shared-pvc) for those recipes. + ### 3. Write your `ingest.yaml` @@ -71,13 +87,21 @@ The top-level shape (`apiVersion`, `kind`, `category`, `table`, `intent`, `label ### 4. Install once per dataset +The ingestor runs once: validates your data, copies files into the destination directory on the PVC, inserts rows into MySQL, sends metadata to the tracebloc backend, then exits. **Run it twice per dataset** — once with `intent: train`, once with `intent: test` — using distinct `table:` names. The example below shows both releases: + ```bash -helm install my-cats-dogs tracebloc/ingestor \ +# Train release — points at the ingest.yaml from step 3 (table: cats_dogs_train, intent: train) +helm install cats-dogs-train tracebloc/ingestor \ + --namespace \ + --set-file ingestConfig=./ingest-train.yaml + +# Test release — same shape, with table: cats_dogs_test and intent: test +helm install cats-dogs-test tracebloc/ingestor \ --namespace \ - --set-file ingestConfig=./ingest.yaml + --set-file ingestConfig=./ingest-test.yaml ``` -The ingestor runs once: validates your data, copies files into the destination directory on the PVC, inserts rows into MySQL, sends metadata to the tracebloc backend, then exits. Repeat per dataset (one helm release per dataset, with different `table:` and `intent:` for train and test). +Each `helm install` is a separate release (the first argument is the release name), so the two runs don't collide. The ingestor Pod picks up `CLIENT_ID` / `CLIENT_PASSWORD` automatically from the Kubernetes Secret the parent `tracebloc/client` chart created in `` at install time — you don't pass credentials on the `helm install` command. Full chart docs (data-staging recipe, schema, every category, update model, verification, override knobs) → [client ingestor README](https://github.com/tracebloc/client/blob/develop/ingestor/README.md). From dc1e09a8381241e19bb62f882a8fda986a94a217 Mon Sep 17 00:00:00 2001 From: Divya Date: Tue, 2 Jun 2026 14:07:39 +0530 Subject: [PATCH 03/12] docs: address PR #46 review feedback MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Reword overview sentence: "Regardless of where" → "Whether" (cleaner). - Move the `--reset-then-reuse-values` caveat above section 1 so the warning appears before any commands the user could run, and clarify it only applies to upgrades of the parent `tracebloc/client` chart (not the `helm install tracebloc/ingestor` runs in step 4). Co-Authored-By: Claude Opus 4.7 (1M context) --- create-use-case/prepare-dataset.mdx | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/create-use-case/prepare-dataset.mdx b/create-use-case/prepare-dataset.mdx index 3133093..46727b7 100644 --- a/create-use-case/prepare-dataset.mdx +++ b/create-use-case/prepare-dataset.mdx @@ -5,7 +5,7 @@ description: "Learn how to prepare and ingest your datasets into tracebloc using ## Overview -Make your data available to the Kubernetes cluster so it can be used for training and evaluation. Regardless of where your client runs on Azure, AWS, Google Cloud, or a local Minikube setup, the process of ingesting datasets works the same way. +Make your data available to the Kubernetes cluster so it can be used for training and evaluation. Whether your client runs on Azure, AWS, Google Cloud, or a local Minikube setup, the process of ingesting datasets works the same way. The data ingestor is a lightweight service that bridges your raw data and the cluster's persistent storage. It comes with ready-made templates (CSV, images, text) that you can use as starting points and customize for your own dataset. By containerizing the ingestion step, the ingestor validates data format and schema, enforces consistency, and transfers the dataset securely into cluster's SQL storage where it becomes accessible to all training and evaluation jobs. @@ -29,24 +29,24 @@ Start with the declarative method below. Drop down to the custom-template flow o Describe your dataset in ~8 lines of YAML, then `helm install`. The official ingestor image (published as `ghcr.io/tracebloc/ingestor`) runs it. No Dockerfile, no Python script. -### 1. Add the chart repo (one-time) + +**Before you run any commands in this section:** if you installed the client via the one-liner (`bash <(curl -fsSL https://tracebloc.io/i.sh)`), every later `helm upgrade tracebloc/client …` **must** include `--reset-then-reuse-values`, otherwise the upgrade drops the values the installer applied and breaks the workspace: ```bash -helm repo add tracebloc https://tracebloc.github.io/client -helm repo update +helm upgrade tracebloc/client -n --reset-then-reuse-values ``` -The `tracebloc/client` parent chart bootstraps the cluster (jobs-manager, MySQL, RBAC). The `tracebloc/ingestor` subchart submits per-dataset ingestion runs against it. +Append `--version ` to pin a specific chart version. This caveat only affects upgrades of the parent `tracebloc/client` chart, not the `helm install tracebloc/ingestor` runs below. + - -If you installed the client via the one-liner (`bash <(curl -fsSL https://tracebloc.io/i.sh)`), use `--reset-then-reuse-values` so the helm upgrade doesn't drop the values the installer applied: +### 1. Add the chart repo (one-time) ```bash -helm upgrade tracebloc/client -n --reset-then-reuse-values +helm repo add tracebloc https://tracebloc.github.io/client +helm repo update ``` -Append `--version ` to pin a specific chart version. - +The `tracebloc/client` parent chart bootstraps the cluster (jobs-manager, MySQL, RBAC). The `tracebloc/ingestor` subchart submits per-dataset ingestion runs against it. ### 2. Stage your data on the cluster's shared PVC From 340cc90fa13188088dca918abb22644134ba0149 Mon Sep 17 00:00:00 2001 From: Divya Date: Tue, 2 Jun 2026 14:21:40 +0530 Subject: [PATCH 04/12] docs: add masked_language_modeling to templates table The templates table in create-use-case/templates.mdx listed 9 supported tasks but was missing masked_language_modeling, even though the template exists in data-ingestors. Added the row alongside the others. Deep MLM-specific guidance (tokenizer.json requirements, validation, troubleshooting) lives in the data-ingestors template README, where the TokenizerValidator does. Co-Authored-By: Claude Opus 4.7 (1M context) --- create-use-case/templates.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/create-use-case/templates.mdx b/create-use-case/templates.mdx index 5b95571..72ac550 100644 --- a/create-use-case/templates.mdx +++ b/create-use-case/templates.mdx @@ -14,6 +14,7 @@ Each task tracebloc supports comes with a runnable data-ingestion template — a | Keypoint detection | [`templates/keypoint_detection`](https://github.com/tracebloc/data-ingestors/tree/develop/templates/keypoint_detection) | | Semantic segmentation | [`templates/semantic_segmentation`](https://github.com/tracebloc/data-ingestors/tree/develop/templates/semantic_segmentation) | | Text classification | [`templates/text_classification`](https://github.com/tracebloc/data-ingestors/tree/develop/templates/text_classification) | +| Masked language modeling | [`templates/masked_language_modeling`](https://github.com/tracebloc/data-ingestors/tree/develop/templates/masked_language_modeling) | | Tabular classification | [`templates/tabular_classification`](https://github.com/tracebloc/data-ingestors/tree/develop/templates/tabular_classification) | | Tabular regression | [`templates/tabular_regression`](https://github.com/tracebloc/data-ingestors/tree/develop/templates/tabular_regression) | | Time series forecasting | [`templates/time_series_forecasting`](https://github.com/tracebloc/data-ingestors/tree/develop/templates/time_series_forecasting) | From c31c38b665588001db7b37aad3fb7507098984c6 Mon Sep 17 00:00:00 2001 From: Divya Date: Tue, 2 Jun 2026 14:40:22 +0530 Subject: [PATCH 05/12] docs: add helm repo update note for stale-chart validation errors A reviewer hit this on a fresh MLM install: ingest_config validation failed: : Additional properties are not allowed ('sequences' was unexpected) category: 'masked_language_modeling' is not one of [...] Both symptoms point at a stale local Helm chart cache that predates the newer category or schema field. `helm repo update` refreshes the cache and the next `helm install` picks up the current schema. Added a Warning callout in step 4 of the Declarative YAML section, scoped generically (any category / schema field, not just MLM). Co-Authored-By: Claude Opus 4.7 (1M context) --- create-use-case/prepare-dataset.mdx | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/create-use-case/prepare-dataset.mdx b/create-use-case/prepare-dataset.mdx index 46727b7..8743761 100644 --- a/create-use-case/prepare-dataset.mdx +++ b/create-use-case/prepare-dataset.mdx @@ -103,6 +103,16 @@ helm install cats-dogs-test tracebloc/ingestor \ Each `helm install` is a separate release (the first argument is the release name), so the two runs don't collide. The ingestor Pod picks up `CLIENT_ID` / `CLIENT_PASSWORD` automatically from the Kubernetes Secret the parent `tracebloc/client` chart created in `` at install time — you don't pass credentials on the `helm install` command. + +**Validation error like `'' is not one of [...]` or `Additional properties are not allowed`?** Your local Helm chart cache is stale and doesn't know about the newer category or schema field. Refresh it before retrying: + +```bash +helm repo update +``` + +Then re-run the `helm install` command above. + + Full chart docs (data-staging recipe, schema, every category, update model, verification, override knobs) → [client ingestor README](https://github.com/tracebloc/client/blob/develop/ingestor/README.md). ## Custom Python template (advanced) From 31da8733847cbd3efcc5332c0066ad5027ffb007 Mon Sep 17 00:00:00 2001 From: Divya Date: Wed, 3 Jun 2026 12:18:07 +0530 Subject: [PATCH 06/12] =?UTF-8?q?docs:=20correct=20troubleshooting=20note?= =?UTF-8?q?=20=E2=80=94=20server-side=20schema,=20not=20local=20chart=20ca?= =?UTF-8?q?che?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Companion to data-ingestors PR #133 commit 5550d1a. Reviewer (@LukasWodka) pointed out the previous Warning was diagnostically wrong: the schema-validation error comes from jobs-manager's submit-time check against its own bundled schema, not from the local Helm chart index, so `helm repo update` is a no-op. The fix is to upgrade the parent `tracebloc/client` chart so jobs-manager redeploys with the current schema. Co-Authored-By: Claude Opus 4.7 (1M context) --- create-use-case/prepare-dataset.mdx | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/create-use-case/prepare-dataset.mdx b/create-use-case/prepare-dataset.mdx index 8743761..aee27d7 100644 --- a/create-use-case/prepare-dataset.mdx +++ b/create-use-case/prepare-dataset.mdx @@ -104,10 +104,11 @@ helm install cats-dogs-test tracebloc/ingestor \ Each `helm install` is a separate release (the first argument is the release name), so the two runs don't collide. The ingestor Pod picks up `CLIENT_ID` / `CLIENT_PASSWORD` automatically from the Kubernetes Secret the parent `tracebloc/client` chart created in `` at install time — you don't pass credentials on the `helm install` command. -**Validation error like `'' is not one of [...]` or `Additional properties are not allowed`?** Your local Helm chart cache is stale and doesn't know about the newer category or schema field. Refresh it before retrying: +**Validation error like `'' is not one of [...]` or `Additional properties are not allowed ( was unexpected)`?** This comes from the cluster's `jobs-manager` validating against its own bundled schema at submit time — the deployed schema is older than the ingestor image you're installing. `helm repo update` won't fix it (that only refreshes the local chart index, not the running server). The fix is on the cluster side: upgrade the parent chart so jobs-manager redeploys with the current schema. ```bash -helm repo update +helm upgrade tracebloc/client \ + -n --reset-then-reuse-values ``` Then re-run the `helm install` command above. From 15b218c384bf12f9e2506dd06a2f8632ab0a4888 Mon Sep 17 00:00:00 2001 From: Lukas Wuttke Date: Thu, 4 Jun 2026 10:09:33 +0200 Subject: [PATCH 07/12] docs(environment-setup): accuracy fixes + copy/structure polish Independent of the installer namespace change (client#192) -- safe to ship now. Accuracy: - Firewall domains: drop the misleading `github.com`; add ghcr.io (ingestor), raw.githubusercontent.com (scripts), *.github.io (chart repo). - Drop the phantom HTTP_PORT/HTTPS_PORT knobs (installer disables ingress). - Troubleshooting: document the `--diagnose` support bundle. Copy + structure: - EKS: "when to use EKS vs local" callout + back-link to setup-guide; Quick-vs-Detailed signpost; dropped softeners/verbosity. - Configuration: installer-vs-Helm audience signpost; tightened verbose lines. Co-Authored-By: Claude Opus 4.8 --- environment-setup/configuration.mdx | 14 +++++++------- environment-setup/eks-client-deployment-guide.mdx | 13 +++++++++---- environment-setup/setup-guide.mdx | 4 ++-- environment-setup/troubleshooting.mdx | 10 ++++++++++ 4 files changed, 28 insertions(+), 13 deletions(-) diff --git a/environment-setup/configuration.mdx b/environment-setup/configuration.mdx index d626845..b09faa4 100644 --- a/environment-setup/configuration.mdx +++ b/environment-setup/configuration.mdx @@ -3,11 +3,13 @@ title: "Configuration" description: "Customize your tracebloc workspace — environment variables, cluster management, GPU support, and manual Helm deployment." --- -The installer uses sensible defaults. This page covers everything you can change — from cluster naming and port mapping to GPU configuration, manual Helm deployment, and day-to-day cluster management. +The installer uses sensible defaults; this page covers what you can change. + +**Installed with the one-liner?** See [Installer Options](#installer-options), [Cluster Management](#cluster-management), and [GPU Support](#gpu-support). **Deploying into your own cluster with Helm** (EKS, AKS, bare-metal)? Jump to [Manual Deployment](#manual-deployment). ## Installer Options -Override defaults by setting environment variables before the install command. Useful when you need a custom cluster name, multiple worker nodes, or non-standard ports. +Override defaults by setting environment variables before the install command. Useful for a custom cluster name, extra worker nodes, or a different data directory. | Variable | Default | Description | |----------|---------|-------------| @@ -15,8 +17,6 @@ Override defaults by setting environment variables before the install command. U | `SERVERS` | `1` | Number of control-plane nodes | | `AGENTS` | `1` | Number of worker nodes | | `K8S_VERSION` | `v1.29.4-k3s1` | k3s image tag | -| `HTTP_PORT` | `80` | Host port mapped to cluster HTTP ingress | -| `HTTPS_PORT` | `443` | Host port mapped to cluster HTTPS ingress | | `HOST_DATA_DIR` | `~/.tracebloc` | Persistent data directory on host | Example — custom cluster name with two worker nodes: @@ -64,7 +64,7 @@ Install logs are saved to `~/.tracebloc/install-*.log`. ## GPU Support -The installer auto-detects GPU hardware and configures the cluster accordingly. No manual setup required on Linux — the installer handles drivers, container toolkit, and Kubernetes device plugin. +GPU is automatic on Linux — the installer detects your hardware and sets up drivers, the container toolkit, and the Kubernetes device plugin. ### NVIDIA (Linux) @@ -94,7 +94,7 @@ The installer does **not** install GPU drivers on Windows. Pre-install NVIDIA dr Skip the installer entirely. Use this if you already have a Kubernetes cluster, need custom resource limits, or want full control over the Helm deployment. -A single unified chart — **`tracebloc/client`** — supports AKS, EKS, bare-metal, and OpenShift. Platform behaviour is selected via values overrides; reference defaults live in the repo at [`client/ci/{aks,eks,bm,oc}-values.yaml`](https://github.com/tracebloc/client/tree/main/client/ci). +A single chart — **`tracebloc/client`** — supports AKS, EKS, bare-metal, and OpenShift; choose your platform via values overrides. Reference defaults live at [`client/ci/{aks,eks,bm,oc}-values.yaml`](https://github.com/tracebloc/client/tree/main/client/ci). ### Add the Helm repository @@ -266,7 +266,7 @@ env: #### Auto-upgrade (on by default) -Releases of chart `1.3.0+` install a `-auto-upgrade` CronJob that polls `https://tracebloc.github.io/client` daily and runs `helm upgrade --reset-then-reuse-values` whenever a newer chart version is published. Closes [tracebloc/client#69](https://github.com/tracebloc/client/issues/69) — older deployed clients no longer drift from the latest secure release. +Releases of chart `1.3.0+` install a `-auto-upgrade` CronJob that polls `https://tracebloc.github.io/client` daily and runs `helm upgrade --reset-then-reuse-values` whenever a newer chart version is published — so clients auto-update instead of staying pinned to the version they were installed with. ```yaml autoUpgrade: diff --git a/environment-setup/eks-client-deployment-guide.mdx b/environment-setup/eks-client-deployment-guide.mdx index bde8421..140bb7a 100644 --- a/environment-setup/eks-client-deployment-guide.mdx +++ b/environment-setup/eks-client-deployment-guide.mdx @@ -5,12 +5,15 @@ description: "Step-by-step guide to deploy Tracebloc on Amazon EKS. Build a prod ## Overview + +**Use EKS for production** — multi-node, autoscaling, or shared GPU clusters on AWS. For a single machine (a laptop or one server), the [local installer](/environment-setup/setup-guide) is simpler and faster. + Running machine learning workloads in the cloud often requires a reliable, secure, and scalable infrastructure—yet setting it up can be complex. This guide walks you through building a complete Amazon EKS (Elastic Kubernetes Service) environment from scratch using the AWS CLI. By following these steps, you'll create a production-ready foundation with networking, GPU-optional compute, storage, and security fully aligned with AWS and Kubernetes best practices. Once the infrastructure is in place, you'll deploy and configure the tracebloc client to securely train and benchmark AI models. This setup ensures that your proprietary data stays within your environment, while still allowing external AI models to be tested and fine-tuned in a controlled, isolated way. The result: a scalable, secure platform for high-performance ML workloads that accelerates collaboration with external experts while maintaining full control over your data and IP. -The entire setup can be completed in about 1–2 hours. +The entire setup takes ~1–2 hours. If the cluster is already up and you are just adding another client to it, skip the cluster-creation steps and go straight to ["Client Configuration"](#5-client-configuration). @@ -44,7 +47,7 @@ aws configure set region eu-central-1 ``` #### Required Permissions -Your AWS user/role should have permissions for: +Requires permissions for: - Amazon EKS cluster management - VPC and networking resources - EC2 instances and security groups @@ -137,6 +140,8 @@ Together, these measures ensure that external models can be deployed safely into ## Quick Setup +Quick Setup runs an automated script that builds the whole cluster in one go. Want step-by-step control (or to customize networking)? Use [Detailed Setup](#detailed-setup) instead. + ### Purpose Spin up a production-ready EKS baseline (VPC, subnets, internet gateway, EKS cluster, managed nodegroup, EFS + CSI driver) in one go. Includes basic validation, colored logging, and a cleanup mode. @@ -167,7 +172,7 @@ Run `./setup_eks.sh cleanup` to remove cluster, nodegroup, EFS, subnets, gateway - **Costs**: This creates billable resources (EC2, EKS, EFS, data transfer). Remove when not needed. - **Network model**: Subnets are configured to auto-assign public IPs for simplicity. Adjust to private subnets + NAT as needed. - **Kubernetes version**: The script requests `--kubernetes-version 1.32`; update if your region/account supports a different current version. -- **Security hardening**: Treat this as a solid baseline; adapt SGs, private subnets, IRSA, and PodSecurity/OPA as required by your environment. +- **Security hardening**: This is a production baseline; harden further for your environment (security groups, private subnets, IRSA, Pod Security/OPA). If you prefer more control over your setup and want to customize the environment to your needs, follow the step-by-step guide below. @@ -454,7 +459,7 @@ Creates a nodegroup with `t3.medium` instances (2 vCPUs, 4 GiB memory) spread ac #### Training Nodegroup -This group runs your ML training workloads and **must be sized appropriately** to provide sufficient memory and compute. Consider dataset size, model type, the number of parallel workloads and whether GPU acceleration is needed. Select instance types and scaling parameters carefully, based on the kind of models you expect to train and the resources they demand. +This group runs your ML training workloads — size it for your dataset, model type, number of parallel workloads, and whether you need GPUs. Refer to the [EC2 instance types list](https://aws.amazon.com/ec2/instance-types) and [EKS managed nodegroups docs](https://docs.aws.amazon.com/eks/latest/userguide/create-managed-node-group.html) for guidance. diff --git a/environment-setup/setup-guide.mdx b/environment-setup/setup-guide.mdx index 9ba80e6..e1431e9 100644 --- a/environment-setup/setup-guide.mdx +++ b/environment-setup/setup-guide.mdx @@ -23,7 +23,7 @@ The installer runs on any modern machine (one host per workspace). These are the **Supported platforms:** macOS (Intel & Apple Silicon) · Linux (x86_64 & arm64) · Windows (x86_64 & arm64) -**Outbound access needed:** The installer downloads container images and connects to the tracebloc platform. Make sure your network allows traffic to `*.docker.io`, `*.tracebloc.io`, `github.com`, and `pypi.org`. +**Outbound access needed:** The installer pulls container images, the install scripts, and the Helm chart, then connects to the tracebloc platform. Allow traffic to `*.docker.io`, `ghcr.io`, `raw.githubusercontent.com`, `*.github.io`, `*.tracebloc.io`, and `pypi.org`. --- @@ -123,7 +123,7 @@ To upgrade a one-liner install later, run `helm upgrade tracebloc/cl ### GPU Support -The installer auto-detects GPU hardware and configures the cluster accordingly: +The installer detects your GPU and configures the cluster: - **Linux (NVIDIA/AMD)** — drivers, container toolkit, and Kubernetes device plugin are installed automatically. A reboot may be required after driver installation. - **macOS** — CPU-only. For GPU workloads, deploy on a Linux machine or use [AWS (EKS)](/environment-setup/eks-client-deployment-guide). diff --git a/environment-setup/troubleshooting.mdx b/environment-setup/troubleshooting.mdx index 2f5ac9c..5d72ae8 100644 --- a/environment-setup/troubleshooting.mdx +++ b/environment-setup/troubleshooting.mdx @@ -7,6 +7,16 @@ Most issues fall into a few categories: pods not starting, client not connecting For real-time cluster monitoring, try [k9s](https://k9scli.io/) — run `k9s -n ` to get a live view of pods, logs, and events. + +**Stuck? Generate a support bundle.** Re-run the installer with `--diagnose`: + +```bash +bash <(curl -fsSL https://tracebloc.io/i.sh) --diagnose +``` + +It writes a redacted `~/.tracebloc/tracebloc-diagnose-.tgz` — logs, pod status, and versions with **credentials removed** — that you can send to support. The first line of output shows your client version. + + ## Quick Checks | Symptom | Check | Fix | From 7498a2e60655eeb599894efc4eebd5042e7b87f7 Mon Sep 17 00:00:00 2001 From: Lukas Wuttke Date: Fri, 5 Jun 2026 08:31:06 +0200 Subject: [PATCH 08/12] docs(environment-setup): add Overview + Quick Start mockup pages Design preview for the section restructure (additive -- sits alongside the existing pages). Namespace-agnostic, no #192 dependency. - overview.mdx: trust-boundary Mermaid diagram, lifecycle-as-trust-story, what-stays/leaves table, glossary, "what it touches". - quickstart.mdx: one-liner with expectations, inspect-first path, signed-CLI note, locked-down escape hatch, placeholder for a terminal-cast demo. - docs.json: both added to the top of the Environment Setup nav. Co-Authored-By: Claude Opus 4.8 --- docs.json | 2 + environment-setup/overview.mdx | 88 ++++++++++++++++++++++++++++++++ environment-setup/quickstart.mdx | 80 +++++++++++++++++++++++++++++ 3 files changed, 170 insertions(+) create mode 100644 environment-setup/overview.mdx create mode 100644 environment-setup/quickstart.mdx diff --git a/docs.json b/docs.json index 042d90b..ac94ab9 100644 --- a/docs.json +++ b/docs.json @@ -75,6 +75,8 @@ { "group": "Environment Setup", "pages": [ + "environment-setup/overview", + "environment-setup/quickstart", "environment-setup/setup-guide", "environment-setup/configuration", "environment-setup/eks-client-deployment-guide", diff --git a/environment-setup/overview.mdx b/environment-setup/overview.mdx new file mode 100644 index 0000000..7bdb7b2 --- /dev/null +++ b/environment-setup/overview.mdx @@ -0,0 +1,88 @@ +--- +title: "Overview" +description: "How tracebloc runs on your infrastructure — and why your data never leaves it." +--- + +**Models come to your data — your data never leaves your infrastructure.** You run a tracebloc *client* on your own hardware. Contributors submit models that are scanned and run in isolation against your data, on your machines. Only metrics and trained weights ever leave. + +## The trust boundary + +```mermaid +flowchart LR + subgraph YOURS["Your infrastructure"] + DATA["Your datasets — raw data"] + CLIENT["tracebloc client"] + TRAIN["Isolated training"] + DATA --> TRAIN + CLIENT --> TRAIN + end + CONTRIB["Contributors"] -->|submit models| PLATFORM["tracebloc platform"] + PLATFORM -->|scanned models in| CLIENT + CLIENT -->|"metrics + weights out — TLS, outbound-only"| PLATFORM + style YOURS fill:#f2fafc,stroke:#0184A3,stroke-width:2px + style DATA fill:#e6f6fb,stroke:#0184A3 +``` + +Raw data stays inside the box. The client opens an **outbound-only** connection — nothing reaches in to pull your data out. + +## How it works + + + + One client per machine — a laptop, an on-prem server, or a cloud cluster. It runs a self-contained Kubernetes environment. + + + You ingest datasets locally. Metadata syncs to the platform so contributors can see what's available — **the raw data never moves.** + + + Submitted models are **scanned for vulnerabilities** before anything runs. + + + Training runs in an **isolated container** with restricted network and system access. + + + Evaluation metrics and trained weights flow back out over TLS. Your data does not. + + + +## What stays, what leaves + +| Stays on your infrastructure | Leaves (outbound, TLS) | Enforced by | +|---|---|---| +| Raw training data | Dataset *metadata* (schema, counts) | Per-job container isolation | +| Datasets at rest | Evaluation *metrics* | NetworkPolicy — no data egress from training pods | +| Training compute | Trained model *weights* | Vulnerability scan before any model runs | +| | | TLS on all client ↔ platform traffic | + + +**The mental model:** `1 machine = 1 client = 1 workspace = n datasets`. One deployment per machine; as many datasets inside it as you like. + + +## Vocabulary + +| Term | What it is | +|---|---| +| **Client** | The tracebloc agent running on your infrastructure | +| **Workspace** | Your client's identity on one machine (its Kubernetes namespace) | +| **Dataset** | Data you've staged locally for use cases | +| **Use case** | A task contributors build models for, against your datasets | +| **Contributor** | An external data scientist who submits models — and never sees your raw data | + +## What it touches + +The installer changes only **Docker** and **`~/.tracebloc`** on your host — no system-wide changes. Uninstalling is a single command, and your data is yours throughout. + +## Get started + + + + A running workspace in about 10 minutes, with one command. + + + Deploy on local / k3d, bare-metal, EKS, AKS, or OpenShift. + + + + +Want the guarantees in detail for your security team? See [Security & data handling](/environment-setup/configuration#security). + diff --git a/environment-setup/quickstart.mdx b/environment-setup/quickstart.mdx new file mode 100644 index 0000000..e177031 --- /dev/null +++ b/environment-setup/quickstart.mdx @@ -0,0 +1,80 @@ +--- +title: "Quick Start" +description: "From zero to a running tracebloc workspace in about 10 minutes." +--- + +A running workspace in about 10 minutes, with one command. Deploying on a specific environment instead (EKS, AKS, bare-metal, OpenShift)? See [Deployment environments](/environment-setup/setup-guide). + +## Before you start + +| You need | Minimum | +|---|---| +| A machine | macOS, Linux, or Windows · 4 CPU · 8 GB RAM · 20 GB free disk | +| Docker | Installed and running | +| A tracebloc account | [Sign up free](https://ai.tracebloc.io) — no credit card | + + + + On the [clients page](https://ai.tracebloc.io/clients), click **+** and note your **Client ID** and **password** — you'll enter them during install. + + + + + + ```bash + bash <(curl -fsSL https://tracebloc.io/i.sh) + ``` + + + ```powershell + irm https://tracebloc.io/i.ps1 | iex + ``` + + + + + **▶ Install demo** — a ~90-second terminal recording goes here, showing the one-liner run end to end: prompts → setup steps → summary → the client turning **Online**. *(placeholder)* + + + **What to expect:** about 5 minutes. It asks for your Client ID and password, installs Docker (if missing) and a local Kubernetes cluster, and touches only `~/.tracebloc` and Docker. Safe to re-run anytime. + + + Every install script is open source. Download, inspect, then run: + + ```bash + curl -fsSL https://tracebloc.io/i.sh -o install.sh + less install.sh # review it + bash install.sh + ``` + + Source: [github.com/tracebloc/client](https://github.com/tracebloc/client/blob/main/scripts/install.sh). Release binaries are cosign-signed, so you can verify their signature before trusting them. + + + + + ```bash + kubectl get pods -A + ``` + + Look for the tracebloc pods (`mysql-client`, `…-jobs-manager`, `…-requests-proxy`) in `Running` state. Then open your [clients page](https://ai.tracebloc.io/clients) — the client should show **Online**. + + + + +**What changed on your machine** — only Docker and `~/.tracebloc`. To remove everything: `k3d cluster delete tracebloc`. + + +## Locked-down environment? + +If your security policy forbids piping scripts from the internet, skip the one-liner and [deploy with Helm](/environment-setup/configuration#manual-deployment) instead — same result, full control over every step. + +## What's next + + + + Ingest data so contributors can build models against it. + + + Define a task and invite contributors. + + From a5e6ca3edabc0c4c50bc657daee9cc7d5fa28297 Mon Sep 17 00:00:00 2001 From: Lukas Wuttke Date: Fri, 5 Jun 2026 08:54:59 +0200 Subject: [PATCH 09/12] docs: revise Overview + Quick Start per review; add TERMINOLOGY.md - TERMINOLOGY.md (repo root): seed terminology sheet -- preferred/avoid terms, words to retire, open questions (client vs workspace). Lukas owns + extends. - overview: fuller "how it works" (deploy -> ingest -> use case -> whitelist contributors -> submit/train -> results only); weights shared only if the owner allows (admin panel); fixed the client definition; dropped "box". - quickstart: "no Docker/Kubernetes knowledge needed" reassurance (the installer installs Docker); lowered specs to 2 CPU / 4 GB RAM (preflight only warns, never hard-fails on RAM/CPU). - setup-guide: same spec correction (4->2 CPU, 8->4 GB RAM). Co-Authored-By: Claude Opus 4.8 --- TERMINOLOGY.md | 43 ++++++++++++++++++++++++++++ environment-setup/overview.mdx | 47 +++++++++++++++++-------------- environment-setup/quickstart.mdx | 9 ++++-- environment-setup/setup-guide.mdx | 4 +-- 4 files changed, 78 insertions(+), 25 deletions(-) create mode 100644 TERMINOLOGY.md diff --git a/TERMINOLOGY.md b/TERMINOLOGY.md new file mode 100644 index 0000000..781af0f --- /dev/null +++ b/TERMINOLOGY.md @@ -0,0 +1,43 @@ +# tracebloc terminology + +The single source of truth for the words we use — in the product UI, docs, website, decks, and support. One concept, one word. The goal: every person and every page names things the same way. + +> **Status: seed.** Lukas owns this file. Add terms as they come up; we run it against the team so we stay consistent. The **open questions** at the bottom need a decision before we hard-enforce them. + +## How to use it + +- Use the **Preferred** term. Avoid everything in **Don't use**. +- One concept = one word. If two words mean the same thing, we pick one and retire the other. +- Applies everywhere customer- or team-facing: docs, app UI, website, decks, support replies, and code-facing copy (comments, log lines). + +## Core terms + +| Concept | Preferred | Don't use | Definition | +|---|---|---|---| +| Our software on the user's infra | **client** | agent, node, box, instance | tracebloc's software running on your own infrastructure — your private AI workspace, where you invite contributors to train models on your data. | +| The user's deployed environment | **workspace** | environment, deployment, "the install" | Your private, dedicated AI workspace on one machine (the client plus your data). | +| The hosted tracebloc service | **the platform** | the cloud, the server, the backend, SaaS | The hosted side (ai.tracebloc.io) that contributors connect through. | +| The user's own servers / laptop | **your infrastructure** | your box, your environment, on-prem (as a noun) | The hardware the workspace runs on — owned and controlled by the user. | +| The person who deploys & owns it | **workspace owner** | admin, host, customer, "the user" | The person who deploys the workspace, ingests data, creates use cases, and controls what's shared. | +| The invited model builder | **contributor** | vendor, participant, expert, "the user" | An invited, whitelisted data scientist who submits and trains models — and never sees the raw data. | +| The collaborative task | **use case** | project, challenge, competition | A task defined from your datasets that contributors build models for. | +| The user's data | **dataset** | data source, "data set" (two words) | Training and test data ingested and staged locally. | +| Bringing data in | **ingest** | upload, import, load | Staging a dataset locally for use cases. (Raw data never leaves your infrastructure.) | +| Connection status | **Online / Offline** | connected/disconnected, up/down | Whether the client has an active secure connection to the platform. | + +## Words to retire + +- **"box"** — casual and vague. Say **your infrastructure**. +- **"the cloud"** — implies the data leaves. Say **the platform** (hosted side) or **your infrastructure** (their side). +- **"upload your data"** — implies the data leaves. Say **ingest** / **stage**. +- **"vendor"** for model builders — say **contributor**. +- **"Tracebloc"** capitalized mid-sentence — the brand is lowercase **tracebloc** (except at the start of a sentence or in titles). + +## Open questions (decide before enforcing) + +1. **client vs. workspace** — the big one; we currently use both for "the thing on your infra." Options: + - **(a)** *workspace* = the user-facing concept ("your private AI workspace"); *client* = the registered object on the platform (has a **Client ID**, shows **Online/Offline**). Framing: "you deploy your workspace; it connects as a client." + - **(b)** Use *workspace* everywhere user-facing; keep *client* only in **Client ID**. + - Pick one — docs and UI follow it. +2. **workspace owner vs. admin vs. data owner** — what do we call the deploying person, especially in the UI ("admin panel")? +3. **contributor vs. data scientist** — is *contributor* the term in both product and marketing? diff --git a/environment-setup/overview.mdx b/environment-setup/overview.mdx index 7bdb7b2..5c7cf72 100644 --- a/environment-setup/overview.mdx +++ b/environment-setup/overview.mdx @@ -3,7 +3,7 @@ title: "Overview" description: "How tracebloc runs on your infrastructure — and why your data never leaves it." --- -**Models come to your data — your data never leaves your infrastructure.** You run a tracebloc *client* on your own hardware. Contributors submit models that are scanned and run in isolation against your data, on your machines. Only metrics and trained weights ever leave. +**Models come to your data — your data never leaves your infrastructure.** You run a tracebloc *client* on your own hardware. Contributors submit models that are scanned and run in isolation against your data, on your machines. Only results leave — and trained model weights only if you choose to share them. ## The trust boundary @@ -18,41 +18,46 @@ flowchart LR end CONTRIB["Contributors"] -->|submit models| PLATFORM["tracebloc platform"] PLATFORM -->|scanned models in| CLIENT - CLIENT -->|"metrics + weights out — TLS, outbound-only"| PLATFORM + CLIENT -->|"results out — TLS, outbound-only"| PLATFORM style YOURS fill:#f2fafc,stroke:#0184A3,stroke-width:2px style DATA fill:#e6f6fb,stroke:#0184A3 ``` -Raw data stays inside the box. The client opens an **outbound-only** connection — nothing reaches in to pull your data out. +Raw data stays inside your infrastructure. The client opens an **outbound-only** connection — nothing reaches in to pull your data out. ## How it works - - One client per machine — a laptop, an on-prem server, or a cloud cluster. It runs a self-contained Kubernetes environment. + + One command sets up your private workspace on your own infrastructure — a laptop, an on-prem server, or a cloud cluster. - - You ingest datasets locally. Metadata syncs to the platform so contributors can see what's available — **the raw data never moves.** + + Stage your training and test data locally. Metadata syncs to the platform so contributors can see what's available — **the raw data never moves.** - - Submitted models are **scanned for vulnerabilities** before anything runs. + + Define a use case from your datasets and set how submitted models are evaluated. - - Training runs in an **isolated container** with restricted network and system access. + + Whitelist contributors by email. Only the people you invite can take part. - - Evaluation metrics and trained weights flow back out over TLS. Your data does not. + + Each model is **scanned for vulnerabilities**, then trains against your data in an **isolated container**, on your hardware. + + + Training and evaluation results flow back to you over TLS. Trained model weights are shared **only if you choose to** — you control that in the admin panel. ## What stays, what leaves -| Stays on your infrastructure | Leaves (outbound, TLS) | Enforced by | -|---|---|---| -| Raw training data | Dataset *metadata* (schema, counts) | Per-job container isolation | -| Datasets at rest | Evaluation *metrics* | NetworkPolicy — no data egress from training pods | -| Training compute | Trained model *weights* | Vulnerability scan before any model runs | -| | | TLS on all client ↔ platform traffic | +| Data | Shared with the platform? | +|---|---| +| Raw training & test data | **Never** — it stays on your infrastructure | +| Dataset metadata (schema, row counts) | Yes — so contributors know what's available | +| Training & evaluation results | Yes — the metrics models are judged on | +| Trained model weights | **Only if you allow it** — your choice per collaboration, set in the admin panel | + +Enforced by per-job container isolation, a NetworkPolicy that blocks data egress from training pods, a vulnerability scan before any model runs, and TLS on all traffic. **The mental model:** `1 machine = 1 client = 1 workspace = n datasets`. One deployment per machine; as many datasets inside it as you like. @@ -62,8 +67,8 @@ Raw data stays inside the box. The client opens an **outbound-only** connection | Term | What it is | |---|---| -| **Client** | The tracebloc agent running on your infrastructure | -| **Workspace** | Your client's identity on one machine (its Kubernetes namespace) | +| **Client** | Your private AI workspace — tracebloc's software running on your own infrastructure, where you invite contributors to train models on your data | +| **Workspace** | The everyday name for your client — your dedicated, private AI environment on one machine | | **Dataset** | Data you've staged locally for use cases | | **Use case** | A task contributors build models for, against your datasets | | **Contributor** | An external data scientist who submits models — and never sees your raw data | diff --git a/environment-setup/quickstart.mdx b/environment-setup/quickstart.mdx index e177031..20d07e5 100644 --- a/environment-setup/quickstart.mdx +++ b/environment-setup/quickstart.mdx @@ -5,14 +5,19 @@ description: "From zero to a running tracebloc workspace in about 10 minutes." A running workspace in about 10 minutes, with one command. Deploying on a specific environment instead (EKS, AKS, bare-metal, OpenShift)? See [Deployment environments](/environment-setup/setup-guide). + +**No Docker or Kubernetes knowledge needed.** The installer sets up the whole container stack for you — on macOS and Linux it even installs Docker if it's missing. You just need a machine. + + ## Before you start | You need | Minimum | |---|---| -| A machine | macOS, Linux, or Windows · 4 CPU · 8 GB RAM · 20 GB free disk | -| Docker | Installed and running | +| A machine | macOS, Linux, or Windows · 2 CPU · 4 GB RAM · 20 GB free disk | | A tracebloc account | [Sign up free](https://ai.tracebloc.io) — no credit card | +The installer runs below these too — it only warns, and more RAM mainly helps once models train. + On the [clients page](https://ai.tracebloc.io/clients), click **+** and note your **Client ID** and **password** — you'll enter them during install. diff --git a/environment-setup/setup-guide.mdx b/environment-setup/setup-guide.mdx index e1431e9..a9eb9bb 100644 --- a/environment-setup/setup-guide.mdx +++ b/environment-setup/setup-guide.mdx @@ -17,8 +17,8 @@ The installer runs on any modern machine (one host per workspace). These are the | | Minimum | Recommended | |---|---------|-------------| -| **CPU** | 4 cores | 8+ cores | -| **RAM** | 8 GB | 16+ GB | +| **CPU** | 2 cores | 8+ cores | +| **RAM** | 4 GB | 16+ GB | | **Disk** | 20 GB free | 50+ GB free | **Supported platforms:** macOS (Intel & Apple Silicon) · Linux (x86_64 & arm64) · Windows (x86_64 & arm64) From 676ea83a471767f42bcde1751d6cbd95f0c10981 Mon Sep 17 00:00:00 2001 From: Lukas Wuttke Date: Fri, 5 Jun 2026 10:13:36 +0200 Subject: [PATCH 10/12] docs(environment-setup): build out Deployment environments, Operations, Security (mockup) Additive preview of the restructured section on develop: - deployment-environments: landing -- comparison table + the shared 6-heading template. - deploy-local / deploy-bare-metal / deploy-aks / deploy-openshift: per-environment guides on the template (EKS reuses the existing detailed guide). - operations: day-2 -- version, health, logs, stop/start, upgrade, rollback, move, uninstall, backup. - security: dedicated "Security & data handling" page for the data-first audience. - docs.json: nested "Deployment environments" group + Operations/Security; Overview and Quick Start now link to the new landing. Co-Authored-By: Claude Opus 4.8 --- docs.json | 18 ++++- environment-setup/deploy-aks.mdx | 54 +++++++++++++ environment-setup/deploy-bare-metal.mdx | 58 +++++++++++++ environment-setup/deploy-local.mdx | 55 +++++++++++++ environment-setup/deploy-openshift.mdx | 58 +++++++++++++ environment-setup/deployment-environments.mdx | 28 +++++++ environment-setup/operations.mdx | 81 +++++++++++++++++++ environment-setup/overview.mdx | 2 +- environment-setup/quickstart.mdx | 2 +- environment-setup/security.mdx | 37 +++++++++ 10 files changed, 388 insertions(+), 5 deletions(-) create mode 100644 environment-setup/deploy-aks.mdx create mode 100644 environment-setup/deploy-bare-metal.mdx create mode 100644 environment-setup/deploy-local.mdx create mode 100644 environment-setup/deploy-openshift.mdx create mode 100644 environment-setup/deployment-environments.mdx create mode 100644 environment-setup/operations.mdx create mode 100644 environment-setup/security.mdx diff --git a/docs.json b/docs.json index ac94ab9..6572ffc 100644 --- a/docs.json +++ b/docs.json @@ -77,10 +77,22 @@ "pages": [ "environment-setup/overview", "environment-setup/quickstart", - "environment-setup/setup-guide", + { + "group": "Deployment environments", + "pages": [ + "environment-setup/deployment-environments", + "environment-setup/deploy-local", + "environment-setup/deploy-bare-metal", + "environment-setup/eks-client-deployment-guide", + "environment-setup/deploy-aks", + "environment-setup/deploy-openshift" + ] + }, "environment-setup/configuration", - "environment-setup/eks-client-deployment-guide", - "environment-setup/troubleshooting" + "environment-setup/operations", + "environment-setup/security", + "environment-setup/troubleshooting", + "environment-setup/setup-guide" ] }, { diff --git a/environment-setup/deploy-aks.mdx b/environment-setup/deploy-aks.mdx new file mode 100644 index 0000000..849b286 --- /dev/null +++ b/environment-setup/deploy-aks.mdx @@ -0,0 +1,54 @@ +--- +title: "Azure AKS" +description: "Deploy the tracebloc client on Azure Kubernetes Service." +--- + +**When to pick it** — You're on Azure and want managed Kubernetes with autoscaling and GPU node pools. + +## Prerequisites + +- An AKS cluster, and `kubectl` pointed at it (`az aks get-credentials …`). +- **Helm 3.x**. +- Your **Client ID** and password from the [clients page](https://ai.tracebloc.io/clients). + +## Install + +```bash +helm repo add tracebloc https://tracebloc.github.io/client +helm repo update +helm show values tracebloc/client > values.yaml # edit per below +helm upgrade --install tracebloc tracebloc/client \ + -n tracebloc --create-namespace -f values.yaml +``` + +Set your credentials in `values.yaml` (see [Configuration → Authentication](/environment-setup/configuration#authentication)). + +## Verify + +```bash +kubectl get pods -n tracebloc +``` + +Pods `Running`, client **Online** on the clients page. + +## Environment-specific config + +Use Azure Files for shared storage: + +```yaml +storageClass: + create: true + provisioner: file.csi.azure.com + parameters: + skuName: Standard_LRS + mountOptions: [dir_mode=0750, file_mode=0640, uid=999, gid=999, mfsymlinks, cache=strict, actimeo=30] +clusterScope: true +``` + +- **NetworkPolicy:** create the AKS cluster with `--network-policy azure` (Azure NPM) or Calico — otherwise the training-pod egress lockdown won't enforce. +- `metrics-server` is bundled on AKS. + +## Production notes + +- Use GPU node pools for training workloads; size requests/limits per job. +- Day-2 upgrades and rollbacks: see [Operations](/environment-setup/operations). diff --git a/environment-setup/deploy-bare-metal.mdx b/environment-setup/deploy-bare-metal.mdx new file mode 100644 index 0000000..4dbbb09 --- /dev/null +++ b/environment-setup/deploy-bare-metal.mdx @@ -0,0 +1,58 @@ +--- +title: "Bare-metal" +description: "Deploy the tracebloc client on your own on-prem Kubernetes cluster." +--- + +**When to pick it** — You already run Kubernetes on-prem (k3s, kubeadm, RKE, …) and want the client on it, with full control over scheduling and storage. + +## Prerequisites + +- A running Kubernetes cluster and `kubectl` access. +- **Helm 3.x**. +- `metrics-server` installed (the resource monitor needs it). +- Your **Client ID** and password from the [clients page](https://ai.tracebloc.io/clients). + +## Install + +```bash +helm repo add tracebloc https://tracebloc.github.io/client +helm repo update +helm show values tracebloc/client > values.yaml # edit per below +helm upgrade --install tracebloc tracebloc/client \ + -n tracebloc --create-namespace -f values.yaml +``` + +Set your credentials in `values.yaml` (see [Configuration → Authentication](/environment-setup/configuration#authentication)). + +## Verify + +```bash +kubectl get pods -n tracebloc +``` + +Pods `Running`, client **Online** on the clients page. + +## Environment-specific config + +Use hostPath-backed volumes: + +```yaml +hostPath: + enabled: true +pvcAccessMode: ReadWriteOnce +storageClass: + create: true + provisioner: kubernetes.io/no-provisioner +namespace: + podSecurity: + enforce: "" # hostPath needs the privileged init-mysql-data container +clusterScope: true +``` + +- **NetworkPolicy** (training-pod egress lockdown) only enforces if your CNI supports it — Calico, Cilium, or kube-router. Flannel alone does **not** enforce. + +## Production notes + +- Schedule MySQL and storage on reliable nodes; back up the data PVCs. +- Size training compute per job via `RESOURCE_REQUESTS` / `RESOURCE_LIMITS` ([Configuration](/environment-setup/configuration#resource-limits-for-training-jobs)). +- Day-2 upgrades and rollbacks: see [Operations](/environment-setup/operations). diff --git a/environment-setup/deploy-local.mdx b/environment-setup/deploy-local.mdx new file mode 100644 index 0000000..f7fc3e4 --- /dev/null +++ b/environment-setup/deploy-local.mdx @@ -0,0 +1,55 @@ +--- +title: "Local / k3d" +description: "Run a tracebloc workspace on a single machine — laptop or on-prem server. Production-capable." +--- + +**When to pick it** — A single machine you own: a laptop to try things, or an on-prem server you run in production. The installer brings up a self-contained Kubernetes cluster (k3d) inside Docker — you don't need a cluster of your own. + +## Prerequisites + +- A machine: macOS, Linux, or Windows · 2 CPU · 4 GB RAM · 20 GB free disk. +- Your **Client ID** and password from the [clients page](https://ai.tracebloc.io/clients). + +That's it — no Docker or Kubernetes knowledge needed. The installer sets up Docker and the cluster for you. + +## Install + + + + ```bash + bash <(curl -fsSL https://tracebloc.io/i.sh) + ``` + + + ```powershell + irm https://tracebloc.io/i.ps1 | iex + ``` + + + +See [Quick Start](/environment-setup/quickstart) for the full walkthrough, including the inspect-first option. + +## Verify + +```bash +kubectl get pods -A +``` + +The tracebloc pods should be `Running`, and your client should read **Online** on the clients page. + +## Environment-specific config + +Set these as environment variables before the install command (full list in [Configuration](/environment-setup/configuration#installer-options)): + +```bash +CLUSTER_NAME=my-cluster AGENTS=2 HOST_DATA_DIR=/data/tracebloc bash <(curl -fsSL https://tracebloc.io/i.sh) +``` + +GPUs are auto-detected on Linux (NVIDIA/AMD) — drivers, container toolkit, and device plugin are installed for you. + +## Production notes + +- **Local is production-capable.** Point it at a server rather than a laptop and it's a real deployment. +- Your data persists in `HOST_DATA_DIR` across stop/start cycles (see [Operations](/environment-setup/operations)). +- Need more headroom? Re-run the installer on a bigger machine, or add worker nodes with `AGENTS`. +- For multi-node high availability, use [bare-metal](/environment-setup/deploy-bare-metal) or a managed cloud instead. diff --git a/environment-setup/deploy-openshift.mdx b/environment-setup/deploy-openshift.mdx new file mode 100644 index 0000000..5e63b68 --- /dev/null +++ b/environment-setup/deploy-openshift.mdx @@ -0,0 +1,58 @@ +--- +title: "OpenShift" +description: "Deploy the tracebloc client on Red Hat OpenShift or OKD." +--- + +**When to pick it** — You run Red Hat OpenShift (or OKD) and need the client to fit its security model (SCCs, OVN networking). + +## Prerequisites + +- An OpenShift cluster, and `oc` / `kubectl` access. +- **Helm 3.x**. +- Your **Client ID** and password from the [clients page](https://ai.tracebloc.io/clients). + +## Install + +```bash +helm repo add tracebloc https://tracebloc.github.io/client +helm repo update +helm show values tracebloc/client > values.yaml # edit per below +helm upgrade --install tracebloc tracebloc/client \ + -n tracebloc --create-namespace -f values.yaml +``` + +Set your credentials in `values.yaml` (see [Configuration → Authentication](/environment-setup/configuration#authentication)). + +## Verify + +```bash +oc get pods -n tracebloc +``` + +Pods `Running`, client **Online** on the clients page. + +## Environment-specific config + +```yaml +storageClass: + create: false + name: ocs-storagecluster-cephfs +clusterScope: false +openshift: + scc: + enabled: true # SCC for the privileged resource-monitor +networkPolicy: + training: + enabled: true + dnsNamespace: openshift-dns + dnsSelector: + dns.operator.openshift.io/daemonset-dns: default +``` + +- OVN-Kubernetes **enforces** NetworkPolicy by default, so the training-pod egress lockdown works out of the box. +- `metrics-server` is present on OpenShift. + +## Production notes + +- The bundled SCC grants the resource-monitor the host access it needs — review it against your cluster policy. +- Size training compute per job; day-2 management is in [Operations](/environment-setup/operations). diff --git a/environment-setup/deployment-environments.mdx b/environment-setup/deployment-environments.mdx new file mode 100644 index 0000000..d3fc419 --- /dev/null +++ b/environment-setup/deployment-environments.mdx @@ -0,0 +1,28 @@ +--- +title: "Deployment environments" +description: "Run tracebloc anywhere — local, bare-metal, EKS, AKS, or OpenShift. Same chart, same steps, your choice of infrastructure." +--- + +tracebloc runs the same way everywhere: one chart (`tracebloc/client`), one set of steps, your choice of infrastructure. **Local is a first-class production option** — a workspace on an on-prem server is every bit as real as one on a managed cloud cluster. + +## Pick your environment + +| Environment | Runs on | GPU | Best when | +|---|---|---|---| +| [Local / k3d](/environment-setup/deploy-local) | One machine you own | NVIDIA / AMD, auto-detected | A laptop or a single on-prem server — the fastest start | +| [Bare-metal](/environment-setup/deploy-bare-metal) | Your own Kubernetes cluster | Your nodes | You already run on-prem Kubernetes | +| [Amazon EKS](/environment-setup/eks-client-deployment-guide) | AWS (managed) | GPU nodegroups | You're on AWS and want managed, autoscaling compute | +| [Azure AKS](/environment-setup/deploy-aks) | Azure (managed) | GPU node pools | You're on Azure | +| [OpenShift](/environment-setup/deploy-openshift) | OpenShift / OKD | Your nodes | You run Red Hat OpenShift | + + +Just want it running fast on one machine? The [Quick Start](/environment-setup/quickstart) one-liner is the local path with zero configuration. + + +## Every environment, same shape + +Each guide follows the same six headings, so you always know where to look: + +**When to pick it · Prerequisites · Install · Verify · Environment-specific config · Production notes.** + +Adding a new target later (GKE, on-prem k3s, …) means filling the same template. All environments deploy the same chart — see [Configuration](/environment-setup/configuration) for every value, and [Operations](/environment-setup/operations) for day-2 management. diff --git a/environment-setup/operations.mdx b/environment-setup/operations.mdx new file mode 100644 index 0000000..0cd441e --- /dev/null +++ b/environment-setup/operations.mdx @@ -0,0 +1,81 @@ +--- +title: "Operations" +description: "Run, monitor, upgrade, and maintain a tracebloc workspace day to day." +--- + +Everything you do *after* the client is running. Commands assume the default namespace `tracebloc` — substitute yours if you changed it. + +## Which version am I on? + +```bash +helm list -n tracebloc # CHART column shows client- +``` + +The install summary also prints the version, and `--diagnose` reports it on its first line. + +## Health & status + +```bash +kubectl get pods -n tracebloc # all client pods Running? +kubectl get pods -n tracebloc-node-agents # the resource-monitor DaemonSet +``` + +Then check your [clients page](https://ai.tracebloc.io/clients) — the client should read **Online**. + +## Logs + +```bash +kubectl logs -n tracebloc -l app=tracebloc-jobs-manager --tail=200 -f +``` + +## Stop & start (local / k3d) + +Free up your machine without losing anything — data persists between stops. + +```bash +k3d cluster stop tracebloc # frees CPU/RAM +k3d cluster start tracebloc # resume where you left off +``` + +## Upgrade + +The auto-upgrade CronJob keeps the client current by default. To upgrade manually: + +```bash +helm repo update +helm upgrade tracebloc tracebloc/client -n tracebloc --reset-then-reuse-values +``` + +`--reset-then-reuse-values` preserves the values the installer applied. Append `--version ` to pin a specific release. + +## Roll back + +```bash +helm history tracebloc -n tracebloc # find the revision to return to +helm rollback tracebloc -n tracebloc +``` + +## Move to another machine + +The client's identity is its **Client ID**, not the machine. To relocate: run the installer on the new host with the **same Client ID**, then re-ingest your datasets (or copy `~/.tracebloc`). The old host can be uninstalled once the new one shows **Online**. + +## Uninstall + + + + ```bash + k3d cluster delete tracebloc # removes the cluster and the client + ``` + + + ```bash + helm uninstall tracebloc -n tracebloc + ``` + + + +PVCs are annotated `helm.sh/resource-policy: keep`, so your data survives an uninstall. To remove it too: `kubectl delete pvc --all -n tracebloc`. + +## Back up + +Your data lives in the data PVCs (or `~/.tracebloc` on a local install). Back up that directory / those volumes on your normal schedule — tracebloc keeps nothing of yours off your infrastructure. diff --git a/environment-setup/overview.mdx b/environment-setup/overview.mdx index 5c7cf72..9ecb326 100644 --- a/environment-setup/overview.mdx +++ b/environment-setup/overview.mdx @@ -83,7 +83,7 @@ The installer changes only **Docker** and **`~/.tracebloc`** on your host — no A running workspace in about 10 minutes, with one command. - + Deploy on local / k3d, bare-metal, EKS, AKS, or OpenShift. diff --git a/environment-setup/quickstart.mdx b/environment-setup/quickstart.mdx index 20d07e5..d45666a 100644 --- a/environment-setup/quickstart.mdx +++ b/environment-setup/quickstart.mdx @@ -3,7 +3,7 @@ title: "Quick Start" description: "From zero to a running tracebloc workspace in about 10 minutes." --- -A running workspace in about 10 minutes, with one command. Deploying on a specific environment instead (EKS, AKS, bare-metal, OpenShift)? See [Deployment environments](/environment-setup/setup-guide). +A running workspace in about 10 minutes, with one command. Deploying on a specific environment instead (EKS, AKS, bare-metal, OpenShift)? See [Deployment environments](/environment-setup/deployment-environments). **No Docker or Kubernetes knowledge needed.** The installer sets up the whole container stack for you — on macOS and Linux it even installs Docker if it's missing. You just need a machine. diff --git a/environment-setup/security.mdx b/environment-setup/security.mdx new file mode 100644 index 0000000..09d1802 --- /dev/null +++ b/environment-setup/security.mdx @@ -0,0 +1,37 @@ +--- +title: "Security & data handling" +description: "What stays on your infrastructure, what leaves, and how tracebloc enforces it — the page to share with your security team." +--- + +tracebloc is built so your data never has to leave your network. This page is the summary to hand to your security or compliance team. + +## What's shared, what isn't + +| Data | Shared with the platform? | +|---|---| +| Raw training & test data | **Never** — it stays on your infrastructure | +| Dataset metadata (schema, row counts) | Yes — so contributors know what's available | +| Training & evaluation results | Yes — the metrics models are judged on | +| Trained model weights | **Only if you allow it** — your choice per collaboration, set in the admin panel | + +## How it's enforced + +- **Data locality.** Training runs against your data on your hardware. Raw data never crosses the boundary. +- **Isolation.** Each training job runs in its own container with restricted system access; Kubernetes namespaces separate workloads. +- **Network policy.** Training pods are denied data egress — they can't reach MySQL, other pods, or the Kubernetes API. +- **Model scanning.** Submitted models are scanned for vulnerabilities (Bandit) before anything executes. +- **Encryption in transit.** All client ↔ platform traffic is TLS, on an **outbound-only** connection. +- **Access control.** Only contributors you whitelist by email can join a use case. +- **Minimal footprint.** The installer touches only Docker and `~/.tracebloc` — no system-wide changes. + +## You control what leaves + +Trained weights are shared only when you choose to share them. Whom you collaborate with, and whether weights are downloadable, is set in the admin panel — per use case. + +## Support bundles are redacted + +If support asks for diagnostics, `--diagnose` produces a bundle with **credentials removed** (passwords, tokens, and proxy secrets stripped before the archive is written). See [Troubleshooting](/environment-setup/troubleshooting). + +## Outbound access + +The client needs outbound HTTPS to: `*.docker.io`, `ghcr.io`, `raw.githubusercontent.com`, `*.github.io`, `*.tracebloc.io`, and `pypi.org`. Nothing needs to reach *in*. From b3dadc9f68deb04f41f718dd8e7c4ab48f2bb76e Mon Sep 17 00:00:00 2001 From: Lukas Wuttke Date: Fri, 5 Jun 2026 10:34:09 +0200 Subject: [PATCH 11/12] docs(environment-setup): fix jobs-manager log selector (app=manager) Validated against the published chart via `helm template`: the jobs-manager pod label is `app: manager`, so `-l app=tracebloc-jobs-manager` matched no pods. Corrected in operations, configuration, and troubleshooting. Co-Authored-By: Claude Opus 4.8 --- environment-setup/configuration.mdx | 2 +- environment-setup/operations.mdx | 2 +- environment-setup/troubleshooting.mdx | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/environment-setup/configuration.mdx b/environment-setup/configuration.mdx index b09faa4..6e2544b 100644 --- a/environment-setup/configuration.mdx +++ b/environment-setup/configuration.mdx @@ -45,7 +45,7 @@ k3d cluster delete tracebloc The jobs manager is the main tracebloc process. Check its logs when debugging connectivity or job execution issues: ```bash -kubectl logs -n -l app=tracebloc-jobs-manager +kubectl logs -n -l app=manager ``` ### Useful commands diff --git a/environment-setup/operations.mdx b/environment-setup/operations.mdx index 0cd441e..0dbf393 100644 --- a/environment-setup/operations.mdx +++ b/environment-setup/operations.mdx @@ -25,7 +25,7 @@ Then check your [clients page](https://ai.tracebloc.io/clients) — the client s ## Logs ```bash -kubectl logs -n tracebloc -l app=tracebloc-jobs-manager --tail=200 -f +kubectl logs -n tracebloc -l app=manager --tail=200 -f ``` ## Stop & start (local / k3d) diff --git a/environment-setup/troubleshooting.mdx b/environment-setup/troubleshooting.mdx index 5d72ae8..f2fd0ce 100644 --- a/environment-setup/troubleshooting.mdx +++ b/environment-setup/troubleshooting.mdx @@ -22,7 +22,7 @@ It writes a redacted `~/.tracebloc/tracebloc-diagnose-.tgz` — logs, | Symptom | Check | Fix | |---------|-------|-----| | Pods not starting | `kubectl describe pod -n ` | Check resource limits, Docker status | -| Client shows Offline | `kubectl logs -n -l app=tracebloc-jobs-manager` | Verify client ID/password, check network | +| Client shows Offline | `kubectl logs -n -l app=manager` | Verify client ID/password, check network | | Docker not running | `docker info` | Start Docker Desktop or daemon | | Cluster not found | `k3d cluster list` | Re-run the installer | | GPU not detected | `nvidia-smi` | Install NVIDIA drivers, reboot, re-run installer | From d3148ed9b33913cc71d0b67c87516c94c72adc07 Mon Sep 17 00:00:00 2001 From: Lukas Wuttke Date: Fri, 5 Jun 2026 11:05:42 +0200 Subject: [PATCH 12/12] docs(environment-setup): adopt "workspace" terminology; prod-ready cut - Use "workspace" as the user-facing term across the new pages; "client" demoted to "Client ID" only. Keeps tracebloc/client (chart) and the clients page (UI). - Remove the Quick Start video placeholder (re-add when recorded). - Drop the superseded old Setup Guide from the nav. - TERMINOLOGY.md: record the workspace decision (option b). Co-Authored-By: Claude Opus 4.8 --- TERMINOLOGY.md | 9 +++------ docs.json | 3 +-- environment-setup/deploy-aks.mdx | 4 ++-- environment-setup/deploy-bare-metal.mdx | 6 +++--- environment-setup/deploy-local.mdx | 2 +- environment-setup/deploy-openshift.mdx | 6 +++--- environment-setup/operations.mdx | 10 +++++----- environment-setup/overview.mdx | 12 ++++++------ environment-setup/quickstart.mdx | 8 ++------ environment-setup/security.mdx | 4 ++-- 10 files changed, 28 insertions(+), 36 deletions(-) diff --git a/TERMINOLOGY.md b/TERMINOLOGY.md index 781af0f..1b8c81a 100644 --- a/TERMINOLOGY.md +++ b/TERMINOLOGY.md @@ -14,8 +14,8 @@ The single source of truth for the words we use — in the product UI, docs, web | Concept | Preferred | Don't use | Definition | |---|---|---|---| -| Our software on the user's infra | **client** | agent, node, box, instance | tracebloc's software running on your own infrastructure — your private AI workspace, where you invite contributors to train models on your data. | -| The user's deployed environment | **workspace** | environment, deployment, "the install" | Your private, dedicated AI workspace on one machine (the client plus your data). | +| The software you run on your infra (and the environment it gives you) | **workspace** | client (as a noun), agent, node, box, instance, deployment | tracebloc's software running on your own infrastructure — your private, dedicated AI environment, where you invite contributors to train models on your data. | +| The credential that connects it to the platform | **Client ID** | client key, token, API key | Created on the clients page; identifies your workspace to the platform. ("client" survives **only** here, matching the current UI.) | | The hosted tracebloc service | **the platform** | the cloud, the server, the backend, SaaS | The hosted side (ai.tracebloc.io) that contributors connect through. | | The user's own servers / laptop | **your infrastructure** | your box, your environment, on-prem (as a noun) | The hardware the workspace runs on — owned and controlled by the user. | | The person who deploys & owns it | **workspace owner** | admin, host, customer, "the user" | The person who deploys the workspace, ingests data, creates use cases, and controls what's shared. | @@ -35,9 +35,6 @@ The single source of truth for the words we use — in the product UI, docs, web ## Open questions (decide before enforcing) -1. **client vs. workspace** — the big one; we currently use both for "the thing on your infra." Options: - - **(a)** *workspace* = the user-facing concept ("your private AI workspace"); *client* = the registered object on the platform (has a **Client ID**, shows **Online/Offline**). Framing: "you deploy your workspace; it connects as a client." - - **(b)** Use *workspace* everywhere user-facing; keep *client* only in **Client ID**. - - Pick one — docs and UI follow it. +1. ✅ **client vs. workspace — DECIDED 2026-06-05 (Lukas): use _workspace_.** Option (b): *workspace* everywhere user-facing; *client* survives only in **Client ID** (the credential). The Environment Setup docs were swept to match. **Residual gap:** the app UI still shows "client" / "clients page" — a UI rename is the follow-up so docs and product fully agree. 2. **workspace owner vs. admin vs. data owner** — what do we call the deploying person, especially in the UI ("admin panel")? 3. **contributor vs. data scientist** — is *contributor* the term in both product and marketing? diff --git a/docs.json b/docs.json index 6572ffc..c42a987 100644 --- a/docs.json +++ b/docs.json @@ -91,8 +91,7 @@ "environment-setup/configuration", "environment-setup/operations", "environment-setup/security", - "environment-setup/troubleshooting", - "environment-setup/setup-guide" + "environment-setup/troubleshooting" ] }, { diff --git a/environment-setup/deploy-aks.mdx b/environment-setup/deploy-aks.mdx index 849b286..d4b4041 100644 --- a/environment-setup/deploy-aks.mdx +++ b/environment-setup/deploy-aks.mdx @@ -1,6 +1,6 @@ --- title: "Azure AKS" -description: "Deploy the tracebloc client on Azure Kubernetes Service." +description: "Deploy a tracebloc workspace on Azure Kubernetes Service." --- **When to pick it** — You're on Azure and want managed Kubernetes with autoscaling and GPU node pools. @@ -29,7 +29,7 @@ Set your credentials in `values.yaml` (see [Configuration → Authentication](/e kubectl get pods -n tracebloc ``` -Pods `Running`, client **Online** on the clients page. +Pods `Running`, your workspace **Online** on the clients page. ## Environment-specific config diff --git a/environment-setup/deploy-bare-metal.mdx b/environment-setup/deploy-bare-metal.mdx index 4dbbb09..222d1b9 100644 --- a/environment-setup/deploy-bare-metal.mdx +++ b/environment-setup/deploy-bare-metal.mdx @@ -1,9 +1,9 @@ --- title: "Bare-metal" -description: "Deploy the tracebloc client on your own on-prem Kubernetes cluster." +description: "Deploy a tracebloc workspace on your own on-prem Kubernetes cluster." --- -**When to pick it** — You already run Kubernetes on-prem (k3s, kubeadm, RKE, …) and want the client on it, with full control over scheduling and storage. +**When to pick it** — You already run Kubernetes on-prem (k3s, kubeadm, RKE, …) and want a workspace on it, with full control over scheduling and storage. ## Prerequisites @@ -30,7 +30,7 @@ Set your credentials in `values.yaml` (see [Configuration → Authentication](/e kubectl get pods -n tracebloc ``` -Pods `Running`, client **Online** on the clients page. +Pods `Running`, your workspace **Online** on the clients page. ## Environment-specific config diff --git a/environment-setup/deploy-local.mdx b/environment-setup/deploy-local.mdx index f7fc3e4..2fa8e21 100644 --- a/environment-setup/deploy-local.mdx +++ b/environment-setup/deploy-local.mdx @@ -35,7 +35,7 @@ See [Quick Start](/environment-setup/quickstart) for the full walkthrough, inclu kubectl get pods -A ``` -The tracebloc pods should be `Running`, and your client should read **Online** on the clients page. +The tracebloc pods should be `Running`, and your workspace should read **Online** on the clients page. ## Environment-specific config diff --git a/environment-setup/deploy-openshift.mdx b/environment-setup/deploy-openshift.mdx index 5e63b68..e594f0c 100644 --- a/environment-setup/deploy-openshift.mdx +++ b/environment-setup/deploy-openshift.mdx @@ -1,9 +1,9 @@ --- title: "OpenShift" -description: "Deploy the tracebloc client on Red Hat OpenShift or OKD." +description: "Deploy a tracebloc workspace on Red Hat OpenShift or OKD." --- -**When to pick it** — You run Red Hat OpenShift (or OKD) and need the client to fit its security model (SCCs, OVN networking). +**When to pick it** — You run Red Hat OpenShift (or OKD) and need the workspace to fit its security model (SCCs, OVN networking). ## Prerequisites @@ -29,7 +29,7 @@ Set your credentials in `values.yaml` (see [Configuration → Authentication](/e oc get pods -n tracebloc ``` -Pods `Running`, client **Online** on the clients page. +Pods `Running`, your workspace **Online** on the clients page. ## Environment-specific config diff --git a/environment-setup/operations.mdx b/environment-setup/operations.mdx index 0dbf393..e256445 100644 --- a/environment-setup/operations.mdx +++ b/environment-setup/operations.mdx @@ -3,7 +3,7 @@ title: "Operations" description: "Run, monitor, upgrade, and maintain a tracebloc workspace day to day." --- -Everything you do *after* the client is running. Commands assume the default namespace `tracebloc` — substitute yours if you changed it. +Everything you do *after* your workspace is running. Commands assume the default namespace `tracebloc` — substitute yours if you changed it. ## Which version am I on? @@ -16,11 +16,11 @@ The install summary also prints the version, and `--diagnose` reports it on its ## Health & status ```bash -kubectl get pods -n tracebloc # all client pods Running? +kubectl get pods -n tracebloc # all workspace pods Running? kubectl get pods -n tracebloc-node-agents # the resource-monitor DaemonSet ``` -Then check your [clients page](https://ai.tracebloc.io/clients) — the client should read **Online**. +Then check your [clients page](https://ai.tracebloc.io/clients) — your workspace should read **Online**. ## Logs @@ -39,7 +39,7 @@ k3d cluster start tracebloc # resume where you left off ## Upgrade -The auto-upgrade CronJob keeps the client current by default. To upgrade manually: +The auto-upgrade CronJob keeps your workspace current by default. To upgrade manually: ```bash helm repo update @@ -64,7 +64,7 @@ The client's identity is its **Client ID**, not the machine. To relocate: run th ```bash - k3d cluster delete tracebloc # removes the cluster and the client + k3d cluster delete tracebloc # removes the cluster and your workspace ``` diff --git a/environment-setup/overview.mdx b/environment-setup/overview.mdx index 9ecb326..fc9c5f4 100644 --- a/environment-setup/overview.mdx +++ b/environment-setup/overview.mdx @@ -3,7 +3,7 @@ title: "Overview" description: "How tracebloc runs on your infrastructure — and why your data never leaves it." --- -**Models come to your data — your data never leaves your infrastructure.** You run a tracebloc *client* on your own hardware. Contributors submit models that are scanned and run in isolation against your data, on your machines. Only results leave — and trained model weights only if you choose to share them. +**Models come to your data — your data never leaves your infrastructure.** You run a tracebloc *workspace* on your own hardware. Contributors submit models that are scanned and run in isolation against your data, on your machines. Only results leave — and trained model weights only if you choose to share them. ## The trust boundary @@ -11,7 +11,7 @@ description: "How tracebloc runs on your infrastructure — and why your data ne flowchart LR subgraph YOURS["Your infrastructure"] DATA["Your datasets — raw data"] - CLIENT["tracebloc client"] + CLIENT["tracebloc workspace"] TRAIN["Isolated training"] DATA --> TRAIN CLIENT --> TRAIN @@ -23,7 +23,7 @@ flowchart LR style DATA fill:#e6f6fb,stroke:#0184A3 ``` -Raw data stays inside your infrastructure. The client opens an **outbound-only** connection — nothing reaches in to pull your data out. +Raw data stays inside your infrastructure. Your workspace opens an **outbound-only** connection — nothing reaches in to pull your data out. ## How it works @@ -60,15 +60,15 @@ Raw data stays inside your infrastructure. The client opens an **outbound-only** Enforced by per-job container isolation, a NetworkPolicy that blocks data egress from training pods, a vulnerability scan before any model runs, and TLS on all traffic. -**The mental model:** `1 machine = 1 client = 1 workspace = n datasets`. One deployment per machine; as many datasets inside it as you like. +**The mental model:** `1 machine = 1 workspace = n datasets`. One deployment per machine; as many datasets inside it as you like. ## Vocabulary | Term | What it is | |---|---| -| **Client** | Your private AI workspace — tracebloc's software running on your own infrastructure, where you invite contributors to train models on your data | -| **Workspace** | The everyday name for your client — your dedicated, private AI environment on one machine | +| **Workspace** | Your private, dedicated AI environment — tracebloc's software running on your own infrastructure, where you invite contributors to train models on your data | +| **Client ID** | The credential that connects your workspace to the platform (created on the clients page) | | **Dataset** | Data you've staged locally for use cases | | **Use case** | A task contributors build models for, against your datasets | | **Contributor** | An external data scientist who submits models — and never sees your raw data | diff --git a/environment-setup/quickstart.mdx b/environment-setup/quickstart.mdx index d45666a..07d2087 100644 --- a/environment-setup/quickstart.mdx +++ b/environment-setup/quickstart.mdx @@ -19,7 +19,7 @@ A running workspace in about 10 minutes, with one command. Deploying on a specif The installer runs below these too — it only warns, and more RAM mainly helps once models train. - + On the [clients page](https://ai.tracebloc.io/clients), click **+** and note your **Client ID** and **password** — you'll enter them during install. @@ -37,10 +37,6 @@ The installer runs below these too — it only warns, and more RAM mainly helps - - **▶ Install demo** — a ~90-second terminal recording goes here, showing the one-liner run end to end: prompts → setup steps → summary → the client turning **Online**. *(placeholder)* - - **What to expect:** about 5 minutes. It asks for your Client ID and password, installs Docker (if missing) and a local Kubernetes cluster, and touches only `~/.tracebloc` and Docker. Safe to re-run anytime. @@ -61,7 +57,7 @@ The installer runs below these too — it only warns, and more RAM mainly helps kubectl get pods -A ``` - Look for the tracebloc pods (`mysql-client`, `…-jobs-manager`, `…-requests-proxy`) in `Running` state. Then open your [clients page](https://ai.tracebloc.io/clients) — the client should show **Online**. + Look for the tracebloc pods (`mysql-client`, `…-jobs-manager`, `…-requests-proxy`) in `Running` state. Then open your [clients page](https://ai.tracebloc.io/clients) — your workspace should show **Online**. diff --git a/environment-setup/security.mdx b/environment-setup/security.mdx index 09d1802..4aacded 100644 --- a/environment-setup/security.mdx +++ b/environment-setup/security.mdx @@ -20,7 +20,7 @@ tracebloc is built so your data never has to leave your network. This page is th - **Isolation.** Each training job runs in its own container with restricted system access; Kubernetes namespaces separate workloads. - **Network policy.** Training pods are denied data egress — they can't reach MySQL, other pods, or the Kubernetes API. - **Model scanning.** Submitted models are scanned for vulnerabilities (Bandit) before anything executes. -- **Encryption in transit.** All client ↔ platform traffic is TLS, on an **outbound-only** connection. +- **Encryption in transit.** All workspace ↔ platform traffic is TLS, on an **outbound-only** connection. - **Access control.** Only contributors you whitelist by email can join a use case. - **Minimal footprint.** The installer touches only Docker and `~/.tracebloc` — no system-wide changes. @@ -34,4 +34,4 @@ If support asks for diagnostics, `--diagnose` produces a bundle with **credentia ## Outbound access -The client needs outbound HTTPS to: `*.docker.io`, `ghcr.io`, `raw.githubusercontent.com`, `*.github.io`, `*.tracebloc.io`, and `pypi.org`. Nothing needs to reach *in*. +Your workspace needs outbound HTTPS to: `*.docker.io`, `ghcr.io`, `raw.githubusercontent.com`, `*.github.io`, `*.tracebloc.io`, and `pypi.org`. Nothing needs to reach *in*.