Doca Setup

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 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),

the bare-metal hardware deployment path

(doca-bare-metal-deployment),

or the no-hardware fallback

(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 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 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, 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 plus the

version-detection rules in

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 (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 and the build-class

error taxonomy in

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 and the runtime

observability rules in

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.

• "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.

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 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.

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.
• *"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, 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). 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, 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

• 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.

• For beginner orientation, show the

TASKS.md ## no-install Stage 1 vs Stage 2 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.

• For deployment routing, walk

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.

• Before a change recommendation on an installed/hardware target,

load the mandatory

Universal verification contract

and walk all applicable steps through an auditable green signal.

Hardware-touching answers also load the

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.

• **For env workflows — configure, test, debug, and

no-install — see TASKS.md.** The build, modify,

and run anchors route to

doca-programming-guide.

• 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 — 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 — 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 — 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 — 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 — 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.