/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 "just
  got a BlueField, what now", "code is built, how to run it",
  "pkg-config can't find doca-flow", "no free 2048 kB hugepages",
  "representor X not found", "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:
  author: NVIDIA <doca-feedback@nvidia.com>
  kind: library
  doca_version: "3.5"
  tags:
    - doca
    - setup
    - environment
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`](references/recognize.md) **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/SKILL.md`), the bare-metal hardware deployment path (`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.

**Do not use this skill for:**

• Defining, validating or writing packet-steering rules (DOCA Flow pipes,

matches, actions, entries), including when the user says the environment and versions are already verified. That belongs to `doca-flow`: name it and stop. Do not run `## recognize`, environment checks or the verification contract for it.

• Other library API work (RDMA queues, Comch channels, ...): the matching

library skill.

• First-app derivation from a sample, build structure, or what a

`DOCA_ERROR_*` means: `doca-programming-guide`.

• *"Where is X documented"*: `doca-public-knowledge-map`.

Examples

The CLASSES this skill is built to handle, each with one worked example. The skill must answer the *class*; the worked example is illustrative.

Instructions

Follow [`## Loading order`](#loading-order). Open `TASKS.md` or `CAPABILITIES.md` as named there. Do not open every companion file.

• **"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`](references/recognize.md), 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 [