/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) — th