Doca Bare Metal Deployment

DOCA bare-metal deployment

Where to start: This skill is the bundle's home for *operating*

a DOCA-linked application binary directly on hardware — no

container, no kubelet, no static-pod manifest. It is the parallel

of doca-container-deployment

for the non-container path. If the user has a DOCA-linked binary

they built (per the canonical workflow in

doca-programming-guide)

and they want to know *how to actually run it on the host or on

the BlueField Arm cores correctly*, open

TASKS.md and start at

## configure. If the question is *what

shape does the bare-metal runtime even have and what is the

deployment contract*, start at CAPABILITIES.md.

If the user is not yet sure whether their target system shape is

the container path or the bare-metal path, route the recognition

step to doca-setup first; only return

here once *bare-metal* is the confirmed shape.

Audience

This skill serves **external DOCA developers and operators who

have a DOCA-linked application binary they built and want to run

it directly on hardware** — i.e., people who already have:

• a DOCA-linked application binary they built per

doca-programming-guide ## build,

• a real BlueField NIC and a host that talks to it (the **host

x86** path — DOCA host install on the host talks to the

BlueField NIC over PCIe), OR a BlueField with a console or SSH

to the Arm side (the BlueField Arm bare-metal path — DOCA

installed on the DPU Arm cores; the binary runs there

directly), and

• a desire to RUN that binary directly on the hardware, not

inside a kubelet-standalone-managed container.

It is not for:

• kernel-driver developers contributing to mlx5_* or the

BlueField OS,

• DOCA library contributors (those changes go to the internal

DOCA tree, not to a bare-metal deployment),

• full-Kubernetes-cluster operators managing a fleet of

BlueFields (the bundle covers

doca-container-deployment

for the single-host kubelet-standalone shape; **fleet/production-scale

deployment is fleet-orchestration scope** — route to the orchestration

entry-point in

doca-public-knowledge-map ## Deploying DOCA services at scale

(DPF / Network Operator / Launch Kit), not hand-rolled static-pod loops),

• fresh-laptop-no-hardware users with no DOCA install yet — those

belong on

doca-setup ## no-install.

The skill teaches the agent the bare-metal-deployment *procedure*

and the rules for quoting documented commands from the public DOCA

Programming Guide and the public BlueField / DPU User Manual via

doca-public-knowledge-map;

it does not invent flag names, PCI BDFs, NUMA numbers, devlink

paths, representor strings, or systemd Restart= mode names from

memory.

When to load this skill

Load this skill when the user is doing **hands-on bare-metal

deployment of a DOCA-linked application binary** on either of the

two supported host modes (host x86 or BlueField Arm), or asking a

cross-cutting bare-metal question that is not specific to one

library's API. Concretely:

• Launching a DOCA-linked binary for the first time on a host

with a BlueField NIC in a PCIe slot, with DOCA installed on the

host.

• Launching a DOCA-linked binary on the BlueField Arm cores

directly (BlueField Arm bare-metal mode), with DOCA installed

on the Arm side per the BlueField OS image.

• Deciding which launch mode to use (direct foreground for

interactive debug; tmux/screen for long-running with manual

reattach; systemd-supervised for restart-after-reboot,

journald-integrated logs, and Restart= policy).

• Binding the DOCA process to the right PCIe function, the right

representor, the right NUMA node, and the right CPU set — and

pinning IRQs to match — without inventing the addresses or the

flag names.

• Setting up per-tenant isolation (cgroup-v2 cpu / memory / io

controllers, network namespaces for multi-tenant deployments,

numactl / taskset for CPU + NUMA binding) so multiple DOCA

processes co-tenant on the same BlueField without crushing each

other.

• Diagnosing a bare-metal launch that is misbehaving — won't

start, starts and exits immediately, runs but can't find the

device, attaches to the device but the workload errors, OOMs or

is signal-killed, is in a restart loop under a supervisor, or

is being interfered with by a co-tenant.

• Cross-cutting questions: *"should I run this in tmux or as a

systemd unit"*, *"what is the smoke-before-bulk loop for a

binary on bare metal"*, *"my binary works in a container on the

