--- name: nvidia/doca-setup source: https://app.decimal.ai/s/nvidia-doca-setup@1/SKILL.md source_sha256: ab78e834d2dd --- # DOCA setup **Where to start:** If the user's question is *deployment-shaped* (*"how do I deploy"*, *"how do I run my DOCA workload"*, *"I just got a BlueField, what now"*, *"my code is built, what next"*), walk [`TASKS.md ## recognize`](TASKS.md#recognize) **first**. It is the bundle's front-door: it detects the system shape (host x86 / BlueField Arm bare-metal / DPU-only / fresh laptop), asks the developer the minimal set of questions needed to disambiguate, and routes to the correct downstream skill — the container deployment path ([`doca-container-deployment`](../doca-container-deployment/SKILL.md)), the bare-metal hardware deployment path ([`doca-bare-metal-deployment`](../doca-bare-metal-deployment/SKILL.md)), or the no-hardware fallback ([`TASKS.md ## no-install`](TASKS.md#no-install)). The wrong failure mode is to silently steer every developer onto containers because the agent loaded that skill first; `## recognize` exists to prevent that. If the user does not have DOCA installed yet and the request is not deployment-shaped, jump straight to [`TASKS.md ## no-install`](TASKS.md#no-install) for the NGC container path. Deployment-shaped requests still enter `## recognize` first, which routes fresh-laptop cases to `## no-install`. Otherwise read [`## When to load this skill`](#when-to-load-this-skill) to confirm the question is env-class, then route to the section below that matches the user's intent. ## Example questions this skill answers well The CLASSES this skill is built to handle, each with one worked example. The skill must answer the *class*; the worked example is illustrative. - **"I want to deploy a DOCA workload — what is the right path?"** — worked example: *"I just got a BlueField; my code is built; what now?"* Resolved by the front-door decision tree in [`TASKS.md ## recognize`](TASKS.md#recognize), which detects the system shape, asks the minimum residual question, and routes to either the container or the bare-metal deployment skill. - **"Verify DOCA is installed and healthy."** — worked example: *"Is DOCA Flow actually available on this box?"* Resolved by the install-health snapshot in [`TASKS.md ## test`](TASKS.md#test) plus the version-detection rules in [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes). - **"I do not have DOCA installed — what now?"** — worked example: *"I'm on macOS and want to learn DOCA before I get a BlueField."* Resolved by [`TASKS.md ## no-install`](TASKS.md#no-install) (NGC DOCA container as universal Stage-1). - **"Prepare the build environment for any DOCA library."** — worked example: *"`pkg-config --cflags doca-flow` returns nothing — what's missing?"* Resolved by the build-prep workflow in [`TASKS.md ## configure`](TASKS.md#configure) and the build-class error taxonomy in [`CAPABILITIES.md ## Error taxonomy`](CAPABILITIES.md#error-taxonomy). - **"Prepare the runtime preconditions on a real DPU box."** — worked example: *"hugepages / representors / devlink — what's the minimum set before I run my first DOCA Flow program?"* Resolved by [`TASKS.md ## configure`](TASKS.md#configure) and the runtime observability rules in [`CAPABILITIES.md ## Observability`](CAPABILITIES.md#observability). - **"Diagnose an env-class failure (install / build / runtime)."** — worked example: *"My DOCA Flow program built fine but says `pkg-config` cannot find it at runtime."* Resolved by the layered env-class debug workflow in [`TASKS.md ## debug`](TASKS.md#debug). - **"Change something about the environment safely."** — worked example: *"I want to switch eswitch mode from legacy to switchdev."* Resolved by the safety constraints in [`CAPABILITIES.md ## Safety policy`](CAPABILITIES.md#safety-policy). If the question is library-API-shaped (Flow pipe construction, RDMA queue setup, …) or program-shaped (how to build, modify a sample, debug the program itself), route to [`doca-programming-guide`](../doca-programming-guide/SKILL.md) or the matching library skill instead — env-class only lives here. ## When to load this skill Load this skill when the user is dealing with the **environment around DOCA** — installing it, verifying the install is healthy, preparing the build / runtime preconditions, debugging env-class failures, figuring out *how to reach an install* from a host that doesn't have one yet, or asking a **deployment-shaped question** that hasn't yet been routed (containers vs. bare-metal) — the front-door routing decision lives here. Concretely: - The deployment-shape routing front door: *"I just got a BlueField, what now?"*, *"my code is built, how do I run it?"*, *"how do I deploy this?"* All of these load `## recognize` first so the agent does not silently push the user onto the wrong path. - Verifying that the DOCA install is healthy and that the build environment can find it (`pkg-config`, headers, library paths). - Preparing the runtime: hugepages, `devlink` device visibility, representor enumeration, kernel-module prerequisites. - Diagnosing common setup-class failures: missing `*.pc` file, hugepages not mounted, representor not visible, header-vs-runtime version mismatch. - The *I have no install yet* path: the user is on macOS, Windows, or a Linux box without DOCA, and needs to reach an environment where DOCA is actually installed. The canonical Stage-1 answer is the public **NGC DOCA container** at `nvcr.io/nvidia/doca/doca` (works on any OS that runs Docker; no NVIDIA hardware required for the build / read / learn loop). See [`TASKS.md ## no-install`](TASKS.md#no-install). Do **not** load this skill for: - *"What is DOCA?", "where is the developer guide?", "where is the install layout documented?"* — those are routing questions; use [`doca-public-knowledge-map`](../doca-public-knowledge-map/SKILL.md). - *"How do I derive a custom first application from a sample?", "how do I structure a DOCA build?", "what does `DOCA_ERROR_BAD_STATE` mean?"* — those are **programming-class** questions and live in [`doca-programming-guide`](../doca-programming-guide/SKILL.md), which owns the universal `## modify` (first-app derivation), the canonical `## build` pattern, the universal lifecycle, and the cross-library `DOCA_ERROR_*` taxonomy. - *Library-internal API questions* (Flow pipe construction, RDMA queue setup, etc.) — those belong in the matching library skill (e.g. [`doca-flow`](../libs/doca-flow/SKILL.md)). This skill stops at *"the install is healthy and the env is ready"*; it does not own program semantics. ## What this skill provides This is a **thin loader**. The body keeps only the orientation needed to pick the right next file. The substantive env material lives in two companion files: - `CAPABILITIES.md` — what the install / build / runtime *environment* surface looks like: install profiles (`doca-all`, `doca-ofed`, `doca-networking`), where the build flavors (release vs trace) live on disk and how to point `LD_LIBRARY_PATH` at them, the env-side version-detection rules, the env-class error taxonomy (`pkg-config` not finding `doca-flow`, hugepages not reserved, representors not visible), what a healthy install looks like under observation, and the safety constraints on environment changes (hugepages global, `mlxconfig` reset, eswitch mode change). - `TASKS.md` — env workflows: `recognize` (the front-door system-shape detect + dev-Q decision tree that routes deployment-shaped questions to either container or bare-metal), `configure` (env prep), `test` (install health snapshot), `debug` (env-class layered diagnosis), and `no-install` (the *I have no install yet* procedure with the NGC container as Path 0). Three other anchors (`build`, `modify`, `run`) exist for lint compliance and route to [`doca-programming-guide`](../doca-programming-guide/SKILL.md), which owns those verbs after the env / program split. This skill assumes nothing about whether DOCA is installed — the `## no-install` workflow exists precisely for the *fresh laptop* case. ## Loading order 1. Read this `SKILL.md` and classify the question as programming, knowledge-map, beginner orientation, deployment routing, or environment work. Programming and knowledge-map questions route to their owning skill and stop here. 2. **For beginner orientation**, show the [`TASKS.md ## no-install` Stage 1 vs Stage 2 roadmap](TASKS.md#stage-1-vs-stage-2--open-every-i-am-new-to-doca-answer-with-the-staged-roadmap) before any command. Then route Stage 1/container learning to `## no-install` Path 0 and Stage 2/hardware runtime to `## no-install` Paths A/C, followed by `## recognize` before selecting container versus bare-metal. Ask one clarifying question when the stage is unknown; if it remains unknown or no reply is available in unattended execution, stop with `confirmation_required` and both paths explained rather than guessing. 3. **For deployment routing**, walk [TASKS.md ## recognize](TASKS.md#recognize) first only when the container-versus-bare-metal path is not already established. If it is established, proceed directly to the matching env workflow. 4. **Before a change recommendation on an installed/hardware target**, load the mandatory [Universal verification contract](CAPABILITIES.md#universal-verification-contract) and walk all applicable steps through an auditable green signal. Hardware-touching answers also load the [hardware binding-layer command stanza](CAPABILITIES.md#hardware-binding-layer-command-stanza). The Stage-1 no-hardware path instead uses its own container install/smoke green signal; never fabricate unavailable PCIe, representor, or hardware evidence. 5. **For env workflows — `configure`, `test`, `debug`, and `no-install` — see [TASKS.md](TASKS.md).** The `build`, `modify`, and `run` anchors route to [`doca-programming-guide`](../doca-programming-guide/SKILL.md). 6. Once the env is healthy, hand off to the selected deployment skill, then `doca-programming-guide`, then the matching library skill. Both companion files cross-link to each other and to `doca-public-knowledge-map` whenever the right answer is *"look it up in the public docs or the installed package layout"* rather than *"setup-specific guidance"*. ## Related skills - [`doca-container-deployment`](../doca-container-deployment/SKILL.md) — the container deployment runtime (kubelet standalone + YAML pod-spec drop) for any DOCA service container on BlueField. `## recognize` here routes to this skill when the developer's workload + system shape land on the container path. - [`doca-bare-metal-deployment`](../doca-bare-metal-deployment/SKILL.md) — the bare-metal hardware deployment runtime (host x86 OR BlueField Arm direct launch — systemd / tmux / direct invocation, hardware-resource binding, per-tenant isolation, restart discipline) for a DOCA-linked binary. `## recognize` here routes to this skill when the developer's workload + system shape land on the bare-metal path. - [`doca-public-knowledge-map`](../doca-public-knowledge-map/SKILL.md) — public DOCA documentation routing and the on-disk layout of an installed DOCA package. This skill defers all *"where is X documented"*, *"where on disk is Y"*, and *"how do I check the installed version"* questions to the knowledge-map. - [`doca-programming-guide`](../doca-programming-guide/SKILL.md) — general DOCA programming patterns once the env is healthy: the canonical `pkg-config doca-` build pattern, the universal *derive a custom first app from a sample* workflow (with C / C++ + non-C tracks), the universal lifecycle, and the cross-library `DOCA_ERROR_*` taxonomy. Anything beyond *"is the install healthy and the env ready"* lives there. - [`doca-flow`](../libs/doca-flow/SKILL.md) — DOCA Flow on BlueField. Builds on this skill for env preparation and on `doca-programming-guide` for the universal first-app derivation, then layers Flow-specific overrides on top.