Doca Setup

---
license: Apache-2.0 AND CC-BY-4.0
name: doca-setup
description: >
  Use this skill when the user is dealing with the DOCA environment
  around their workload — verifying an install is healthy, preparing
  the build env (pkg-config, headers, LD_LIBRARY_PATH, hugepages,
  devlink, representors), debugging env-class failures, deciding
  container-vs-bare-metal deployment shape, or reaching a DOCA install
  from a host that doesn't have one yet via the NGC DOCA container
  Stage-1 fallback. Trigger even when the user does not explicitly
  mention "DOCA setup" — typical implicit phrasings include "I just
  got a BlueField, what now", "my code is built, how do I run it",
  "pkg-config can't find doca-flow", "no free 2048 kB hugepages",
  "representor X not found", "I'm on a Mac and want to learn DOCA".
  Refuse and route elsewhere for library API specifics (Flow pipes,
  RDMA queues), the modify-a-sample first-app workflow or DOCA_ERROR_*
  program-side debugging, and "where is X documented" knowledge-map
  questions — those belong to other skills.
metadata:
  kind: library
compatibility: >
  No DOCA install required to read this skill (it is an overlay loaded
  against any DOCA artifact skill); the validation steps within DO
  require a live DOCA install at /opt/mellanox/doca. The agent must
  have a target-host command channel or provide commands for the user
  to run and return their exact output; local shell access must not be
  assumed to reach the target.
---

# 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-<library>` 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.