BlueField but not when I run it directly on the Arm — what

changed"*.

Do not load this skill for the container-path equivalent

(those questions go to

doca-container-deployment);

for full-Kubernetes-cluster operations (out of scope per the

bundle's non-goals); for library-API questions (route to the

matching libs/<library> skill); for env-preparation questions

including hugepages, IOMMU, pkg-config, and devlink mode flips

(use doca-setup); for any

hardware-state-changing operation including mlxconfig writes

and BFB reflashes (route to

doca-hardware-safety for the

cross-cutting meta-policy); or for cross-library programming

questions (use

doca-programming-guide).

What this skill provides

This is a thin loader. Substantive material lives in two

companion files:

• CAPABILITIES.md — the bare-metal deployment runtime contract

for a DOCA-linked binary: the two host modes (host x86 vs

BlueField Arm bare-metal), the three launch modes (direct,

tmux/screen, systemd-supervised), the hardware-resource-binding

surface (PF / VF / representor enumeration; NUMA topology

discovery; CPU pinning rationale; IRQ affinity rules), the

per-tenant isolation surface (cgroup-v2 cpu / memory / io,

network namespaces, numactl / taskset), the restart and

recovery semantics (documented systemd Restart= modes vs

crash-and-investigate vs supervisor-driven restart), the

bare-metal-specific version overlay on the four-way version

match owned by

doca-version, the cross-cutting

error taxonomy (seven layers, walked in order), the observability

surface (stdout/stderr discipline by launch mode; device-state

introspection via devlink / sysfs / mlxconfig *query*;

per-tenant resource visibility), and the safety policy (overlay

on

doca-hardware-safety:

smoke-before-bulk for binaries; failed bare-metal process is

HIGH-STAKES; do not invent PCI addresses, NUMA numbers,

representor names, devlink paths, or systemd Restart= mode

names; confirm tenant-isolation primitives BEFORE the workload

starts).

• TASKS.md — step-by-step workflows for the in-scope bare-metal

verbs: configure, build, modify, run (with an explicit

### isolation sub-anchor covering cgroup-v2 / namespaces /

numactl per-tenant primitives), test, debug,

bluefield-lifecycle (the BFB-install → RShim/TMFIFO →

post-BFB-recovery operational sequencing ladder, with the

six-state bluefield-state-classifier sub-anchor), the

Command appendix (documented commands the agent may quote,

each cross-linked to its public-doc source — no invented

commands), and the Deferred task verbs block routing

container-path / cluster / library-API / env-prep /

hardware-state-change / cross-library questions out to their

owning skills. (The change-application discipline for any

mutating burn invoked from ## bluefield-lifecycle is still

meta-policy owned by

doca-hardware-safety,

loaded alongside.)

The skill assumes a host or BlueField target where:

• DOCA is already installed and healthy (per

doca-setup ## test),

• the user has a DOCA-linked application binary they built (per

doca-programming-guide ## build),

• the user has the host-OS permissions to enumerate devices,

reserve hugepages, write systemd units (if they choose that

launch mode), and bind processes to NUMA nodes.

It does not cover installing DOCA — that path goes through

doca-setup — and it does not cover

building the binary — that path goes through

doca-programming-guide.

Loading order

• Read this SKILL.md first to confirm the user's question is

in scope (bare-metal launch of a DOCA-linked binary on host

x86 or BlueField Arm; NOT the container path, NOT a full

cluster, NOT a library-API question).

• **For the runtime contract (two host modes, three launch

modes, hardware-binding surface, per-tenant isolation, version

overlay, seven-layer error taxonomy, observability surface,

bare-metal safety overlay), see

CAPABILITIES.md.**

• **For step-by-step workflows — configure, build (routing

stub), modify (routing stub), run (with ### isolation

sub-anchor), test, debug, bluefield-lifecycle (BFB

install + RShim/TMFIFO + post-BFB recovery + the six-state

bluefield-state-classifier), plus the Command appendix and

the Deferred task verbs block — see TASKS.md.**

Example questions this skill answers well

See references/details.md.

What this skill deliberately does not ship

See references/details.md.

Related skills

See references/details.md.